[SDK] Base2 exponential histogram aggregation

.vscode/launch.json

@@ -1,24 +1,33 @@
 {
   "version": "0.2.0",
   "configurations": [
-      {
-          "name": "Debug on Windows",
-          "type": "cppvsdbg",
-          "request": "launch",
-          "program": "${workspaceFolder}/build/<path-to-bin-file>",
-          "args": [],
-          "stopAtEntry": false,
-          "cwd": "${workspaceFolder}",
-          "environment": [],
-          "externalConsole": false
-      },
-      {
-          "name": "Debug on Linux",
-          "type": "gdb",
-          "request": "launch",
-          "target": "${workspaceFolder}/bazel-bin/<path to the bin file>",
-          "cwd": "${workspaceRoot}",
-          "valuesFormatting": "parseText"
-      }
+    {
+        "name": "(ctest) Launch",
+        "type": "cppdbg",
+        "cwd": "${cmake.testWorkingDirectory}",
+        "request": "launch",
+        "program": "${cmake.testProgram}",
+        "args": [ "${cmake.testArgs}" ],
+        // other options...
+    },
+    {
+        "name": "Debug on Windows",
+        "type": "cppvsdbg",
+        "request": "launch",
+        "program": "${workspaceFolder}/build/<path-to-bin-file>",
+        "args": [],
+        "stopAtEntry": false,
+        "cwd": "${workspaceFolder}",
+        "environment": [],
+        "externalConsole": false
+    },
+    {
+        "name": "Debug on Linux",
+        "type": "gdb",
+        "request": "launch",
+        "target": "${workspaceFolder}/bazel-bin/<path to the bin file>",
+        "cwd": "${workspaceRoot}",
+        "valuesFormatting": "parseText"
+    }
   ]
 }

CHANGELOG.md

@@ -13,6 +13,17 @@ Increment the:
 * MINOR version when you add functionality in a backwards compatible manner, and
 * PATCH version when you make backwards compatible bug fixes.
 
