Add instrument advisory API to "Stable" Metrics SDK (#793)

* Add advisory bucket size to Stable SDK Histogram

* Add tests

* Reverted unrelated changes

* Updated test to verify exported data uses custom buckets

---------

Co-authored-by: Bryce Buchanan <[email protected]>

Author: JustasL

Sources/OpenTelemetryApi/Metrics/Stable/DefaultStableMeter.swift

@@ -49,6 +49,10 @@ public class DefaultStableMeter: StableMeter {
   }
 
   public class NoopDoubleHistogramBuilder: DoubleHistogramBuilder {
+    public func setExplicitBucketBoundariesAdvice(_ boundaries: [Double]) -> Self {
+      return self
+    }
+    
     public func ofLongs() -> NoopLongHistogramBuilder {
       NoopLongHistogramBuilder()
     }
@@ -127,6 +131,10 @@ public class DefaultStableMeter: StableMeter {
   }
 
   public class NoopLongHistogramBuilder: LongHistogramBuilder {
+    public func setExplicitBucketBoundariesAdvice(_ boundaries: [Double]) -> Self {
+      return self
+    }
+    
     public func build() -> NoopLongHistogram {
       NoopLongHistogram()
     }

Sources/OpenTelemetryApi/Metrics/Stable/DoubleHistogramBuilder.swift

@@ -9,6 +9,13 @@ public protocol DoubleHistogramBuilder: AnyObject {
   associatedtype AnyLongHistogramBuilder : LongHistogramBuilder
   associatedtype AnyDoubleHistogram : DoubleHistogram
   func ofLongs() -> AnyLongHistogramBuilder
+  
+  /// Sets explicit bucket boundaries advice for the histogram.
+  /// This is a hint to the SDK about the recommended bucket boundaries.
+  /// The SDK may ignore this advice if a View is configured for this instrument.
+  /// - Parameter boundaries: Array of bucket boundaries in ascending order
+  /// - Returns: Self for method chaining
+  func setExplicitBucketBoundariesAdvice(_ boundaries: [Double]) -> Self
 
   func build() -> AnyDoubleHistogram
 }

Sources/OpenTelemetryApi/Metrics/Stable/LongHistogramBuilder.swift

@@ -7,5 +7,13 @@ import Foundation
 
 public protocol LongHistogramBuilder: AnyObject {
   associatedtype AnyLongHistogram: LongHistogram
+  
+  /// Sets explicit bucket boundaries advice for the histogram.
+  /// This is a hint to the SDK about the recommended bucket boundaries.
+  /// The SDK may ignore this advice if a View is configured for this instrument.
+  /// - Parameter boundaries: Array of bucket boundaries in ascending order
+  /// - Returns: Self for method chaining
+  func setExplicitBucketBoundariesAdvice(_ boundaries: [Double]) -> Self
+  
   func build() -> AnyLongHistogram
 }

Sources/OpenTelemetrySdk/Metrics/Stable/Aggregation/DefaultAggregation.swift

@@ -21,7 +21,12 @@ public class DefaultAggregation: Aggregation {
     case .counter, .upDownCounter, .observableCounter, .observableUpDownCounter:
       return SumAggregation.instance
     case .histogram:
-      return ExplicitBucketHistogramAggregation.instance
+      // Use advisory bucket boundaries if available, otherwise use default
+      if let advisoryBoundaries = instrument.explicitBucketBoundariesAdvice {
+        return ExplicitBucketHistogramAggregation(bucketBoundaries: advisoryBoundaries)
+      } else {
+        return ExplicitBucketHistogramAggregation.instance
+      }
     case .observableGauge, .gauge:
       return LastValueAggregation.instance
     }

Sources/OpenTelemetrySdk/Metrics/Stable/DoubleHistogramMeterBuilderSdk.swift

@@ -23,6 +23,11 @@ public class DoubleHistogramMeterBuilderSdk: InstrumentBuilder, DoubleHistogramB
     )
   }
 
+  public func setExplicitBucketBoundariesAdvice(_ boundaries: [Double]) -> Self {
+    self.explicitBucketBoundariesAdvice = boundaries
+    return self
+  }
+
   public func ofLongs() -> LongHistogramMeterBuilderSdk {
     swapBuilder(LongHistogramMeterBuilderSdk.init)
   }

Sources/OpenTelemetrySdk/Metrics/Stable/InstrumentBuilder.swift

@@ -14,6 +14,8 @@ public class InstrumentBuilder {
   var description: String
   var unit: String
   var instrumentName: String
+  var explicitBucketBoundariesAdvice: [Double]?
+  
   init(meterProviderSharedState: inout MeterProviderSharedState, meterSharedState: inout StableMeterSharedState, type: InstrumentType, valueType: InstrumentValueType, description: String, unit: String, instrumentName: String) {
     self.meterProviderSharedState = meterProviderSharedState
     self.meterSharedState = meterSharedState
@@ -22,6 +24,7 @@ public class InstrumentBuilder {
     self.description = description
     self.unit = unit
     self.instrumentName = instrumentName
+    self.explicitBucketBoundariesAdvice = nil
   }
 }
 
@@ -38,12 +41,14 @@ public extension InstrumentBuilder {
   }
 
   internal func swapBuilder<T: InstrumentBuilder>(_ builder: (inout MeterProviderSharedState, inout StableMeterSharedState, String, String, String) -> T) -> T {
-    return builder(&meterProviderSharedState, &meterSharedState, instrumentName, description, unit)
+    let newBuilder = builder(&meterProviderSharedState, &meterSharedState, instrumentName, description, unit)
+    newBuilder.explicitBucketBoundariesAdvice = self.explicitBucketBoundariesAdvice
+    return newBuilder
   }
 
   // todo : Is it necessary to use inout for writableMetricStorage?
   func buildSynchronousInstrument<T: Instrument>(_ instrumentFactory: (InstrumentDescriptor, WritableMetricStorage) -> T) -> T {
-    let descriptor = InstrumentDescriptor(name: instrumentName, description: description, unit: unit, type: type, valueType: valueType)
+    let descriptor = InstrumentDescriptor(name: instrumentName, description: description, unit: unit, type: type, valueType: valueType, explicitBucketBoundariesAdvice: explicitBucketBoundariesAdvice)
     let storage = meterSharedState.registerSynchronousMetricStorage(instrument: descriptor, meterProviderSharedState: meterProviderSharedState)
     return instrumentFactory(descriptor, storage)
   }
@@ -67,7 +72,7 @@ public extension InstrumentBuilder {
   }
 
   func buildObservableMeasurement(type: InstrumentType) -> StableObservableMeasurementSdk {
-    let descriptor = InstrumentDescriptor(name: instrumentName, description: description, unit: unit, type: type, valueType: valueType)
+    let descriptor = InstrumentDescriptor(name: instrumentName, description: description, unit: unit, type: type, valueType: valueType, explicitBucketBoundariesAdvice: explicitBucketBoundariesAdvice)
     return meterSharedState.registerObservableMeasurement(instrumentDescriptor: descriptor)
   }
 }

Sources/OpenTelemetrySdk/Metrics/Stable/InstrumentDescriptor.swift

@@ -11,20 +11,23 @@ public struct InstrumentDescriptor: Equatable {
   public let unit: String
   public let type: InstrumentType
   public let valueType: InstrumentValueType
+  public let explicitBucketBoundariesAdvice: [Double]?
 
-  public init(name: String, description: String, unit: String, type: InstrumentType, valueType: InstrumentValueType) {
+  public init(name: String, description: String, unit: String, type: InstrumentType, valueType: InstrumentValueType, explicitBucketBoundariesAdvice: [Double]? = nil) {
     self.name = name
     self.description = description
     self.unit = unit
     self.type = type
     self.valueType = valueType
+    self.explicitBucketBoundariesAdvice = explicitBucketBoundariesAdvice
   }
 
   public static func == (lhs: Self, rhs: Self) -> Bool {
     return lhs.name == rhs.name &&
       lhs.description == rhs.description &&
       lhs.unit == rhs.unit &&
       lhs.valueType == rhs.valueType &&
-      lhs.type == rhs.type
+      lhs.type == rhs.type &&
+      lhs.explicitBucketBoundariesAdvice == rhs.explicitBucketBoundariesAdvice
   }
 }

Sources/OpenTelemetrySdk/Metrics/Stable/LongHistogramMeterBuilderSdk.swift

@@ -23,6 +23,11 @@ public class LongHistogramMeterBuilderSdk: InstrumentBuilder, LongHistogramBuild
     )
   }
 
