add enabled functions (#1350)

* add enabled function
spec 1.34 requires logger, tracer, and instrument to have an enabled function

* Update src/API/Metrics/Instrument.php

Co-authored-by: Tobias Bachert <[email protected]>

* adjust instrument enabled logic

---------

Co-authored-by: Tobias Bachert <[email protected]>

src/API/Logs/LoggerInterface.php

@@ -11,4 +11,11 @@ interface LoggerInterface
      * @see https://github.com/open-telemetry/opentelemetry-specification/blob/v1.32.0/specification/logs/bridge-api.md#artifact-naming
      */
     public function emit(LogRecord $logRecord): void;
+
+    /**
+     * Determine if the logger is enabled. Logs bridge API authors SHOULD call this method each time they
+     * are about to generate a LogRecord, to avoid performing computationally expensive work.
+     * @experimental
+     */
+    public function enabled(): bool;
 }

src/API/Logs/NoopLogger.php

@@ -30,4 +30,9 @@ public function emit(LogRecord $logRecord): void
     public function log($level, $message, array $context = []): void
     {
     }
+
+    public function enabled(): bool
+    {
+        return false;
+    }
 }

src/API/Metrics/AsynchronousInstrument.php

@@ -7,6 +7,6 @@
 /**
  * Marker interface for asynchronous instruments.
  */
-interface AsynchronousInstrument
+interface AsynchronousInstrument extends Instrument
 {
 }

src/API/Metrics/Instrument.php

@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\API\Metrics;
+
+interface Instrument
+{
+    /**
+     * Determine if the instrument is enabled. Instrumentation authors SHOULD call this API each time they record a measurement.
+     * @experimental
+     */
+    public function enabled(): bool;
+}

src/API/Metrics/Noop/NoopCounter.php

@@ -15,4 +15,9 @@ public function add($amount, iterable $attributes = [], $context = null): void
     {
         // no-op
     }
+
+    public function enabled(): bool
+    {
+        return false;
+    }
 }

src/API/Metrics/Noop/NoopHistogram.php

@@ -15,4 +15,9 @@ public function record($amount, iterable $attributes = [], $context = null): voi
     {
         // no-op
     }
+
+    public function enabled(): bool
+    {
+        return false;
+    }
 }

src/API/Metrics/Noop/NoopObservableCounter.php

@@ -16,4 +16,9 @@ public function observe(callable $callback, bool $weaken = false): ObservableCal
     {
         return new NoopObservableCallback();
     }
+
+    public function enabled(): bool
+    {
+        return false;
+    }
 }

src/API/Metrics/Noop/NoopObservableGauge.php

@@ -16,4 +16,9 @@ public function observe(callable $callback, bool $weaken = false): ObservableCal
     {
         return new NoopObservableCallback();
     }
+
+    public function enabled(): bool
+    {
+        return false;
+    }
 }

src/API/Metrics/Noop/NoopObservableUpDownCounter.php

@@ -16,4 +16,9 @@ public function observe(callable $callback, bool $weaken = false): ObservableCal
     {
         return new NoopObservableCallback();
     }
+
+    public function enabled(): bool
+    {
+        return false;
+    }
 }

src/API/Metrics/Noop/NoopUpDownCounter.php

@@ -15,4 +15,9 @@ public function add($amount, iterable $attributes = [], $context = null): void
     {
         // no-op
     }
+
+    public function enabled(): bool
+    {
+        return false;
+    }
 }

src/API/Metrics/SynchronousInstrument.php

@@ -7,6 +7,6 @@
 /**
  * Marker interface for synchronous instruments.
  */
-interface SynchronousInstrument
+interface SynchronousInstrument extends Instrument
 {
 }

src/API/Trace/NoopTracer.php

@@ -23,4 +23,9 @@ public function spanBuilder(string $spanName): SpanBuilderInterface
     {
         return new NoopSpanBuilder(Context::storage());
     }
+
+    public function enabled(): bool
+    {
+        return false;
+    }
 }

src/API/Trace/TracerInterface.php

@@ -8,4 +8,11 @@ interface TracerInterface
 {
     /** @param non-empty-string $spanName */
     public function spanBuilder(string $spanName): SpanBuilderInterface;
+
+    /**
+     * Determine if the tracer is enabled. Instrumentation authors SHOULD call this method prior to
+     * creating a new span.
+     * @experimental
+     */
+    public function enabled(): bool;
 }

src/SDK/Logs/Logger.php

@@ -42,4 +42,9 @@ public function emit(LogRecord $logRecord): void
             ]);
         }
     }
+
+    public function enabled(): bool
+    {
+        return true;
+    }
 }

src/SDK/Metrics/DefaultAggregationProviderTrait.php

@@ -15,6 +15,5 @@ public function defaultAggregation($instrumentType, array $advisory = []): ?Aggr
             InstrumentType::GAUGE, InstrumentType::ASYNCHRONOUS_GAUGE => new Aggregation\LastValueAggregation(),
             default => null,
         };
-        // @codeCoverageIgnoreEnd
     }
 }

src/SDK/Metrics/MetricRegistry/MetricRegistry.php

@@ -174,4 +174,9 @@ public function collectAndPush(iterable $streamIds): void
             }
         }
     }
+
+    public function enabled(Instrument $instrument): bool
+    {
+        return isset($this->instrumentToStreams[spl_object_id($instrument)]);
+    }
 }

src/SDK/Metrics/MetricRegistry/MetricWriterInterface.php

@@ -17,4 +17,5 @@ public function record(Instrument $instrument, $value, iterable $attributes = []
     public function registerCallback(Closure $callback, Instrument $instrument, Instrument ...$instruments): int;
 
     public function unregisterCallback(int $callbackId): void;
+    public function enabled(Instrument $instrument): bool;
 }