+## [1.21 2025-04-04]
+
+* [SDK] Base2 exponential histogram aggregation
+  [#3175](https://github.com/open-telemetry/opentelemetry-cpp/pull/3346)
+
+  New Features:
+
+  Add base2 exponential histogram aggregation. Includes a new aggregation type,
+  ostream exporter, and otlp/grpc exporter. Updated histogram aggregation and
+  benchmark tests.
+
 ## [Unreleased]
 
 * [API] Remove `WITH_ABSEIL` and `HAVE_ABSEIL`

examples/common/metrics_foo_library/foo_library.cc

@@ -100,7 +100,24 @@ void foo_library::histogram_example(const std::string &name)
   std::string histogram_name = name + "_histogram";
   auto provider              = metrics_api::Provider::GetMeterProvider();
   opentelemetry::nostd::shared_ptr<metrics_api::Meter> meter = provider->GetMeter(name, "1.2.0");
-  auto histogram_counter = meter->CreateDoubleHistogram(histogram_name, "des", "unit");
+  auto histogram_counter = meter->CreateDoubleHistogram(histogram_name, "des", "histogram-unit");
+  auto context           = opentelemetry::context::Context{};
+  for (uint32_t i = 0; i < 20; ++i)
+  {
+    double val                                = (rand() % 700) + 1.1;
+    std::map<std::string, std::string> labels = get_random_attr();
+    auto labelkv = opentelemetry::common::KeyValueIterableView<decltype(labels)>{labels};
+    histogram_counter->Record(val, labelkv, context);
+    std::this_thread::sleep_for(std::chrono::milliseconds(250));
+  }
+}
+
+void foo_library::histogram_exp_example(const std::string &name)
+{
+  std::string histogram_name = name + "_exponential_histogram";
+  auto provider              = metrics_api::Provider::GetMeterProvider();
+  opentelemetry::nostd::shared_ptr<metrics_api::Meter> meter = provider->GetMeter(name, "1.2.0");
+  auto histogram_counter = meter->CreateDoubleHistogram(histogram_name, "des", "histogram-unit");
   auto context           = opentelemetry::context::Context{};
   for (uint32_t i = 0; i < 20; ++i)
   {

examples/common/metrics_foo_library/foo_library.h

@@ -10,6 +10,7 @@ class foo_library
 public:
   static void counter_example(const std::string &name);
   static void histogram_example(const std::string &name);
+  static void histogram_exp_example(const std::string &name);
   static void observable_counter_example(const std::string &name);
 #if OPENTELEMETRY_ABI_VERSION_NO >= 2
   static void gauge_example(const std::string &name);

examples/metrics_simple/metrics_ostream.cc

@@ -15,6 +15,8 @@
 #include "opentelemetry/sdk/metrics/export/periodic_exporting_metric_reader_factory.h"
 #include "opentelemetry/sdk/metrics/export/periodic_exporting_metric_reader_options.h"
 #include "opentelemetry/sdk/metrics/instruments.h"
+#include "opentelemetry/sdk/metrics/meter_context.h"
+#include "opentelemetry/sdk/metrics/meter_context_factory.h"
 #include "opentelemetry/sdk/metrics/meter_provider.h"
 #include "opentelemetry/sdk/metrics/meter_provider_factory.h"
 #include "opentelemetry/sdk/metrics/metric_reader.h"
@@ -56,9 +58,9 @@ void InitMetrics(const std::string &name)
   auto reader =
       metrics_sdk::PeriodicExportingMetricReaderFactory::Create(std::move(exporter), options);
 
-  auto provider = opentelemetry::sdk::metrics::MeterProviderFactory::Create();
-
-  provider->AddMetricReader(std::move(reader));
+  auto context = metrics_sdk::MeterContextFactory::Create();
+  context->AddMetricReader(std::move(reader));
+  auto provider = opentelemetry::sdk::metrics::MeterProviderFactory::Create(std::move(context));
 
   // counter view
   std::string counter_name = name + "_counter";
@@ -112,6 +114,30 @@ void InitMetrics(const std::string &name)
   provider->AddView(std::move(histogram_instrument_selector), std::move(histogram_meter_selector),
                     std::move(histogram_view));
 
+  // hisogram view with base2 exponential aggregation
+  std::string histogram_base2_name         = name + "_exponential_histogram";
+  unit                                     = "histogram-unit";
+  auto histogram_base2_instrument_selector = metrics_sdk::InstrumentSelectorFactory::Create(
+      metrics_sdk::InstrumentType::kHistogram, histogram_base2_name, unit);
+  auto histogram_base2_meter_selector =
+      metrics_sdk::MeterSelectorFactory::Create(name, version, schema);
+  auto histogram_base2_aggregation_config =
+      std::unique_ptr<metrics_sdk::Base2ExponentialHistogramAggregationConfig>(
+          new metrics_sdk::Base2ExponentialHistogramAggregationConfig);
+  histogram_base2_aggregation_config->max_scale_      = 3;
+  histogram_base2_aggregation_config->record_min_max_ = true;
+  histogram_base2_aggregation_config->max_buckets_    = 100;
+
+  std::shared_ptr<metrics_sdk::AggregationConfig> base2_aggregation_config(
+      std::move(histogram_base2_aggregation_config));
+
+  auto histogram_base2_view = metrics_sdk::ViewFactory::Create(
+      name, "description", unit, metrics_sdk::AggregationType::kBase2ExponentialHistogram,
+      base2_aggregation_config);
+
+  provider->AddView(std::move(histogram_base2_instrument_selector),
+                    std::move(histogram_base2_meter_selector), std::move(histogram_base2_view));
+
   std::shared_ptr<opentelemetry::metrics::MeterProvider> api_provider(std::move(provider));
 
   metrics_sdk::Provider::SetMeterProvider(api_provider);
@@ -147,6 +173,10 @@ int main(int argc, char **argv)
   {
     foo_library::histogram_example(name);
   }
+  else if (example_type == "exponential_histogram")
+  {
+    foo_library::histogram_exp_example(name);
+  }
 #if OPENTELEMETRY_ABI_VERSION_NO >= 2
   else if (example_type == "gauge")
   {
@@ -170,6 +200,7 @@ int main(int argc, char **argv)
     std::thread counter_example{&foo_library::counter_example, name};
     std::thread observable_counter_example{&foo_library::observable_counter_example, name};
     std::thread histogram_example{&foo_library::histogram_example, name};
+    std::thread histogram_exp_example{&foo_library::histogram_exp_example, name};
 #if OPENTELEMETRY_ABI_VERSION_NO >= 2
     std::thread gauge_example{&foo_library::gauge_example, name};
 #endif
@@ -181,6 +212,7 @@ int main(int argc, char **argv)
     counter_example.join();
     observable_counter_example.join();
     histogram_example.join();
+    histogram_exp_example.join();
 #if OPENTELEMETRY_ABI_VERSION_NO >= 2
     gauge_example.join();
 #endif

examples/otlp/grpc_metric_main.cc

@@ -1,6 +1,9 @@
 // Copyright The OpenTelemetry Authors
 // SPDX-License-Identifier: Apache-2.0
 
+#include "grpcpp/grpcpp.h"
+#include "opentelemetry/exporters/otlp/otlp_grpc_exporter.h"
+
 #include "opentelemetry/exporters/otlp/otlp_grpc_metric_exporter_factory.h"
 #include "opentelemetry/metrics/provider.h"
 #include "opentelemetry/sdk/metrics/aggregation/default_aggregation.h"
@@ -11,6 +14,9 @@
 #include "opentelemetry/sdk/metrics/meter_provider.h"
 #include "opentelemetry/sdk/metrics/meter_provider_factory.h"
 #include "opentelemetry/sdk/metrics/provider.h"
+#include "opentelemetry/sdk/metrics/view/instrument_selector_factory.h"
+#include "opentelemetry/sdk/metrics/view/meter_selector_factory.h"
+#include "opentelemetry/sdk/metrics/view/view_factory.h"
 
 #include <memory>
 #include <thread>
@@ -31,7 +37,7 @@ namespace
 
 otlp_exporter::OtlpGrpcMetricExporterOptions exporter_options;
 
-void InitMetrics()
+void InitMetrics(std::string &name)
 {
   auto exporter = otlp_exporter::OtlpGrpcMetricExporterFactory::Create(exporter_options);
 
@@ -49,10 +55,39 @@ void InitMetrics()
   auto context = metric_sdk::MeterContextFactory::Create();
   context->AddMetricReader(std::move(reader));
 
-  auto u_provider = metric_sdk::MeterProviderFactory::Create(std::move(context));
-  std::shared_ptr<opentelemetry::metrics::MeterProvider> provider(std::move(u_provider));
+  auto provider = metric_sdk::MeterProviderFactory::Create(std::move(context));
+
+  // histogram view
+  std::string histogram_name = name + "_histogram";
+  std::string unit           = "unit";
+
+  auto histogram_instrument_selector = metric_sdk::InstrumentSelectorFactory::Create(
+      metric_sdk::InstrumentType::kHistogram, histogram_name, unit);
+
+  auto histogram_meter_selector = metric_sdk::MeterSelectorFactory::Create(name, version, schema);
+
+  auto histogram_aggregation_config =
+      std::unique_ptr<metric_sdk::Base2ExponentialHistogramAggregationConfig>(
+          new metric_sdk::Base2ExponentialHistogramAggregationConfig);
+
+  histogram_aggregation_config->max_scale_ = 3;
+
+  // histogram_aggregation_config->boundaries_ = std::vector<double>{
+  //     0.0, 50.0, 100.0, 250.0, 500.0, 750.0, 1000.0, 2500.0, 5000.0, 10000.0, 20000.0};
+
+  std::shared_ptr<metric_sdk::AggregationConfig> aggregation_config(
+      std::move(histogram_aggregation_config));
 
-  metric_sdk::Provider::SetMeterProvider(provider);
+  auto histogram_view = metric_sdk::ViewFactory::Create(
+      name, "description", unit, metric_sdk::AggregationType::kBase2ExponentialHistogram,
+      aggregation_config);
+
+  provider->AddView(std::move(histogram_instrument_selector), std::move(histogram_meter_selector),
+                    std::move(histogram_view));
+
+  std::shared_ptr<opentelemetry::metrics::MeterProvider> api_provider(std::move(provider));
+
+  metric_sdk::Provider::SetMeterProvider(api_provider);
 }
 
 void CleanupMetrics()
@@ -78,10 +113,17 @@ int main(int argc, char *argv[])
       }
     }
   }
