examples/metrics-advanced: add explanation

Author: thomasstauffer666

examples/metrics-advanced/src/main.rs

@@ -34,6 +34,20 @@ fn init_meter_provider() -> opentelemetry_sdk::metrics::SdkMeterProvider {
     };
 
     // for example 3
+    // Unlike a regular OpenTelemetry histogram with fixed buckets, which can be
+    // specified explicitly, an exponential histogram calculates bucket widths
+    // automatically, growing them exponentially. The configuration is
+    // controlled by two parameters: max_size defines the maximum number of
+    // buckets, while max_scale adjusts the resolution, with higher values
+    // providing greater precision.
+    // If the minimum and maximum values are known in advance, a regular
+    // histogram is often the better choice. However, if the range of values is
+    // unpredictable e.g. may include extreme outliers, an exponential histogram
+    // is more suitable. A example is measuring packet round-trip time in a
+    // WLAN: while most packets return in milliseconds, some may occasionally
+    // take hundreds of milliseconds or even seconds.
+    // Details are in:
+    // https://opentelemetry.io/docs/specs/otel/metrics/data-model/#exponentialhistogram
     let my_view_change_aggregation = |i: &Instrument| {
         if i.name() == "my_third_histogram" {
             Stream::builder()
@@ -137,6 +151,11 @@ async fn main() -> Result<(), Box<dyn Error + Send + Sync + 'static>> {
     histogram3.record(-1.3, &[KeyValue::new("mykey1", "myvalue1")]);
     histogram3.record(-5.5, &[KeyValue::new("mykey1", "myvalue1")]);
     histogram3.record(7.5, &[KeyValue::new("mykey1", "myvalue1")]);
+    // Internally the exponential histogram puts values either into a list of
+    // negative buckets or a list of positive buckets. Based on the values which
+    // are added the buckets are adjusted automatically. E.g. if the next record
+    // is commented/uncommented, will result in a exponential histogram with a
+    // different scale.
     histogram3.record(0.4, &[KeyValue::new("mykey1", "myvalue1")]);
 
     // Metrics are exported by default every 60 seconds when using stdout exporter,