update default temporality to spec (#1715)

* update default temporality to spec
The spec requirements for temporality have changed since our implementation of metrics. Now, Cumulative is the preferred default.
A temporality preference of LowMemory is now in spec, which was partially implemented for declarative config, but not for environment-based
autoloading. Added some integration tests to validate temporality settings for different preference inputs.

Added some non-spec otlp transports (stdout/nd-json and memory/json), since they exercise more of the otlp metrics codebase than the existing
InMemory exporters, and made integration testing for temporality easier.

* remove invalid default OTEL_METRICS_EXPORTER, fix test name

* move test transports under tests/

* remove stream temporality

* tests

* temporality is a function of instrument kind

* temporality selection
centralize temporality selection into a trait and re-use across metric exporters
remove temporality as a function of stream type (spec now says that temporality is a function of
instrument + preference

* add check and warning that async callbacks must not return a value
...and add tests that gauges do not have a temporality

* add stdout factories

* remove unused stdout transport

* remove stdout transport, hash _register.php files

* update temporality upgrade docs

* use AggregationTemporalitySelectorInterface to provide temporality preference
based on opentelemetry-java's implementation, the spec-defined preferences are defined in
SDK/Metrics/AggregationTemporalitySelector

* test gauge temporality, update docs

* fix gauge temporality, add tests based on Java's

* Update src/SDK/Metrics/AggregationTemporalitySelector.php

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

* update test

---------

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

Author: brettmc

.github/workflows/php.yml

@@ -87,7 +87,7 @@ jobs:
       uses: actions/cache@v4
       with:
         path: vendor
-        key: ${{ runner.os }}-${{ matrix.php-version }}-composer-${{ hashFiles('**/composer.json') }}
+        key: ${{ runner.os }}-${{ matrix.php-version }}-composer-${{ hashFiles('**/composer.json', '**/_register.php') }}
     - name: Cache test tools
       id: test-tools-cache
       uses: actions/cache@v4

composer.json

@@ -7,7 +7,7 @@
     "readme": "./README.md",
     "license": "Apache-2.0",
     "require": {
-        "php": "^8.1",
+        "php": "^8.2",
         "google/protobuf": "^3.22 || ^4.0",
         "nyholm/psr7-server": "^1.1",
         "php-http/discovery": "^1.14",

docs/upgrading.md

@@ -30,8 +30,16 @@ providing a higher priority for the same type).
 Methods which previously accepted `Temporality|string`, or `InstrumentType|string` no longer accept strings.
 `$advisory` is now a required parameter for `OpenTelemetry\SDK\Metrics\DefaultAggregationProviderInterface`.
 
+If the SDK is configured via autoloading (using environment variables or declarative (yaml) config), the default temporality
+is `Cumulative` for all instruments, per [spec](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.48.0/specification/metrics/sdk_exporters/otlp.md#general).
+This can be changed by setting the temporality preference via `OTEL_METRIC_TEMPORALITY_PREFERENCE` environment variable. Possible
+values are `cumulative`, `delta`, or `lowmemory`.
+
+If the SDK is configured programmatically, an exporter should be configured with an `AggregationTemporalitySelectorInterface`.
+The SDK-provided implementations are `AggregationTemporalitySelector::alwaysCumulative()`, `::deltaPreferred()`,
+and `::lowMemory()`. The default selector is cumulative.
+
 #### TracerProvider
 `TracerProvider` constructor now accepts a `SpanProcessorInterface` as the first argument, rather than an array of
 `SpanProcessorInterface`s. If multiple processors are required, they should be added to a `MultiSpanProcessor` (which
 is what happened internally in 1.x anyway).
-

examples/metrics/getting_started.php

@@ -3,7 +3,7 @@
 declare(strict_types=1);
 
 use OpenTelemetry\API\Metrics\ObserverInterface;
-use OpenTelemetry\SDK\Metrics\Data\Temporality;
+use OpenTelemetry\SDK\Metrics\AggregationTemporalitySelector;
 use OpenTelemetry\SDK\Metrics\MeterProvider;
 use OpenTelemetry\SDK\Metrics\MetricExporter\ConsoleMetricExporter;
 use OpenTelemetry\SDK\Metrics\MetricReader\ExportingReader;
@@ -18,7 +18,7 @@
  */
 
 $reader = new ExportingReader(
-    new ConsoleMetricExporter(Temporality::DELTA)
+    new ConsoleMetricExporter(AggregationTemporalitySelector::deltaPreferred())
 );
 
 $meterProvider = MeterProvider::builder()

examples/metrics/weak-reference-observables.php

@@ -3,7 +3,7 @@
 declare(strict_types=1);
 
 use OpenTelemetry\API\Metrics\ObserverInterface;
-use OpenTelemetry\SDK\Metrics\Data\Temporality;
+use OpenTelemetry\SDK\Metrics\AggregationTemporalitySelector;
 use OpenTelemetry\SDK\Metrics\MeterProvider;
 use OpenTelemetry\SDK\Metrics\MetricExporter\ConsoleMetricExporter;
 use OpenTelemetry\SDK\Metrics\MetricReader\ExportingReader;
@@ -19,7 +19,7 @@
  */
 
 $reader = new ExportingReader(
-    new ConsoleMetricExporter(Temporality::DELTA)
+    new ConsoleMetricExporter(AggregationTemporalitySelector::deltaPreferred())
 );
 
 $meterProvider = MeterProvider::builder()

files/collector/otel-collector-config.yml

@@ -2,7 +2,9 @@ receivers:
   otlp:
     protocols:
       grpc:
+        endpoint: 0.0.0.0:4317
       http:
+        endpoint: 0.0.0.0:4318
   zipkin:
 
 exporters:

phpstan.neon.dist

@@ -52,6 +52,14 @@ parameters:
             paths:
                 - src/SDK/Common/InstrumentationScope
         -
-            message: "#.*expects Google\\\\Protobuf\\\\RepeatedField.*#"
+            message: "#.*RepeatedField.*#"
             paths:
                 - src/Contrib/Otlp
+        -
+            message: "#Access to an undefined property .*#"
+            paths:
+                - tests/Integration/SDK/Metrics
+        -
+            message: "#.*assertSame.*will always evaluate to false.#"
+            paths:
+                - tests/Unit/SDK/Metrics/MetricRegistry/MetricRegistryTest.php

rector.php

@@ -6,6 +6,7 @@
 use Rector\CodeQuality\Rector\Identical\FlipTypeControlToUseExclusiveTypeRector;
 use Rector\CodeQuality\Rector\If_\ExplicitBoolCompareRector;
 use Rector\Config\RectorConfig;
+use Rector\Php71\Rector\FuncCall\RemoveExtraParametersRector;
 use Rector\Php82\Rector\Class_\ReadOnlyClassRector;
 use Rector\PHPUnit\Set\PHPUnitSetList;
 use Rector\Strict\Rector\Empty_\DisallowedEmptyRuleFixerRector;
@@ -31,5 +32,6 @@
         ExplicitBoolCompareRector::class,
         LocallyCalledStaticMethodToNonStaticRector::class,
         ReadOnlyClassRector::class,
+        RemoveExtraParametersRector::class
     ]);
 };