+  std::cout << "Using endpoint: " << exporter_options.endpoint << std::endl;
+  std::cout << "Using example type: " << example_type << std::endl;
+  std::cout << "Using cacert path: " << exporter_options.ssl_credentials_cacert_path << std::endl;
+  std::cout << "Using ssl credentials: " << exporter_options.use_ssl_credentials << std::endl;
+
   // Removing this line will leave the default noop MetricProvider in place.
-  InitMetrics();
+
   std::string name{"otlp_grpc_metric_example"};
 
+  InitMetrics(name);
+
   if (example_type == "counter")
   {
     foo_library::counter_example(name);
@@ -94,6 +136,10 @@ int main(int argc, char *argv[])
   {
     foo_library::histogram_example(name);
   }
+  else if (example_type == "exponential_histogram")
+  {
+    foo_library::histogram_exp_example(name);
+  }
 #if OPENTELEMETRY_ABI_VERSION_NO >= 2
   else if (example_type == "gauge")
   {
@@ -102,15 +148,15 @@ int main(int argc, char *argv[])
 #endif
   else
   {
-    std::thread counter_example{&foo_library::counter_example, name};
-    std::thread observable_counter_example{&foo_library::observable_counter_example, name};
+    // std::thread counter_example{&foo_library::counter_example, name};
+    //  std::thread observable_counter_example{&foo_library::observable_counter_example, name};
     std::thread histogram_example{&foo_library::histogram_example, name};
 #if OPENTELEMETRY_ABI_VERSION_NO >= 2
     std::thread gauge_example{&foo_library::gauge_example, name};
 #endif
 
-    counter_example.join();
-    observable_counter_example.join();
+    // counter_example.join();
+    // observable_counter_example.join();
     histogram_example.join();
 #if OPENTELEMETRY_ABI_VERSION_NO >= 2
     gauge_example.join();

exporters/ostream/src/metric_exporter.cc

@@ -24,6 +24,7 @@
 #include "opentelemetry/sdk/common/exporter_utils.h"
 #include "opentelemetry/sdk/common/global_log_handler.h"
 #include "opentelemetry/sdk/instrumentationscope/instrumentation_scope.h"
+#include "opentelemetry/sdk/metrics/data/circular_buffer.h"
 #include "opentelemetry/sdk/metrics/data/metric_data.h"
 #include "opentelemetry/sdk/metrics/data/point_data.h"
 #include "opentelemetry/sdk/metrics/export/metric_producer.h"
@@ -247,6 +248,39 @@ void OStreamMetricExporter::printPointData(const opentelemetry::sdk::metrics::Po
       sout_ << nostd::get<int64_t>(last_point_data.value_);
     }
   }
+  else if (nostd::holds_alternative<sdk::metrics::Base2ExponentialHistogramPointData>(point_data))
+  {
+    auto histogram_point_data =
+        nostd::get<sdk::metrics::Base2ExponentialHistogramPointData>(point_data);
+    sout_ << "\n  type: Base2ExponentialHistogramPointData";
+    sout_ << "\n  count: " << histogram_point_data.count_;
+    sout_ << "\n  sum: " << histogram_point_data.sum_;
+    sout_ << "\n  zero_count: " << histogram_point_data.zero_count_;
+    if (histogram_point_data.record_min_max_)
+    {
+      sout_ << "\n  min: " << histogram_point_data.min_;
+      sout_ << "\n  max: " << histogram_point_data.max_;
+    }
+    sout_ << "\n  scale: " << histogram_point_data.scale_;
+    sout_ << "\n  positive buckets:";
+    if (!histogram_point_data.positive_buckets_.Empty())
+    {
+      for (auto i = histogram_point_data.positive_buckets_.StartIndex();
+           i <= histogram_point_data.positive_buckets_.EndIndex(); ++i)
+      {
+        sout_ << "\n\t" << i << ": " << histogram_point_data.positive_buckets_.Get(i);
+      }
+    }
+    sout_ << "\n  negative buckets:";
+    if (!histogram_point_data.negative_buckets_.Empty())
+    {
+      for (auto i = histogram_point_data.negative_buckets_.StartIndex();
+           i <= histogram_point_data.negative_buckets_.EndIndex(); ++i)
+      {
+        sout_ << "\n\t" << i << ": " << histogram_point_data.negative_buckets_.Get(i);
+      }
+    }
+  }
 }
 
 void OStreamMetricExporter::printPointAttributes(