Add instrument advisory parameter

src/API/Metrics/MeterInterface.php

@@ -13,14 +13,16 @@ interface MeterInterface
      * @param string $name name of the instrument
      * @param string|null $unit unit of measure
      * @param string|null $description description of the instrument
+     * @param array $advisory an optional set of recommendations
      * @return CounterInterface created instrument
      *
      * @see https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#counter-creation
      */
     public function createCounter(
         string $name,
         ?string $unit = null,
-        ?string $description = null
+        ?string $description = null,
+        array $advisory = []
     ): CounterInterface;
 
     /**
@@ -29,6 +31,8 @@ public function createCounter(
      * @param string $name name of the instrument
      * @param string|null $unit unit of measure
      * @param string|null $description description of the instrument
+     * @param array|callable $advisory an optional set of recommendations, or
+     *        deprecated: the first callback to report measurements
      * @param callable ...$callbacks responsible for reporting measurements
      * @return ObservableCounterInterface created instrument
      *
@@ -38,6 +42,7 @@ public function createObservableCounter(
         string $name,
         ?string $unit = null,
         ?string $description = null,
+        $advisory = [],
         callable ...$callbacks
     ): ObservableCounterInterface;
 
@@ -47,14 +52,17 @@ public function createObservableCounter(
      * @param string $name name of the instrument
      * @param string|null $unit unit of measure
      * @param string|null $description description of the instrument
+     * @param array $advisory an optional set of recommendations, e.g.
+     *        <code>['ExplicitBucketBoundaries' => [0.25, 0.5, 1, 5]]</code>
      * @return HistogramInterface created instrument
      *
      * @see https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#histogram-creation
      */
     public function createHistogram(
         string $name,
         ?string $unit = null,
-        ?string $description = null
+        ?string $description = null,
+        array $advisory = []
     ): HistogramInterface;
 
     /**
@@ -63,6 +71,8 @@ public function createHistogram(
      * @param string $name name of the instrument
      * @param string|null $unit unit of measure
      * @param string|null $description description of the instrument
+     * @param array|callable $advisory an optional set of recommendations, or
+     *        deprecated: the first callback to report measurements
      * @param callable ...$callbacks responsible for reporting measurements
      * @return ObservableGaugeInterface created instrument
      *
@@ -72,6 +82,7 @@ public function createObservableGauge(
         string $name,
         ?string $unit = null,
         ?string $description = null,
+        $advisory = [],
         callable ...$callbacks
     ): ObservableGaugeInterface;
 
@@ -81,14 +92,16 @@ public function createObservableGauge(
      * @param string $name name of the instrument
      * @param string|null $unit unit of measure
      * @param string|null $description description of the instrument
+     * @param array $advisory an optional set of recommendations
      * @return UpDownCounterInterface created instrument
      *
      * @see https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#updowncounter-creation
      */
     public function createUpDownCounter(
         string $name,
         ?string $unit = null,
-        ?string $description = null
+        ?string $description = null,
+        array $advisory = []
     ): UpDownCounterInterface;
 
     /**
@@ -97,6 +110,8 @@ public function createUpDownCounter(
      * @param string $name name of the instrument
      * @param string|null $unit unit of measure
      * @param string|null $description description of the instrument
+     * @param array|callable $advisory an optional set of recommendations, or
+     *        deprecated: the first callback to report measurements
      * @param callable ...$callbacks responsible for reporting measurements
      * @return ObservableUpDownCounterInterface created instrument
      *
@@ -106,6 +121,7 @@ public function createObservableUpDownCounter(
         string $name,
         ?string $unit = null,
         ?string $description = null,
+        $advisory = [],
         callable ...$callbacks
     ): ObservableUpDownCounterInterface;
 }

src/API/Metrics/Noop/NoopMeter.php

@@ -14,32 +14,32 @@
 
 final class NoopMeter implements MeterInterface
 {
-    public function createCounter(string $name, ?string $unit = null, ?string $description = null): CounterInterface
+    public function createCounter(string $name, ?string $unit = null, ?string $description = null, array $advisory = []): CounterInterface
     {
         return new NoopCounter();
     }
 
-    public function createObservableCounter(string $name, ?string $unit = null, ?string $description = null, callable ...$callbacks): ObservableCounterInterface
+    public function createObservableCounter(string $name, ?string $unit = null, ?string $description = null, $advisory = [], callable ...$callbacks): ObservableCounterInterface
     {
         return new NoopObservableCounter();
     }
 
-    public function createHistogram(string $name, ?string $unit = null, ?string $description = null): HistogramInterface
+    public function createHistogram(string $name, ?string $unit = null, ?string $description = null, array $advisory = []): HistogramInterface
     {
         return new NoopHistogram();
     }
 
-    public function createObservableGauge(string $name, ?string $unit = null, ?string $description = null, callable ...$callbacks): ObservableGaugeInterface
+    public function createObservableGauge(string $name, ?string $unit = null, ?string $description = null, $advisory = [], callable ...$callbacks): ObservableGaugeInterface
     {
         return new NoopObservableGauge();
     }
 
-    public function createUpDownCounter(string $name, ?string $unit = null, ?string $description = null): UpDownCounterInterface
+    public function createUpDownCounter(string $name, ?string $unit = null, ?string $description = null, array $advisory = []): UpDownCounterInterface
     {
         return new NoopUpDownCounter();
     }
 
-    public function createObservableUpDownCounter(string $name, ?string $unit = null, ?string $description = null, callable ...$callbacks): ObservableUpDownCounterInterface
+    public function createObservableUpDownCounter(string $name, ?string $unit = null, ?string $description = null, $advisory = [], callable ...$callbacks): ObservableUpDownCounterInterface
     {
         return new NoopObservableUpDownCounter();
     }

src/API/composer.json

@@ -24,6 +24,9 @@
         "symfony/polyfill-php81": "^1.26",
         "symfony/polyfill-php82": "^1.26"
     },
+    "conflict": {
+        "open-telemetry/sdk": "<=1.0.1"
+    },
     "autoload": {
         "psr-4": {
             "OpenTelemetry\\API\\": "."

src/SDK/Metrics/DefaultAggregationProviderInterface.php

@@ -8,6 +8,10 @@ interface DefaultAggregationProviderInterface
 {
     /**
      * @param string|InstrumentType $instrumentType
+     * @param array $advisory optional set of recommendations
+     *
+     * @noinspection PhpDocSignatureInspection not added for BC
+     * @phan-suppress PhanCommentParamWithoutRealParam @phpstan-ignore-next-line
      */
