migrate Clock classes to API

examples/disabling_sdk.php

@@ -4,11 +4,11 @@
 
 namespace OpenTelemetry\Example;
 
+use OpenTelemetry\API\Common\Time\ClockFactory;
 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;

examples/logs/exporters/otlp_grpc.php

@@ -4,6 +4,7 @@
 
 namespace OpenTelemetry\Example;
 
+use OpenTelemetry\API\Common\Time\ClockFactory;
 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;

examples/logs/features/batch_exporting.php

@@ -4,11 +4,11 @@
 
 namespace OpenTelemetry\Example;
 
+use OpenTelemetry\API\Common\Time\ClockFactory;
 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;

examples/metrics/basic.php

@@ -7,11 +7,11 @@
 
 require_once __DIR__ . '/../../vendor/autoload.php';
 
+use OpenTelemetry\API\Common\Time\ClockFactory;
 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;

examples/metrics/exporters/otlp_grpc.php

@@ -6,11 +6,11 @@
 
 require __DIR__ . '/../../../vendor/autoload.php';
 
+use OpenTelemetry\API\Common\Time\ClockFactory;
 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();

examples/metrics/exporters/otlp_http.php

@@ -6,9 +6,9 @@
 
 require __DIR__ . '/../../../vendor/autoload.php';
 
+use OpenTelemetry\API\Common\Time\ClockFactory;
 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();

examples/metrics/exporters/stream.php

@@ -6,9 +6,9 @@
 
 require __DIR__ . '/../../../vendor/autoload.php';
 
+use OpenTelemetry\API\Common\Time\ClockFactory;
 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();

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;

examples/traces/exporters/otlp_file.php

@@ -6,10 +6,10 @@
 
 require __DIR__ . '/../../../vendor/autoload.php';
 
+use OpenTelemetry\API\Common\Time\ClockFactory;
 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;
 

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\ClockFactory;
 use OpenTelemetry\SDK\Trace\SpanExporter\ConsoleSpanExporterFactory;
 use OpenTelemetry\SDK\Trace\SpanProcessor\BatchSpanProcessor;
 use OpenTelemetry\SDK\Trace\TracerProvider;

examples/troubleshooting/logging_of_span_data.php

@@ -17,9 +17,9 @@
  * will be the last log entry
  */
 
+use OpenTelemetry\API\Common\Time\ClockFactory;
 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;

src/API/Common/Time/ClockFactory.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\API\Common\Time;
+
+final class ClockFactory implements ClockFactoryInterface
+{
+    private static ?ClockInterface $default = null;
+
+    public static function create(): self
+    {
+        return new self();
+    }
+
+    public function build(): ClockInterface
+    {
+        return new SystemClock();
+    }
+
+    public static function getDefault(): ClockInterface
+    {
+        return self::$default ?? self::$default = self::create()->build();
+    }
+
+    public static function setDefault(?ClockInterface $clock): void
+    {
+        self::$default = $clock;
+    }
+}

src/API/Common/Time/ClockFactoryInterface.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\API\Common\Time;
+
+interface ClockFactoryInterface
+{
+    public static function create(): self;
+
+    public function build(): ClockInterface;
+
+    public static function getDefault(): ClockInterface;
+
+    public static function setDefault(?ClockInterface $clock): void;
+}

src/API/Common/Time/ClockInterface.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\API\Common\Time;
+
+interface ClockInterface
+{
+    public const MILLIS_PER_SECOND = 1_000;
+    public const MICROS_PER_SECOND = 1_000_000;
+    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;
+}

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;

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;
-    }
 }

src/API/Common/Time/Util.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\API\Common\Time;
+
+class Util
+{
+    /** @psalm-pure */
+    public static function nanosToMicros(int $nanoseconds): int
+    {
+        return intdiv($nanoseconds, ClockInterface::NANOS_PER_MICROSECOND);
+    }
+
+    /** @psalm-pure */
+    public static function nanosToMillis(int $nanoseconds): int
+    {
+        return intdiv($nanoseconds, ClockInterface::NANOS_PER_MILLISECOND);
+    }
+
+    /** @psalm-pure */
+    public static function secondsToNanos(int $seconds): int
+    {
+        return $seconds * ClockInterface::NANOS_PER_SECOND;
+    }
+
+    /** @psalm-pure */
+    public static function millisToNanos(int $milliSeconds): int
+    {
+        return $milliSeconds * ClockInterface::NANOS_PER_MILLISECOND;
+    }
+}

