Add instrument advisory parameter (#1186)

* Add instrument advisory parameter

* Undo bucket boundaries change to preserve BC

"SDKs SHOULD use the default value when boundaries are not explicitly provided, unless they have good reasons to use something different (e.g. for backward compatibility reasons in a stable SDK release)."

* Add note that passing callback instead of advisory is deprecated

Author: Nevay

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

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

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\\": "."