-    public function defaultAggregation($instrumentType): ?AggregationInterface;
+    public function defaultAggregation($instrumentType /*, array $advisory = [] */): ?AggregationInterface;
 }

src/SDK/Metrics/DefaultAggregationProviderTrait.php

@@ -6,7 +6,7 @@
 
 trait DefaultAggregationProviderTrait
 {
-    public function defaultAggregation($instrumentType): ?AggregationInterface
+    public function defaultAggregation($instrumentType, array $advisory = []): ?AggregationInterface
     {
         switch ($instrumentType) {
             case InstrumentType::COUNTER:
@@ -16,7 +16,7 @@ public function defaultAggregation($instrumentType): ?AggregationInterface
             case InstrumentType::ASYNCHRONOUS_UP_DOWN_COUNTER:
                 return new Aggregation\SumAggregation();
             case InstrumentType::HISTOGRAM:
-                return new Aggregation\ExplicitBucketHistogramAggregation([0, 5, 10, 25, 50, 75, 100, 250, 500, 1000]);
+                return new Aggregation\ExplicitBucketHistogramAggregation($advisory['ExplicitBucketBoundaries'] ?? [0, 5, 10, 25, 50, 75, 100, 250, 500, 1000]);
             case InstrumentType::ASYNCHRONOUS_GAUGE:
                 return new Aggregation\LastValueAggregation();
         }

src/SDK/Metrics/Instrument.php

@@ -23,14 +23,20 @@ final class Instrument
      * @readonly
      */
     public ?string $description;
+    /**
+     * @readonly
+     */
+    public array $advisory;
+
     /**
      * @param string|InstrumentType $type
      */
-    public function __construct($type, string $name, ?string $unit, ?string $description)
+    public function __construct($type, string $name, ?string $unit, ?string $description, array $advisory = [])
     {
         $this->type = $type;
         $this->name = $name;
         $this->unit = $unit;
         $this->description = $description;
+        $this->advisory = $advisory;
     }
 }

src/SDK/Metrics/Meter.php

@@ -4,7 +4,9 @@
 
 namespace OpenTelemetry\SDK\Metrics;
 
+use function array_unshift;
 use ArrayAccess;
+use function is_callable;
 use OpenTelemetry\API\Metrics\CounterInterface;
 use OpenTelemetry\API\Metrics\HistogramInterface;
 use OpenTelemetry\API\Metrics\MeterInterface;
@@ -75,25 +77,31 @@ public function __construct(
         $this->writer = $writer;
     }
 
-    public function createCounter(string $name, ?string $unit = null, ?string $description = null): CounterInterface
+    public function createCounter(string $name, ?string $unit = null, ?string $description = null, array $advisory = []): CounterInterface
     {
         [$instrument, $referenceCounter] = $this->createSynchronousWriter(
             InstrumentType::COUNTER,
             $name,
             $unit,
             $description,
+            $advisory,
         );
 
         return new Counter($this->writer, $instrument, $referenceCounter);
     }
 
-    public function createObservableCounter(string $name, ?string $unit = null, ?string $description = null, callable ...$callbacks): ObservableCounterInterface
+    public function createObservableCounter(string $name, ?string $unit = null, ?string $description = null, $advisory = [], callable ...$callbacks): ObservableCounterInterface
     {
+        if (is_callable($advisory)) {
+            array_unshift($callbacks, $advisory);
+            $advisory = [];
+        }
         [$instrument, $referenceCounter, $destructors] = $this->createAsynchronousObserver(
             InstrumentType::ASYNCHRONOUS_COUNTER,
             $name,
             $unit,
             $description,
+            $advisory,
         );
 
         foreach ($callbacks as $callback) {
@@ -104,25 +112,31 @@ public function createObservableCounter(string $name, ?string $unit = null, ?str
         return new ObservableCounter($this->writer, $instrument, $referenceCounter, $destructors);
     }
 
-    public function createHistogram(string $name, ?string $unit = null, ?string $description = null): HistogramInterface
+    public function createHistogram(string $name, ?string $unit = null, ?string $description = null, array $advisory = []): HistogramInterface
     {
         [$instrument, $referenceCounter] = $this->createSynchronousWriter(
             InstrumentType::HISTOGRAM,
             $name,
             $unit,
             $description,
+            $advisory,
         );
 
         return new Histogram($this->writer, $instrument, $referenceCounter);
     }
 
-    public function createObservableGauge(string $name, ?string $unit = null, ?string $description = null, callable ...$callbacks): ObservableGaugeInterface
+    public function createObservableGauge(string $name, ?string $unit = null, ?string $description = null, $advisory = [], callable ...$callbacks): ObservableGaugeInterface
     {
+        if (is_callable($advisory)) {
+            array_unshift($callbacks, $advisory);
+            $advisory = [];
+        }
         [$instrument, $referenceCounter, $destructors] = $this->createAsynchronousObserver(
             InstrumentType::ASYNCHRONOUS_GAUGE,
             $name,
             $unit,
             $description,
+            $advisory,
         );
 
         foreach ($callbacks as $callback) {
@@ -133,25 +147,31 @@ public function createObservableGauge(string $name, ?string $unit = null, ?strin
         return new ObservableGauge($this->writer, $instrument, $referenceCounter, $destructors);
     }
 
-    public function createUpDownCounter(string $name, ?string $unit = null, ?string $description = null): UpDownCounterInterface
+    public function createUpDownCounter(string $name, ?string $unit = null, ?string $description = null, array $advisory = []): UpDownCounterInterface
     {
         [$instrument, $referenceCounter] = $this->createSynchronousWriter(
             InstrumentType::UP_DOWN_COUNTER,
             $name,
             $unit,
             $description,
+            $advisory,
         );
 
         return new UpDownCounter($this->writer, $instrument, $referenceCounter);
     }
 
-    public function createObservableUpDownCounter(string $name, ?string $unit = null, ?string $description = null, callable ...$callbacks): ObservableUpDownCounterInterface
+    public function createObservableUpDownCounter(string $name, ?string $unit = null, ?string $description = null, $advisory = [], callable ...$callbacks): ObservableUpDownCounterInterface
     {
+        if (is_callable($advisory)) {
+            array_unshift($callbacks, $advisory);
+            $advisory = [];
+        }
         [$instrument, $referenceCounter, $destructors] = $this->createAsynchronousObserver(
             InstrumentType::ASYNCHRONOUS_UP_DOWN_COUNTER,
             $name,
             $unit,
             $description,
+            $advisory,
         );
 
         foreach ($callbacks as $callback) {
@@ -166,9 +186,9 @@ public function createObservableUpDownCounter(string $name, ?string $unit = null
      * @param string|InstrumentType $instrumentType
      * @return array{Instrument, ReferenceCounterInterface}
      */
-    private function createSynchronousWriter($instrumentType, string $name, ?string $unit, ?string $description): array
+    private function createSynchronousWriter($instrumentType, string $name, ?string $unit, ?string $description, array $advisory = []): array
     {
-        $instrument = new Instrument($instrumentType, $name, $unit, $description);
+        $instrument = new Instrument($instrumentType, $name, $unit, $description, $advisory);
 
         $instrumentationScopeId = $this->instrumentationScopeId($this->instrumentationScope);
         $instrumentId = $this->instrumentId($instrument);
@@ -213,9 +233,9 @@ private function createSynchronousWriter($instrumentType, string $name, ?string
      * @param string|InstrumentType $instrumentType
      * @return array{Instrument, ReferenceCounterInterface, ArrayAccess<object, ObservableCallbackDestructor>}
      */
-    private function createAsynchronousObserver($instrumentType, string $name, ?string $unit, ?string $description): array
+    private function createAsynchronousObserver($instrumentType, string $name, ?string $unit, ?string $description, array $advisory): array
     {
-        $instrument = new Instrument($instrumentType, $name, $unit, $description);
+        $instrument = new Instrument($instrumentType, $name, $unit, $description, $advisory);
 
         $instrumentationScopeId = $this->instrumentationScopeId($this->instrumentationScope);
         $instrumentId = $this->instrumentId($instrument);
@@ -293,7 +313,8 @@ private function viewRegistrationRequests(Instrument $instrument, StalenessHandl
                             $view->unit,
                             $view->description,
                             $view->attributeKeys,
-                            $metricRegistry->defaultAggregation($instrument->type),
+                            /** @phan-suppress-next-line PhanParamTooMany @phpstan-ignore-next-line */
+                            $metricRegistry->defaultAggregation($instrument->type, $instrument->advisory),
                         ),
                         new RegistryRegistration($metricRegistry, $stalenessHandler),
                     ];
@@ -309,6 +330,11 @@ private function instrumentationScopeId(InstrumentationScopeInterface $instrumen
 
     private function instrumentId(Instrument $instrument): string
     {
-        return serialize($instrument);
+        return serialize([
+            $instrument->type,
+            $instrument->name,
+            $instrument->unit,
+            $instrument->description,
+        ]);
     }
 }

src/SDK/Metrics/MetricReader/ExportingReader.php

@@ -41,13 +41,14 @@ public function __construct(MetricExporterInterface $exporter)
         $this->exporter = $exporter;
     }
 
-    public function defaultAggregation($instrumentType): ?AggregationInterface
+    public function defaultAggregation($instrumentType, array $advisory = []): ?AggregationInterface
     {
         if ($this->exporter instanceof DefaultAggregationProviderInterface) {
-            return $this->exporter->defaultAggregation($instrumentType);
+            /** @phan-suppress-next-line PhanParamTooMany @phpstan-ignore-next-line */
+            return $this->exporter->defaultAggregation($instrumentType, $advisory);
         }
 
-        return $this->_defaultAggregation($instrumentType);
+        return $this->_defaultAggregation($instrumentType, $advisory);
     }
 
     public function add(MetricSourceProviderInterface $provider, MetricMetadataInterface $metadata, StalenessHandlerInterface $stalenessHandler): void