src/Config/SDK/ComponentProvider/Logs/LogRecordProcessorBatch.php

@@ -4,11 +4,11 @@
 
 namespace OpenTelemetry\Config\SDK\ComponentProvider\Logs;
 
+use OpenTelemetry\API\Common\Time\ClockFactory;
 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;

src/Config/SDK/ComponentProvider/OpenTelemetrySdk.php

@@ -4,6 +4,7 @@
 
 namespace OpenTelemetry\Config\SDK\ComponentProvider;
 
+use OpenTelemetry\API\Common\Time\ClockFactory;
 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;

src/Config/SDK/ComponentProvider/Trace/SpanProcessorBatch.php

@@ -4,11 +4,11 @@
 
 namespace OpenTelemetry\Config\SDK\ComponentProvider\Trace;
 
+use OpenTelemetry\API\Common\Time\ClockFactory;
 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;

src/Contrib/Zipkin/SpanConverter.php

@@ -5,10 +5,10 @@
 namespace OpenTelemetry\Contrib\Zipkin;
 
 use function max;
+use OpenTelemetry\API\Common\Time\Util as TimeUtil;
 use OpenTelemetry\API\Trace\SpanKind;
 use OpenTelemetry\API\Trace\StatusCode;
 use OpenTelemetry\Contrib\Zipkin\SpanKind as ZipkinSpanKind;
-use OpenTelemetry\SDK\Common\Time\Util as TimeUtil;
 use OpenTelemetry\SDK\Resource\ResourceInfoFactory;
 use OpenTelemetry\SDK\Trace\EventInterface;
 use OpenTelemetry\SDK\Trace\SpanConverterInterface;

src/SDK/Common/Time/ClockFactory.php

@@ -4,27 +4,31 @@
 
 namespace OpenTelemetry\SDK\Common\Time;
 
-final class ClockFactory implements ClockFactoryInterface
-{
-    private static ?ClockInterface $default = null;
+use OpenTelemetry\API\Common\Time as API;
 
-    public static function create(): self
+/**
+ * @deprecated Use OpenTelemetry\API\Common\Time\ClockFactory
+ * @codeCoverageIgnore
+ */
+class ClockFactory implements API\ClockFactoryInterface
+{
+    public static function getDefault(): API\ClockInterface
     {
-        return new self();
+        return API\ClockFactory::getDefault();
     }
 
-    public function build(): ClockInterface
+    public static function create(): API\ClockFactoryInterface
     {
-        return new SystemClock();
+        return API\ClockFactory::create();
     }
 
-    public static function getDefault(): ClockInterface
+    public function build(): API\ClockInterface
     {
-        return self::$default ?? self::$default = self::create()->build();
+        return (new API\ClockFactory())->build();
     }
 
-    public static function setDefault(?ClockInterface $clock): void
+    public static function setDefault(?API\ClockInterface $clock): void
     {
-        self::$default = $clock;
+        API\ClockFactory::setDefault($clock);
     }
 }

src/SDK/Common/Time/ClockFactoryInterface.php

@@ -4,13 +4,11 @@
 
 namespace OpenTelemetry\SDK\Common\Time;
 
-interface ClockFactoryInterface
-{
-    public static function create(): self;
-
-    public function build(): ClockInterface;
+use OpenTelemetry\API\Common\Time\ClockFactoryInterface as API;
 
-    public static function getDefault(): ClockInterface;
-
-    public static function setDefault(?ClockInterface $clock): void;
+/**
+ * @deprecated Use OpenTelemetry\API\Common\Time\ClockFactoryInterface
+ */
+interface ClockFactoryInterface extends API
+{
 }