migrate Clock classes to API (open-telemetry#1281)

* migrate Clock classes to API - move Clock* + Util into API - add a deprecated wrapper for ClockFactory and Util - remove unused StopWatch* classes * review feedback * replace ClockFactory with Clock It's not really a factory, and really only provides access to a system clock. Create a Clock class which is more clear in its purpose. * remove time Util class per review feedback, it's only used in Zipkin. Removed some unused consts from ClockInterface * Apply suggestions from code review Co-authored-by: Tobias Bachert <[email protected]> --------- Co-authored-by: Tobias Bachert <[email protected]>
brettmc · Apr 29, 2024 · fc161a8 · fc161a8
1 parent 9fe6aa0
commit fc161a8
Show file tree

Hide file tree

Showing 59 changed files with 212 additions and 735 deletions.
diff --git a/examples/disabling_sdk.php b/examples/disabling_sdk.php
@@ -4,11 +4,11 @@
 
 namespace OpenTelemetry\Example;
 
+use OpenTelemetry\API\Common\Time\Clock;
 use OpenTelemetry\Contrib\Otlp\MetricExporter;
 use OpenTelemetry\SDK\Common\Attribute\Attributes;
 use OpenTelemetry\SDK\Common\Export\Stream\StreamTransportFactory;
 use OpenTelemetry\SDK\Common\Instrumentation\InstrumentationScopeFactory;
-use OpenTelemetry\SDK\Common\Time\ClockFactory;
 use OpenTelemetry\SDK\Metrics\Exemplar\ExemplarFilter\WithSampledTraceExemplarFilter;
 use OpenTelemetry\SDK\Metrics\MeterProvider;
 use OpenTelemetry\SDK\Metrics\MetricReader\ExportingReader;
@@ -29,7 +29,7 @@
 echo get_class($tracer) . PHP_EOL;
 
 //metrics
-$clock = ClockFactory::getDefault();
+$clock = Clock::getDefault();
 $reader = new ExportingReader(new MetricExporter((new StreamTransportFactory())->create(STDOUT, 'application/x-ndjson')));
 $views = new CriteriaViewRegistry();
 $meterProvider = new MeterProvider(

diff --git a/examples/logs/exporters/otlp_grpc.php b/examples/logs/exporters/otlp_grpc.php
@@ -4,6 +4,7 @@
 
 namespace OpenTelemetry\Example;
 
+use OpenTelemetry\API\Common\Time\Clock;
 use OpenTelemetry\API\Logs\EventLogger;
 use OpenTelemetry\API\Logs\LogRecord;
 use OpenTelemetry\API\Signals;
@@ -12,7 +13,6 @@
 use OpenTelemetry\Contrib\Otlp\OtlpUtil;
 use Opentelemetry\Proto\Logs\V1\SeverityNumber;
 use OpenTelemetry\SDK\Common\Instrumentation\InstrumentationScopeFactory;
-use OpenTelemetry\SDK\Common\Time\ClockFactory;
 use OpenTelemetry\SDK\Logs\LoggerProvider;
 use OpenTelemetry\SDK\Logs\LogRecordLimitsBuilder;
 use OpenTelemetry\SDK\Logs\Processor\BatchLogRecordProcessor;
@@ -24,7 +24,7 @@
 $loggerProvider = new LoggerProvider(
     new BatchLogRecordProcessor(
         $exporter,
-        ClockFactory::getDefault()
+        Clock::getDefault()
     ),
     new InstrumentationScopeFactory(
         (new LogRecordLimitsBuilder())->build()->getAttributeFactory()

diff --git a/examples/logs/features/batch_exporting.php b/examples/logs/features/batch_exporting.php
@@ -4,11 +4,11 @@
 
 namespace OpenTelemetry\Example;
 
+use OpenTelemetry\API\Common\Time\Clock;
 use OpenTelemetry\API\Logs\EventLogger;
 use OpenTelemetry\API\Logs\LogRecord;
 use OpenTelemetry\SDK\Common\Attribute\Attributes;
 use OpenTelemetry\SDK\Common\Instrumentation\InstrumentationScopeFactory;
-use OpenTelemetry\SDK\Common\Time\ClockFactory;
 use OpenTelemetry\SDK\Logs\Exporter\ConsoleExporterFactory;
 use OpenTelemetry\SDK\Logs\LoggerProvider;
 use OpenTelemetry\SDK\Logs\Processor\BatchLogRecordProcessor;
@@ -18,7 +18,7 @@
 $loggerProvider = new LoggerProvider(
     new BatchLogRecordProcessor(
         (new ConsoleExporterFactory())->create(),
-        ClockFactory::getDefault()
+        Clock::getDefault()
     ),
     new InstrumentationScopeFactory(Attributes::factory())
 );

diff --git a/examples/metrics/basic.php b/examples/metrics/basic.php
@@ -7,11 +7,11 @@
 
 require_once __DIR__ . '/../../vendor/autoload.php';
 
+use OpenTelemetry\API\Common\Time\Clock;
 use OpenTelemetry\Contrib\Otlp\MetricExporter;
 use OpenTelemetry\SDK\Common\Attribute\Attributes;
 use OpenTelemetry\SDK\Common\Export\Stream\StreamTransportFactory;
 use OpenTelemetry\SDK\Common\Instrumentation\InstrumentationScopeFactory;
-use OpenTelemetry\SDK\Common\Time\ClockFactory;
 use OpenTelemetry\SDK\Metrics\Aggregation\ExplicitBucketHistogramAggregation;
 use OpenTelemetry\SDK\Metrics\Exemplar\ExemplarFilter\WithSampledTraceExemplarFilter;
 use OpenTelemetry\SDK\Metrics\MeterProvider;
@@ -22,7 +22,7 @@
 use OpenTelemetry\SDK\Metrics\View\ViewTemplate;
 use OpenTelemetry\SDK\Resource\ResourceInfoFactory;
 
-$clock = ClockFactory::getDefault();
+$clock = Clock::getDefault();
 $reader = new ExportingReader(new MetricExporter((new StreamTransportFactory())->create(STDOUT, 'application/x-ndjson'), /*Temporality::CUMULATIVE*/));
 
 // Let's imagine we export the metrics as Histogram, and to simplify the story we will only have one histogram bucket (-Inf, +Inf):

diff --git a/examples/metrics/exporters/otlp_grpc.php b/examples/metrics/exporters/otlp_grpc.php
@@ -6,14 +6,14 @@
 
 require __DIR__ . '/../../../vendor/autoload.php';
 
+use OpenTelemetry\API\Common\Time\Clock;
 use OpenTelemetry\API\Signals;
 use OpenTelemetry\Contrib\Grpc\GrpcTransportFactory;
 use OpenTelemetry\Contrib\Otlp\MetricExporter;
 use OpenTelemetry\Contrib\Otlp\OtlpUtil;
-use OpenTelemetry\SDK\Common\Time\ClockFactory;
 use OpenTelemetry\SDK\Metrics\MetricReader\ExportingReader;
 
-$clock = ClockFactory::getDefault();
+$clock = Clock::getDefault();
 
 $reader = new ExportingReader(
     new MetricExporter(

diff --git a/examples/metrics/exporters/otlp_http.php b/examples/metrics/exporters/otlp_http.php
@@ -6,12 +6,12 @@
 
 require __DIR__ . '/../../../vendor/autoload.php';
 
+use OpenTelemetry\API\Common\Time\Clock;
 use OpenTelemetry\Contrib\Otlp\MetricExporter;
 use OpenTelemetry\SDK\Common\Export\Http\PsrTransportFactory;
-use OpenTelemetry\SDK\Common\Time\ClockFactory;
 use OpenTelemetry\SDK\Metrics\MetricReader\ExportingReader;
 
-$clock = ClockFactory::getDefault();
+$clock = Clock::getDefault();
 $reader = new ExportingReader(
     new MetricExporter(
         (new PsrTransportFactory())->create('http://collector:4318/v1/metrics', \OpenTelemetry\Contrib\Otlp\ContentTypes::JSON)

diff --git a/examples/metrics/exporters/stream.php b/examples/metrics/exporters/stream.php
@@ -6,12 +6,12 @@
 
 require __DIR__ . '/../../../vendor/autoload.php';
 
+use OpenTelemetry\API\Common\Time\Clock;
 use OpenTelemetry\Contrib\Otlp\MetricExporter;
 use OpenTelemetry\SDK\Common\Export\Stream\StreamTransportFactory;
-use OpenTelemetry\SDK\Common\Time\ClockFactory;
 use OpenTelemetry\SDK\Metrics\MetricReader\ExportingReader;
 
-$clock = ClockFactory::getDefault();
+$clock = Clock::getDefault();
 // @psalm-suppress InternalMethod
 $reader = new ExportingReader(
     new MetricExporter(

diff --git a/examples/src/ExampleMetricsGenerator.php b/examples/src/ExampleMetricsGenerator.php
@@ -4,10 +4,10 @@
 
 namespace OpenTelemetry\Example;
 
+use OpenTelemetry\API\Common\Time\ClockInterface;
 use OpenTelemetry\API\Metrics\ObserverInterface;
 use OpenTelemetry\SDK\Common\Attribute\Attributes;
 use OpenTelemetry\SDK\Common\Instrumentation\InstrumentationScopeFactory;
-use OpenTelemetry\SDK\Common\Time\ClockInterface;
 use OpenTelemetry\SDK\Metrics\Exemplar\ExemplarFilter\WithSampledTraceExemplarFilter;
 use OpenTelemetry\SDK\Metrics\MeterProvider;
 use OpenTelemetry\SDK\Metrics\MetricReader\ExportingReader;

diff --git a/examples/traces/exporters/otlp_file.php b/examples/traces/exporters/otlp_file.php
@@ -6,10 +6,10 @@
 
 require __DIR__ . '/../../../vendor/autoload.php';
 
+use OpenTelemetry\API\Common\Time\Clock;
 use OpenTelemetry\Contrib\Otlp\ContentTypes;
 use OpenTelemetry\Contrib\Otlp\SpanExporter;
 use OpenTelemetry\SDK\Common\Export\Stream\StreamTransportFactory;
-use OpenTelemetry\SDK\Common\Time\ClockFactory;
 use OpenTelemetry\SDK\Trace\SpanProcessor\BatchSpanProcessor;
 use OpenTelemetry\SDK\Trace\TracerProvider;
 
@@ -23,7 +23,7 @@
 $tracerProvider =  new TracerProvider(
     new BatchSpanProcessor(
         $exporter,
-        ClockFactory::getDefault()
+        Clock::getDefault()
     )
 );
 $tracer = $tracerProvider->getTracer('io.opentelemetry.contrib.php');

diff --git a/examples/traces/features/batch_exporting.php b/examples/traces/features/batch_exporting.php
@@ -6,7 +6,7 @@
 
 require __DIR__ . '/../../../vendor/autoload.php';
 
-use OpenTelemetry\SDK\Common\Time\ClockFactory;
+use OpenTelemetry\API\Common\Time\Clock;
 use OpenTelemetry\SDK\Trace\SpanExporter\ConsoleSpanExporterFactory;
 use OpenTelemetry\SDK\Trace\SpanProcessor\BatchSpanProcessor;
 use OpenTelemetry\SDK\Trace\TracerProvider;
@@ -19,7 +19,7 @@
 $tracerProvider = new TracerProvider(
     new BatchSpanProcessor(
         (new ConsoleSpanExporterFactory())->create(),
-        ClockFactory::getDefault(),
+        Clock::getDefault(),
         2048, //max spans to queue before sending to exporter
         $delayMillis, //batch delay milliseconds
     )

diff --git a/examples/troubleshooting/logging_of_span_data.php b/examples/troubleshooting/logging_of_span_data.php
@@ -17,9 +17,9 @@
  * will be the last log entry
  */
 
+use OpenTelemetry\API\Common\Time\Clock;
 use OpenTelemetry\Contrib\Zipkin\Exporter as ZipkinExporter;
 use OpenTelemetry\SDK\Common\Export\Http\PsrTransportFactory;
-use OpenTelemetry\SDK\Common\Time\ClockFactory;
 use OpenTelemetry\SDK\Logs\SimplePsrFileLogger;
 use OpenTelemetry\SDK\Trace\Sampler\AlwaysOnSampler;
 use OpenTelemetry\SDK\Trace\SpanExporter\LoggerDecorator;
@@ -57,7 +57,7 @@
  * Create the Tracer
  */
 $tracerProvider = new TracerProvider(
-    new BatchSpanProcessor($decorator, ClockFactory::getDefault()),
+    new BatchSpanProcessor($decorator, Clock::getDefault()),
     new AlwaysOnSampler()
 );
 $tracer = $tracerProvider->getTracer('io.opentelemetry.contrib.php');

diff --git a/src/API/Common/Time/Clock.php b/src/API/Common/Time/Clock.php
@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\API\Common\Time;
+
+final class Clock
+{
+    private static ?ClockInterface $clock = null;
+
+    public static function getDefault(): ClockInterface
+    {
+        return self::$clock ??= new SystemClock();
+    }
+
+    public static function setDefault(ClockInterface $clock): void
+    {
+        self::$clock = $clock;
+    }
+
+    public static function reset(): void
+    {
+        self::$clock = null;
+    }
+}
diff --git a/src/API/Common/Time/ClockInterface.php b/src/API/Common/Time/ClockInterface.php
@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\API\Common\Time;
+
+interface ClockInterface
+{
+    public const NANOS_PER_SECOND = 1_000_000_000;
+    public const NANOS_PER_MILLISECOND = 1_000_000;
+    public const NANOS_PER_MICROSECOND = 1_000;
+
+    /**
+     * Returns the current epoch wall-clock timestamp in nanoseconds
+     */
+    public function now(): int;
+}
diff --git a/src/SDK/Common/Time/SystemClock.php → src/API/Common/Time/SystemClock.php b/src/SDK/Common/Time/SystemClock.php → src/API/Common/Time/SystemClock.php
@@ -2,11 +2,14 @@
 
 declare(strict_types=1);
 
-namespace OpenTelemetry\SDK\Common\Time;
+namespace OpenTelemetry\API\Common\Time;
 
 use function hrtime;
 use function microtime;
 
+/**
+ * @internal OpenTelemetry
+ */
 final class SystemClock implements ClockInterface
 {
     private static int $referenceTime = 0;

diff --git a/tests/Unit/SDK/Util/TestClock.php → src/API/Common/Time/TestClock.php b/tests/Unit/SDK/Util/TestClock.php → src/API/Common/Time/TestClock.php
@@ -2,10 +2,11 @@
 
 declare(strict_types=1);
 
-namespace OpenTelemetry\Tests\Unit\SDK\Util;
-
-use OpenTelemetry\SDK\Common\Time\ClockInterface;
+namespace OpenTelemetry\API\Common\Time;
 
+/**
+ * @internal OpenTelemetry
+ */
 final class TestClock implements ClockInterface
 {
     public const DEFAULT_START_EPOCH = 1633060331386955008; // Fri Oct 01 2021 03:52:11 UTC
@@ -36,9 +37,4 @@ public function now(): int
     {
         return $this->currentEpochNanos;
     }
-
-    public function nanoTime(): int
-    {
-        return $this->currentEpochNanos;
-    }
 }
diff --git a/src/Config/SDK/ComponentProvider/Logs/LogRecordProcessorBatch.php b/src/Config/SDK/ComponentProvider/Logs/LogRecordProcessorBatch.php
@@ -4,11 +4,11 @@
 
 namespace OpenTelemetry\Config\SDK\ComponentProvider\Logs;
 
+use OpenTelemetry\API\Common\Time\Clock;
 use OpenTelemetry\Config\SDK\Configuration\ComponentPlugin;
 use OpenTelemetry\Config\SDK\Configuration\ComponentProvider;
 use OpenTelemetry\Config\SDK\Configuration\ComponentProviderRegistry;
 use OpenTelemetry\Config\SDK\Configuration\Context;
-use OpenTelemetry\SDK\Common\Time\ClockFactory;
 use OpenTelemetry\SDK\Logs\LogRecordExporterInterface;
 use OpenTelemetry\SDK\Logs\LogRecordProcessorInterface;
 use OpenTelemetry\SDK\Logs\Processor\BatchLogRecordProcessor;
@@ -33,7 +33,7 @@ public function createPlugin(array $properties, Context $context): LogRecordProc
     {
         return new BatchLogRecordProcessor(
             exporter: $properties['exporter']->create($context),
-            clock: ClockFactory::getDefault(),
+            clock: Clock::getDefault(),
             maxQueueSize: $properties['max_queue_size'],
             scheduledDelayMillis: $properties['schedule_delay'],
             exportTimeoutMillis: $properties['export_timeout'],

diff --git a/src/Config/SDK/ComponentProvider/OpenTelemetrySdk.php b/src/Config/SDK/ComponentProvider/OpenTelemetrySdk.php
@@ -4,6 +4,7 @@
 
 namespace OpenTelemetry\Config\SDK\ComponentProvider;
 
+use OpenTelemetry\API\Common\Time\Clock;
 use OpenTelemetry\Config\SDK\Configuration\ComponentPlugin;
 use OpenTelemetry\Config\SDK\Configuration\ComponentProvider;
 use OpenTelemetry\Config\SDK\Configuration\ComponentProviderRegistry;
@@ -13,7 +14,6 @@
 use OpenTelemetry\Context\Propagation\TextMapPropagatorInterface;
 use OpenTelemetry\SDK\Common\Attribute\Attributes;
 use OpenTelemetry\SDK\Common\Instrumentation\InstrumentationScopeFactory;
-use OpenTelemetry\SDK\Common\Time\ClockFactory;
 use OpenTelemetry\SDK\Logs\LoggerProvider;
 use OpenTelemetry\SDK\Logs\LogRecordProcessorInterface;
 use OpenTelemetry\SDK\Logs\Processor\MultiLogRecordProcessor;
@@ -215,7 +215,7 @@ public function createPlugin(array $properties, Context $context): SdkBuilder
         $meterProvider = new MeterProvider(
             contextStorage: null,
             resource: $resource,
-            clock: ClockFactory::getDefault(),
+            clock: Clock::getDefault(),
             attributesFactory: Attributes::factory(),
             instrumentationScopeFactory: new InstrumentationScopeFactory(Attributes::factory()),
             metricReaders: $metricReaders, // @phpstan-ignore-line

diff --git a/src/Config/SDK/ComponentProvider/Trace/SpanProcessorBatch.php b/src/Config/SDK/ComponentProvider/Trace/SpanProcessorBatch.php
@@ -4,11 +4,11 @@
 
 namespace OpenTelemetry\Config\SDK\ComponentProvider\Trace;
 
+use OpenTelemetry\API\Common\Time\Clock;
 use OpenTelemetry\Config\SDK\Configuration\ComponentPlugin;
 use OpenTelemetry\Config\SDK\Configuration\ComponentProvider;
 use OpenTelemetry\Config\SDK\Configuration\ComponentProviderRegistry;
 use OpenTelemetry\Config\SDK\Configuration\Context;
-use OpenTelemetry\SDK\Common\Time\ClockFactory;
 use OpenTelemetry\SDK\Trace\SpanExporterInterface;
 use OpenTelemetry\SDK\Trace\SpanProcessor\BatchSpanProcessor;
 use OpenTelemetry\SDK\Trace\SpanProcessorInterface;
@@ -33,7 +33,7 @@ public function createPlugin(array $properties, Context $context): SpanProcessor
     {
         return new BatchSpanProcessor(
             exporter: $properties['exporter']->create($context),
-            clock: ClockFactory::getDefault(),
+            clock: Clock::getDefault(),
             maxQueueSize: $properties['max_queue_size'],
             scheduledDelayMillis: $properties['schedule_delay'],
             exportTimeoutMillis: $properties['export_timeout'],