feat(opentelemetry-otlp): support histogram aggregation configuration

michaelbeaumont · michaelbeaumont · commit 4203559c74ae · 2026-04-09T12:43:44.000+02:00
diff --git a/opentelemetry-otlp/src/exporter/http/mod.rs b/opentelemetry-otlp/src/exporter/http/mod.rs
@@ -342,6 +342,7 @@ impl HttpExporterBuilder {
     pub fn build_metrics_exporter(
         mut self,
         temporality: opentelemetry_sdk::metrics::Temporality,
+        histogram_aggregation: opentelemetry_sdk::metrics::HistogramAggregation,
     ) -> Result<crate::MetricExporter, ExporterBuildError> {
         use crate::{
             OTEL_EXPORTER_OTLP_METRICS_COMPRESSION, OTEL_EXPORTER_OTLP_METRICS_ENDPOINT,
@@ -356,7 +357,11 @@ impl HttpExporterBuilder {
             OTEL_EXPORTER_OTLP_METRICS_COMPRESSION,
         )?;
 
-        Ok(crate::MetricExporter::from_http(client, temporality))
+        Ok(crate::MetricExporter::from_http(
+            client,
+            temporality,
+            histogram_aggregation,
+        ))
     }
 }
 
diff --git a/opentelemetry-otlp/src/exporter/tonic/mod.rs b/opentelemetry-otlp/src/exporter/tonic/mod.rs
@@ -367,6 +367,7 @@ impl TonicExporterBuilder {
     pub(crate) fn build_metrics_exporter(
         self,
         temporality: opentelemetry_sdk::metrics::Temporality,
+        histogram_aggregation: opentelemetry_sdk::metrics::HistogramAggregation,
     ) -> Result<crate::MetricExporter, ExporterBuildError> {
         use crate::MetricExporter;
         use metrics::TonicMetricsClient;
@@ -382,7 +383,11 @@ impl TonicExporterBuilder {
 
         let client = TonicMetricsClient::new(channel, interceptor, compression, retry_policy);
 
-        Ok(MetricExporter::from_tonic(client, temporality))
+        Ok(MetricExporter::from_tonic(
+            client,
+            temporality,
+            histogram_aggregation,
+        ))
     }
 
     /// Build a new tonic span exporter
diff --git a/opentelemetry-otlp/src/lib.rs b/opentelemetry-otlp/src/lib.rs
@@ -243,6 +243,7 @@
 //! | `OTEL_EXPORTER_OTLP_METRICS_HEADERS` | Signal-specific headers for metrics exports. |
 //! | `OTEL_EXPORTER_OTLP_METRICS_COMPRESSION` | Signal-specific compression for metrics exports. |
 //! | `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` | Temporality preference for metrics. Valid values: `cumulative`, `delta`, `lowmemory` (case-insensitive). | `cumulative` |
+//! | `OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION` | Default histogram aggregation. Valid values: `explicit_bucket_histogram`, `base2_exponential_bucket_histogram` (case-insensitive). | `explicit_bucket_histogram` |
 //!
 //! ## Logs
 //!
@@ -659,8 +660,9 @@ pub use crate::span::{
 #[cfg(any(feature = "http-proto", feature = "http-json", feature = "grpc-tonic"))]
 pub use crate::metric::{
     MetricExporter, MetricExporterBuilder, OTEL_EXPORTER_OTLP_METRICS_COMPRESSION,
-    OTEL_EXPORTER_OTLP_METRICS_ENDPOINT, OTEL_EXPORTER_OTLP_METRICS_HEADERS,
-    OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE, OTEL_EXPORTER_OTLP_METRICS_TIMEOUT,
+    OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION, OTEL_EXPORTER_OTLP_METRICS_ENDPOINT,
+    OTEL_EXPORTER_OTLP_METRICS_HEADERS, OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE,
+    OTEL_EXPORTER_OTLP_METRICS_TIMEOUT,
 };
 
 #[cfg(feature = "logs")]
diff --git a/opentelemetry-otlp/src/metric.rs b/opentelemetry-otlp/src/metric.rs
@@ -24,7 +24,7 @@ use core::fmt;
 use opentelemetry_sdk::error::OTelSdkResult;
 
 use opentelemetry_sdk::metrics::{
-    data::ResourceMetrics, exporter::PushMetricExporter, Temporality,
+    data::ResourceMetrics, exporter::PushMetricExporter, HistogramAggregation, Temporality,
 };
 use std::fmt::{Debug, Formatter};
 use std::time::Duration;
@@ -45,12 +45,18 @@ pub const OTEL_EXPORTER_OTLP_METRICS_HEADERS: &str = "OTEL_EXPORTER_OTLP_METRICS
 /// Temporality preference for metrics, defaults to cumulative.
 pub const OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE: &str =
     "OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE";
+/// Default histogram aggregation for metrics.
+/// Valid values: `explicit_bucket_histogram`, `base2_exponential_bucket_histogram` (case-insensitive).
+/// Defaults to `explicit_bucket_histogram`.
+pub const OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION: &str =
+    "OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION";
 
 /// A builder for creating a new [MetricExporter].
 #[derive(Debug, Default, Clone)]
 pub struct MetricExporterBuilder<C> {
     client: C,
     temporality: Option<Temporality>,
+    histogram_aggregation: Option<HistogramAggregation>,
 }
 
 impl MetricExporterBuilder<NoExporterBuilderSet> {
@@ -89,6 +95,7 @@ impl<C> MetricExporterBuilder<C> {
         MetricExporterBuilder {
             client: TonicExporterBuilderSet(TonicExporterBuilder::default()),
             temporality: self.temporality,
+            histogram_aggregation: self.histogram_aggregation,
         }
     }
 
@@ -98,6 +105,7 @@ impl<C> MetricExporterBuilder<C> {
         MetricExporterBuilder {
             client: HttpExporterBuilderSet(HttpExporterBuilder::default()),
             temporality: self.temporality,
+            histogram_aggregation: self.histogram_aggregation,
         }
     }
 
@@ -108,6 +116,25 @@ impl<C> MetricExporterBuilder<C> {
         MetricExporterBuilder {
             client: self.client,
             temporality: Some(temporality),
+            histogram_aggregation: self.histogram_aggregation,
+        }
+    }
+
+    /// Set the default histogram aggregation for the metrics.
+    ///
+    /// Valid values: [HistogramAggregation::ExplicitBucketHistogram] (default),
+    /// [HistogramAggregation::Base2ExponentialBucketHistogram].
+    ///
+    /// Note: Programmatically setting this will override any value set via the
+    /// `OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION` environment variable.
+    pub fn with_histogram_aggregation(
+        self,
+        histogram_aggregation: HistogramAggregation,
+    ) -> MetricExporterBuilder<C> {
+        MetricExporterBuilder {
+            client: self.client,
+            temporality: self.temporality,
+            histogram_aggregation: Some(histogram_aggregation),
         }
     }
 }
@@ -132,12 +159,40 @@ fn resolve_temporality(provided: Option<Temporality>) -> Result<Temporality, Exp
     Ok(Temporality::default())
 }
 
+/// Resolve histogram aggregation with priority:
+/// 1. Provided config value
+/// 2. OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION environment variable
+/// 3. Default (ExplicitBucketHistogram)
+#[cfg(any(feature = "http-proto", feature = "http-json", feature = "grpc-tonic"))]
+fn resolve_histogram_aggregation(
+    provided: Option<HistogramAggregation>,
+) -> Result<HistogramAggregation, ExporterBuildError> {
+    if let Some(histogram_aggregation) = provided {
+        return Ok(histogram_aggregation);
+    }
+    if let Ok(val) = std::env::var(OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION) {
+        return val
+            .parse::<HistogramAggregation>()
+            .map_err(|_| ExporterBuildError::InvalidConfig {
+                name: OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION.to_string(),
+                reason: format!(
+                    "Invalid value '{val}'. Expected: explicit_bucket_histogram or base2_exponential_bucket_histogram"
+                ),
+            });
+    }
+    Ok(HistogramAggregation::default())
+}
+
 #[cfg(feature = "grpc-tonic")]
 impl MetricExporterBuilder<TonicExporterBuilderSet> {
     /// Build the [MetricExporter] with the gRPC Tonic transport.
     pub fn build(self) -> Result<MetricExporter, ExporterBuildError> {
         let temporality = resolve_temporality(self.temporality)?;
-        let exporter = self.client.0.build_metrics_exporter(temporality)?;
+        let histogram_aggregation = resolve_histogram_aggregation(self.histogram_aggregation)?;
+        let exporter = self
+            .client
+            .0
+            .build_metrics_exporter(temporality, histogram_aggregation)?;
         opentelemetry::otel_debug!(name: "MetricExporterBuilt");
         Ok(exporter)
     }
@@ -148,7 +203,11 @@ impl MetricExporterBuilder<HttpExporterBuilderSet> {
     /// Build the [MetricExporter] with the HTTP transport.
     pub fn build(self) -> Result<MetricExporter, ExporterBuildError> {
         let temporality = resolve_temporality(self.temporality)?;
-        let exporter = self.client.0.build_metrics_exporter(temporality)?;
+        let histogram_aggregation = resolve_histogram_aggregation(self.histogram_aggregation)?;
+        let exporter = self
+            .client
+            .0
+            .build_metrics_exporter(temporality, histogram_aggregation)?;
         Ok(exporter)
     }
 }
@@ -194,6 +253,7 @@ pub(crate) trait MetricsClient: fmt::Debug + Send + Sync + 'static {
 pub struct MetricExporter {
     client: SupportedTransportClient,
     temporality: Temporality,
+    histogram_aggregation: HistogramAggregation,
 }
 
 #[derive(Debug)]
@@ -241,6 +301,10 @@ impl PushMetricExporter for MetricExporter {
     fn temporality(&self) -> Temporality {
         self.temporality
     }
+
+    fn default_histogram_aggregation(&self) -> HistogramAggregation {
+        self.histogram_aggregation
+    }
 }
 
 impl MetricExporter {
@@ -253,21 +317,25 @@ impl MetricExporter {
     pub(crate) fn from_tonic(
         client: crate::exporter::tonic::metrics::TonicMetricsClient,
         temporality: Temporality,
+        histogram_aggregation: HistogramAggregation,
     ) -> Self {
         Self {
             client: SupportedTransportClient::Tonic(client),
             temporality,
+            histogram_aggregation,
         }
     }
 
     #[cfg(any(feature = "http-proto", feature = "http-json"))]
     pub(crate) fn from_http(
         client: crate::exporter::http::OtlpHttpClient,
         temporality: Temporality,
+        histogram_aggregation: HistogramAggregation,
     ) -> Self {
         Self {
             client: SupportedTransportClient::Http(client),
             temporality,
+            histogram_aggregation,
         }
     }
 }
@@ -373,4 +441,97 @@ mod tests {
             assert_eq!(result, Temporality::Cumulative);
         });
     }
+
+    #[test]
+    fn histogram_aggregation_code_config_overrides_env_var() {
+        run_env_test(
+            vec![(
+                OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION,
+                "explicit_bucket_histogram",
+            )],
+            || {
+                let result = resolve_histogram_aggregation(Some(
+                    HistogramAggregation::Base2ExponentialBucketHistogram,
+                ))
+                .unwrap();
+                assert_eq!(
+                    result,
+                    HistogramAggregation::Base2ExponentialBucketHistogram
+                );
+            },
+        );
+    }
+
+    #[test]
+    fn histogram_aggregation_env_var_sets_explicit_bucket() {
+        run_env_test(
+            vec![(
+                OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION,
+                "explicit_bucket_histogram",
+            )],
+            || {
+                let result = resolve_histogram_aggregation(None).unwrap();
+                assert_eq!(result, HistogramAggregation::ExplicitBucketHistogram);
+            },
+        );
+    }
+
+    #[test]
+    fn histogram_aggregation_env_var_sets_base2_exponential() {
+        run_env_test(
+            vec![(
+                OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION,
+                "base2_exponential_bucket_histogram",
+            )],
+            || {
+                let result = resolve_histogram_aggregation(None).unwrap();
+                assert_eq!(
+                    result,
+                    HistogramAggregation::Base2ExponentialBucketHistogram
+                );
+            },
+        );
+    }
+
+    #[test]
+    fn histogram_aggregation_env_var_case_insensitive() {
+        run_env_test(
+            vec![(
+                OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION,
+                "BASE2_EXPONENTIAL_BUCKET_HISTOGRAM",
+            )],
+            || {
+                let result = resolve_histogram_aggregation(None).unwrap();
+                assert_eq!(
+                    result,
+                    HistogramAggregation::Base2ExponentialBucketHistogram
+                );
+            },
+        );
+    }
+
+    #[test]
+    fn histogram_aggregation_invalid_env_var_returns_error() {
+        run_env_test(
+            vec![(
+                OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION,
+                "invalid",
+            )],
+            || {
+                let result = resolve_histogram_aggregation(None);
+                assert!(result.is_err());
+            },
+        );
+    }
+
+    #[test]
+    fn histogram_aggregation_default_when_nothing_set() {
+        temp_env::with_var_unset(
+            OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION,
+            || {
+                let result = resolve_histogram_aggregation(None).unwrap();
+                assert_eq!(result, HistogramAggregation::ExplicitBucketHistogram);
+            },
+        );
+    }
 }