src/SDK/Metrics/ObservableInstrumentTrait.php

@@ -59,4 +59,9 @@ public function observe(callable $callback): ObservableCallbackInterface
             $this->referenceCounter,
         );
     }
+
+    public function enabled(): bool
+    {
+        return $this->writer->enabled($this->instrument);
+    }
 }

src/SDK/Metrics/SynchronousInstrumentTrait.php

@@ -41,4 +41,9 @@ public function write($amount, iterable $attributes = [], $context = null): void
     {
         $this->writer->record($this->instrument, $amount, $attributes, $context);
     }
+
+    public function enabled(): bool
+    {
+        return true;
+    }
 }

src/SDK/Trace/Tracer.php

@@ -41,4 +41,9 @@ public function getInstrumentationScope(): InstrumentationScopeInterface
     {
         return $this->instrumentationScope;
     }
+
+    public function enabled(): bool
+    {
+        return true;
+    }
 }

tests/Unit/API/Logs/NoopLoggerTest.php

@@ -2,7 +2,7 @@
 
 declare(strict_types=1);
 
-namespace OpenTelemetry\Example\Unit\API\Logs;
+namespace OpenTelemetry\Tests\Unit\API\Logs;
 
 use OpenTelemetry\API\Logs\NoopLogger;
 use PHPUnit\Framework\Attributes\CoversClass;
@@ -15,4 +15,9 @@ public function test_get_instance(): void
     {
         $this->assertInstanceOf(NoopLogger::class, NoopLogger::getInstance());
     }
+
+    public function test_enabled(): void
+    {
+        $this->assertFalse(NoopLogger::getInstance()->enabled());
+    }
 }

tests/Unit/API/Trace/NoopTracerTest.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\Tests\Unit\API\Trace;
+
+use OpenTelemetry\API\Trace\NoopSpanBuilder;
+use OpenTelemetry\API\Trace\NoopTracer;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(NoopTracer::class)]
+class NoopTracerTest extends TestCase
+{
+    public function test_get_instance(): void
+    {
+        $this->assertSame(NoopTracer::getInstance(), NoopTracer::getInstance());
+    }
+
+    public function test_span_builder(): void
+    {
+        $this->assertInstanceOf(NoopSpanBuilder::class, NoopTracer::getInstance()->spanBuilder('test'));
+    }
+
+    public function test_enabled(): void
+    {
+        $this->assertFalse(NoopTracer::getInstance()->enabled());
+    }
+}

tests/Unit/SDK/Logs/LoggerTest.php

@@ -109,4 +109,10 @@ public function test_logs_dropped_attributes(): void
 
         $logger->emit($record);
     }
+
+    public function test_enabled(): void
+    {
+        $logger = new Logger($this->sharedState, $this->scope);
+        $this->assertTrue($logger->enabled());
+    }
 }

tests/Unit/SDK/Metrics/InstrumentTest.php

@@ -20,6 +20,7 @@
 use OpenTelemetry\SDK\Metrics\ObservableCallback;
 use OpenTelemetry\SDK\Metrics\ObservableCallbackDestructor;
 use OpenTelemetry\SDK\Metrics\ObservableCounter;
+use OpenTelemetry\SDK\Metrics\ObservableInstrumentTrait;
 use OpenTelemetry\SDK\Metrics\ReferenceCounterInterface;
 use OpenTelemetry\SDK\Metrics\StalenessHandler\NoopStalenessHandler;
 use OpenTelemetry\SDK\Metrics\Stream\MetricAggregator;
@@ -36,6 +37,7 @@
 #[CoversClass(UpDownCounter::class)]
 #[CoversClass(Histogram::class)]
 #[CoversClass(ObservableCallback::class)]
+#[CoversClass(ObservableInstrumentTrait::class)]
 final class InstrumentTest extends TestCase
 {
 
@@ -239,4 +241,25 @@ public function test_observable_callback_does_not_acquire_persistent_on_destruct
         /** @noinspection PhpExpressionResultUnusedInspection */
         new ObservableCallback($writer, $referenceCounter, 1, $callbackDestructor, new stdClass());
     }
+
+    public function test_synchronous_enabled(): void
+    {
+        $w = $this->createMock(MetricWriterInterface::class);
+        $c = $this->createMock(ReferenceCounterInterface::class);
+        $i = new Instrument(InstrumentType::UP_DOWN_COUNTER, 'test', null, null);
+        $counter = new Counter($w, $i, $c);
+
+        $this->assertTrue($counter->enabled());
+    }
+
+    public function test_asynchronous_enabled(): void
+    {
+        $w = $this->createMock(MetricWriterInterface::class);
+        $w->method('enabled')->willReturn(true);
+        $c = $this->createMock(ReferenceCounterInterface::class);
+        $i = new Instrument(InstrumentType::UP_DOWN_COUNTER, 'test', null, null);
+        $counter = new ObservableCounter($w, $i, $c, new WeakMap());
+
+        $this->assertTrue($counter->enabled());
+    }
 }

tests/Unit/SDK/Trace/TracerTest.php

@@ -63,4 +63,9 @@ public function test_returns_noop_span_builder_if_shared_state_is_shutdown(): vo
         $this->tracerSharedState->method('hasShutdown')->willReturn(true); //@phpstan-ignore-line
         $this->assertInstanceOf(NoopSpanBuilder::class, $this->tracer->spanBuilder('foo'));
     }
+
+    public function test_enabled(): void
+    {
+        $this->assertTrue($this->tracer->enabled());
+    }
 }