+  public func setExplicitBucketBoundariesAdvice(_ boundaries: [Double]) -> Self {
+    self.explicitBucketBoundariesAdvice = boundaries
+    return self
+  }
+
   public func build() -> LongHistogramMeterSdk {
     buildSynchronousInstrument(LongHistogramMeterSdk.init)
   }

Tests/OpenTelemetrySdkTests/Metrics/StableMetrics/AdvisoryParameterTests.swift

@@ -0,0 +1,68 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import XCTest
+import OpenTelemetryApi
+@testable import OpenTelemetrySdk
+
+class AdvisoryParameterTests: XCTestCase {
+    
+  func testHistogramExportedDataUsesCustomBucketsWithWaitingExporter() {
+    let waitingExporter = WaitingMetricExporter(numberToWaitFor: 1, aggregationTemporality: .delta)
+    let stableMeterProvider = StableMeterProviderSdk.builder()
+      .registerMetricReader(reader: StablePeriodicMetricReaderSdk(exporter: waitingExporter, exportInterval: 5.0))
+      .registerView(selector: InstrumentSelectorBuilder().build(), view: StableView.builder().build())
+      .build()
+    
+    let meter = stableMeterProvider.meterBuilder(name: "testMeter").build()
+    
+    let customBoundaries = [1.0, 5.0, 10.0, 25.0, 50.0, 100.0]
+    
+    let histogram = meter
+      .histogramBuilder(name: "test_histogram_with_custom_buckets")
+      .setExplicitBucketBoundariesAdvice(customBoundaries)
+      .build()
+    
+    // Record some values to generate data
+    histogram.record(value: 3.0)   // Should fall in bucket [1.0, 5.0)
+    histogram.record(value: 7.0)   // Should fall in bucket [5.0, 10.0)
+    histogram.record(value: 15.0)  // Should fall in bucket [10.0, 25.0)
+    histogram.record(value: 75.0)  // Should fall in bucket [50.0, 100.0)
+    histogram.record(value: 150.0) // Should fall in the overflow bucket (>100.0)
+    
+    // Wait for export using the waiting exporter
+    let metrics = waitingExporter.waitForExport()
+    
+    // Verify that we received the expected metric
+    XCTAssertEqual(metrics.count, 1)
+    
+    let metricData = metrics[0]
+    XCTAssertEqual(metricData.name, "test_histogram_with_custom_buckets")
+    XCTAssertEqual(metricData.type, .Histogram)
+    
+    // Get the histogram data and verify the boundaries
+    let histogramData = metricData.getHistogramData()
+    XCTAssertEqual(histogramData.count, 1)
+    
+    let pointData = histogramData[0]
+    
+    // Verify that the exported data uses our custom boundaries
+    XCTAssertEqual(pointData.boundaries, customBoundaries)
+    
+    // Verify the bucket counts match our recorded values
+    // Expected bucket counts: [0, 1, 1, 1, 0, 1, 1] 
+    // (empty bucket <1.0, then 1 value in each: [1-5), [5-10), [10-25), empty [25-50), 1 in [50-100), 1 in overflow >100)
+    let expectedCounts = [0, 1, 1, 1, 0, 1, 1]
+    XCTAssertEqual(pointData.counts, expectedCounts)
+    
+    // Verify total count and sum
+    XCTAssertEqual(pointData.count, 5)
+    XCTAssertEqual(pointData.sum, 250.0) // 3 + 7 + 15 + 75 + 150
+    
+    // Verify min and max
+    XCTAssertEqual(pointData.min, 3.0)
+    XCTAssertEqual(pointData.max, 150.0)
+  }
+}