Add support for multi-instrument callbacks (#1202)

* Add support for multi-instrument callbacks

https://opentelemetry.io/docs/specs/otel/metrics/api/#multiple-instrument-callbacks

* Fix undefined offset on detach of batch callback with repeated instrument

* Unify BatchObservableCallback and ObservableCallback

* Add missing typehint

* Do not bump API dependency

Not required, SDK will continue to work with lower API versions, only `::batchObserve()` won't be usable.

Author: Nevay

Metrics/AsynchronousInstrument.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\API\Metrics;
+
+/**
+ * Marker interface for asynchronous instruments.
+ */
+interface AsynchronousInstrument
+{
+}

Metrics/CounterInterface.php

@@ -6,7 +6,7 @@
 
 use OpenTelemetry\Context\ContextInterface;
 
-interface CounterInterface
+interface CounterInterface extends SynchronousInstrument
 {
 
     /**

Metrics/HistogramInterface.php

@@ -6,7 +6,7 @@
 
 use OpenTelemetry\Context\ContextInterface;
 
-interface HistogramInterface
+interface HistogramInterface extends SynchronousInstrument
 {
 
     /**

Metrics/MeterInterface.php

@@ -7,6 +7,40 @@
 interface MeterInterface
 {
 
+    /**
+     * Reports measurements for multiple asynchronous instrument from a single callback.
+     *
+     * The callback receives an {@link ObserverInterface} for each instrument. All provided
+     * instruments have to be created by this meter.
+     *
+     * ```php
+     * $callback = $meter->batchObserve(
+     *     function(
+     *         ObserverInterface $usageObserver,
+     *         ObserverInterface $pressureObserver,
+     *     ): void {
+     *         [$usage, $pressure] = expensive_system_call();
+     *         $usageObserver->observe($usage);
+     *         $pressureObserver->observe($pressure);
+     *     },
+     *     $meter->createObservableCounter('usage', description: 'count of items used'),
+     *     $meter->createObservableGauge('pressure', description: 'force per unit area'),
+     * );
+     * ```
+     *
+     * @param callable $callback function responsible for reporting the measurements
+     * @param AsynchronousInstrument $instrument first instrument to report measurements for
+     * @param AsynchronousInstrument ...$instruments additional instruments to report measurements for
+     * @return ObservableCallbackInterface token to detach callback
+     *
+     * @see https://opentelemetry.io/docs/specs/otel/metrics/api/#multiple-instrument-callbacks
+     */
+    public function batchObserve(
+        callable $callback,
+        AsynchronousInstrument $instrument,
+        AsynchronousInstrument ...$instruments
+    ): ObservableCallbackInterface;
+
     /**
      * Creates a `Counter`.
      *

Metrics/Noop/NoopMeter.php

@@ -4,16 +4,23 @@
 
 namespace OpenTelemetry\API\Metrics\Noop;
 
+use OpenTelemetry\API\Metrics\AsynchronousInstrument;
 use OpenTelemetry\API\Metrics\CounterInterface;
 use OpenTelemetry\API\Metrics\HistogramInterface;
 use OpenTelemetry\API\Metrics\MeterInterface;
+use OpenTelemetry\API\Metrics\ObservableCallbackInterface;
 use OpenTelemetry\API\Metrics\ObservableCounterInterface;
 use OpenTelemetry\API\Metrics\ObservableGaugeInterface;
 use OpenTelemetry\API\Metrics\ObservableUpDownCounterInterface;
 use OpenTelemetry\API\Metrics\UpDownCounterInterface;
 
 final class NoopMeter implements MeterInterface
 {
+    public function batchObserve(callable $callback, AsynchronousInstrument $instrument, AsynchronousInstrument ...$instruments): ObservableCallbackInterface
+    {
+        return new NoopObservableCallback();
+    }
+
     public function createCounter(string $name, ?string $unit = null, ?string $description = null, array $advisory = []): CounterInterface
     {
         return new NoopCounter();

Metrics/ObservableCounterInterface.php

@@ -4,7 +4,7 @@
 
 namespace OpenTelemetry\API\Metrics;
 
-interface ObservableCounterInterface
+interface ObservableCounterInterface extends AsynchronousInstrument
 {
 
     /**

Metrics/ObservableGaugeInterface.php

@@ -4,7 +4,7 @@
 
 namespace OpenTelemetry\API\Metrics;
 
-interface ObservableGaugeInterface
+interface ObservableGaugeInterface extends AsynchronousInstrument
 {
 
     /**

Metrics/ObservableUpDownCounterInterface.php

@@ -4,7 +4,7 @@
 
 namespace OpenTelemetry\API\Metrics;
 
-interface ObservableUpDownCounterInterface
+interface ObservableUpDownCounterInterface extends AsynchronousInstrument
 {
 
     /**

Metrics/SynchronousInstrument.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\API\Metrics;
+
+/**
+ * Marker interface for synchronous instruments.
+ */
+interface SynchronousInstrument
+{
+}

Metrics/UpDownCounterInterface.php

@@ -6,7 +6,7 @@
 
 use OpenTelemetry\Context\ContextInterface;
 
-interface UpDownCounterInterface
+interface UpDownCounterInterface extends SynchronousInstrument
 {
 
     /**