src/Config/SDK/ComponentProvider/Metrics/MetricExporterOtlpFile.php

@@ -13,7 +13,7 @@
 use OpenTelemetry\Contrib\Otlp\ContentTypes;
 use OpenTelemetry\Contrib\Otlp\MetricExporter;
 use OpenTelemetry\SDK\Common\Services\Loader;
-use OpenTelemetry\SDK\Metrics\Data\Temporality;
+use OpenTelemetry\SDK\Metrics\AggregationTemporalitySelector;
 use OpenTelemetry\SDK\Metrics\MetricExporterInterface;
 use Symfony\Component\Config\Definition\Builder\ArrayNodeDefinition;
 use Symfony\Component\Config\Definition\Builder\NodeBuilder;
@@ -35,16 +35,16 @@ public function createPlugin(array $properties, Context $context): MetricExporte
     {
         $endpoint = OutputStreamParser::parse($properties['output_stream']);
 
-        $temporality = match ($properties['temporality_preference']) {
-            'cumulative' => Temporality::CUMULATIVE,
-            'delta' => Temporality::DELTA,
-            'lowmemory' => null,
+        $selector = match ($properties['temporality_preference']) {
+            'cumulative' => AggregationTemporalitySelector::alwaysCumulative(),
+            'delta' => AggregationTemporalitySelector::deltaPreferred(),
+            'lowmemory' => AggregationTemporalitySelector::lowMemory(),
         };
 
         return new MetricExporter(Loader::transportFactory('stream')->create(
             endpoint: $endpoint,
             contentType: ContentTypes::NDJSON,
-        ), $temporality);
+        ), $selector);
     }
 
     public function getConfig(ComponentProviderRegistry $registry, NodeBuilder $builder): ArrayNodeDefinition

src/Config/SDK/ComponentProvider/Metrics/MetricExporterOtlpGrpc.php

@@ -16,7 +16,7 @@
 use OpenTelemetry\Contrib\Otlp\Protocols;
 use OpenTelemetry\SDK\Common\Configuration\Parser\MapParser;
 use OpenTelemetry\SDK\Common\Services\Loader;
-use OpenTelemetry\SDK\Metrics\Data\Temporality;
+use OpenTelemetry\SDK\Metrics\AggregationTemporalitySelector;
 use OpenTelemetry\SDK\Metrics\MetricExporterInterface;
 use Symfony\Component\Config\Definition\Builder\ArrayNodeDefinition;
 use Symfony\Component\Config\Definition\Builder\NodeBuilder;
@@ -49,10 +49,10 @@ public function createPlugin(array $properties, Context $context): MetricExporte
 
         $headers = array_column($properties['headers'], 'value', 'name') + MapParser::parse($properties['headers_list']);
 
-        $temporality = match ($properties['temporality_preference']) {
-            'cumulative' => Temporality::CUMULATIVE,
-            'delta' => Temporality::DELTA,
-            'lowmemory' => null,
+        $selector = match ($properties['temporality_preference']) {
+            'cumulative' => AggregationTemporalitySelector::alwaysCumulative(),
+            'delta' => AggregationTemporalitySelector::deltaPreferred(),
+            'lowmemory' => AggregationTemporalitySelector::lowMemory(),
         };
 
         return new MetricExporter(Loader::transportFactory($protocol)->create(
@@ -64,7 +64,7 @@ public function createPlugin(array $properties, Context $context): MetricExporte
             cacert: $properties['certificate_file'],
             cert: $properties['client_certificate_file'],
             key: $properties['client_certificate_file'],
-        ), $temporality);
+        ), $selector);
     }
 
     public function getConfig(ComponentProviderRegistry $registry, NodeBuilder $builder): ArrayNodeDefinition