[API] Add synchronous gauge (open-telemetry#3029)

* Add synchronous gauge * Add ABI Version macro, update tests * Fix function description * Fix formatting * Remove ABI macros from SDK. * Add error log for gauge delta temporality. * Fix formatting * Apply suggestions from code review Move kGauge to the end, for better ABI compatibility. --------- Co-authored-by: Lalit Kumar Bhasin <[email protected]> Co-authored-by: Marc Alff <[email protected]>
esigo · Oct 30, 2024 · f30ab92 · f30ab92 · github-actions · Oct 31, 2024
1 parent 6292a6a
commit f30ab92
Show file tree

Hide file tree

Showing 20 changed files with 664 additions and 2 deletions.
diff --git a/api/include/opentelemetry/metrics/meter.h b/api/include/opentelemetry/metrics/meter.h
@@ -21,6 +21,9 @@ class Histogram;
 template <typename T>
 class UpDownCounter;
 
+template <typename T>
+class Gauge;
+
 class ObservableInstrument;
 
 /**
@@ -91,6 +94,27 @@ class Meter
       nostd::string_view description = "",
       nostd::string_view unit        = "") noexcept = 0;
 
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
+  /**
+   * Creates a Gauge with the passed characteristics and returns a unique_ptr to that Gauge.
+   *
+   * @param name the name of the new Gauge.
+   * @param description a brief description of what the Gauge is used for.
+   * @param unit the unit of metric values following https://unitsofmeasure.org/ucum.html.
+   * @return a unique pointer to the created Gauge.
+   */
+
+  virtual nostd::unique_ptr<Gauge<int64_t>> CreateInt64Gauge(
+      nostd::string_view name,
+      nostd::string_view description = "",
+      nostd::string_view unit        = "") noexcept = 0;
+
+  virtual nostd::unique_ptr<Gauge<double>> CreateDoubleGauge(
+      nostd::string_view name,
+      nostd::string_view description = "",
+      nostd::string_view unit        = "") noexcept = 0;
+#endif
+
   /**
    * Creates a Asynchronous (Observable) Gauge with the passed characteristics and returns a
    * shared_ptr to that Observable Gauge

diff --git a/api/include/opentelemetry/metrics/noop.h b/api/include/opentelemetry/metrics/noop.h
@@ -71,6 +71,26 @@ class NoopUpDownCounter : public UpDownCounter<T>
   {}
 };
 
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
+template <class T>
+class NoopGauge : public Gauge<T>
+{
+public:
+  NoopGauge(nostd::string_view /* name */,
+            nostd::string_view /* description */,
+            nostd::string_view /* unit */) noexcept
+  {}
+  ~NoopGauge() override = default;
+  void Record(T /* value */) noexcept override {}
+  void Record(T /* value */, const context::Context & /* context */) noexcept override {}
+  void Record(T /* value */, const common::KeyValueIterable & /* attributes */) noexcept override {}
+  void Record(T /* value */,
+              const common::KeyValueIterable & /* attributes */,
+              const context::Context & /* context */) noexcept override
+  {}
+};
+#endif
+
 class NoopObservableInstrument : public ObservableInstrument
 {
 public:
@@ -140,6 +160,22 @@ class NoopMeter final : public Meter
     return nostd::unique_ptr<Histogram<double>>{new NoopHistogram<double>(name, description, unit)};
   }
 
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
+  nostd::unique_ptr<Gauge<int64_t>> CreateInt64Gauge(nostd::string_view name,
+                                                     nostd::string_view description = "",
+                                                     nostd::string_view unit = "") noexcept override
+  {
+    return nostd::unique_ptr<Gauge<int64_t>>{new NoopGauge<int64_t>(name, description, unit)};
+  }
+
+  nostd::unique_ptr<Gauge<double>> CreateDoubleGauge(nostd::string_view name,
+                                                     nostd::string_view description = "",
+                                                     nostd::string_view unit = "") noexcept override
+  {
+    return nostd::unique_ptr<Gauge<double>>{new NoopGauge<double>(name, description, unit)};
+  }
+#endif
+
   nostd::shared_ptr<ObservableInstrument> CreateInt64ObservableGauge(
       nostd::string_view name,
       nostd::string_view description = "",

diff --git a/api/include/opentelemetry/metrics/sync_instruments.h b/api/include/opentelemetry/metrics/sync_instruments.h
@@ -247,5 +247,82 @@ class UpDownCounter : public SynchronousInstrument
   }
 };
 
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
+/* A Gauge instrument that records values. */
+template <class T>
+class Gauge : public SynchronousInstrument
+{
+
+public:
+  /**
+   * Record a value
+   *
+   * @param value The measurement value. May be positive, negative or zero.
+   */
+  virtual void Record(T value) noexcept = 0;
+
+  /**
+   * Record a value
+   *
+   * @param value The measurement value. May be positive, negative or zero.
+   * @param context The explicit context to associate with this measurement.
+   */
+  virtual void Record(T value, const context::Context &context) noexcept = 0;
+
+  /**
+   * Record a value with a set of attributes.
+   *
+   * @param value The measurement value. May be positive, negative or zero.
+   * @param attributes A set of attributes to associate with the value.
+   */
+
+  virtual void Record(T value, const common::KeyValueIterable &attributes) noexcept = 0;
+
+  /**
+   * Record a value with a set of attributes.
+   *
+   * @param value The measurement value. May be positive, negative or zero.
+   * @param attributes A set of attributes to associate with the value.
+   * @param context The explicit context to associate with this measurement.
+   */
+  virtual void Record(T value,
+                      const common::KeyValueIterable &attributes,
+                      const context::Context &context) noexcept = 0;
+
+  template <class U,
+            nostd::enable_if_t<common::detail::is_key_value_iterable<U>::value> * = nullptr>
+  void Record(T value, const U &attributes) noexcept
+  {
+    this->Record(value, common::KeyValueIterableView<U>{attributes});
+  }
+
+  template <class U,
+            nostd::enable_if_t<common::detail::is_key_value_iterable<U>::value> * = nullptr>
+  void Record(T value, const U &attributes, const context::Context &context) noexcept
+  {
+    this->Record(value, common::KeyValueIterableView<U>{attributes}, context);
+  }
+
+  void Record(T value,
+              std::initializer_list<std::pair<nostd::string_view, common::AttributeValue>>
+                  attributes) noexcept
+  {
+    this->Record(value, nostd::span<const std::pair<nostd::string_view, common::AttributeValue>>{
+                            attributes.begin(), attributes.end()});
+  }
+
+  void Record(
+      T value,
+      std::initializer_list<std::pair<nostd::string_view, common::AttributeValue>> attributes,
+      const context::Context &context) noexcept
+  {
+    this->Record(value,
+                 nostd::span<const std::pair<nostd::string_view, common::AttributeValue>>{
+                     attributes.begin(), attributes.end()},
+                 context);
+  }
+};
+#endif
+
 }  // namespace metrics
 OPENTELEMETRY_END_NAMESPACE
diff --git a/examples/common/metrics_foo_library/foo_library.cc b/examples/common/metrics_foo_library/foo_library.cc
@@ -107,3 +107,22 @@ void foo_library::histogram_example(const std::string &name)
     std::this_thread::sleep_for(std::chrono::milliseconds(250));
   }
 }
+
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
+void foo_library::gauge_example(const std::string &name)
+{
+  std::string gauge_name = name + "_gauge";
+  auto provider          = metrics_api::Provider::GetMeterProvider();
+  opentelemetry::nostd::shared_ptr<metrics_api::Meter> meter = provider->GetMeter(name, "1.2.0");
+  auto gauge   = meter->CreateInt64Gauge(gauge_name, "des", "unit");
+  auto context = opentelemetry::context::Context{};
+  for (uint32_t i = 0; i < 20; ++i)
+  {
+    int64_t val                               = (rand() % 100) + 100;
+    std::map<std::string, std::string> labels = get_random_attr();
+    auto labelkv = opentelemetry::common::KeyValueIterableView<decltype(labels)>{labels};
+    gauge->Record(val, labelkv, context);
+    std::this_thread::sleep_for(std::chrono::milliseconds(250));
+  }
+}
+#endif
diff --git a/examples/common/metrics_foo_library/foo_library.h b/examples/common/metrics_foo_library/foo_library.h
@@ -11,4 +11,7 @@ class foo_library
   static void counter_example(const std::string &name);
   static void histogram_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);
+#endif
 };
diff --git a/examples/metrics_simple/metrics_ostream.cc b/examples/metrics_simple/metrics_ostream.cc
@@ -148,15 +148,27 @@ int main(int argc, char **argv)
   {
     foo_library::histogram_example(name);
   }
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
+  else if (example_type == "gauge")
+  {
+    foo_library::gauge_example(name);
+  }
+#endif
   else
   {
     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();
     histogram_example.join();
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
+    gauge_example.join();
+#endif
   }
 
   CleanupMetrics();

diff --git a/examples/otlp/file_metric_main.cc b/examples/otlp/file_metric_main.cc
@@ -98,15 +98,27 @@ int main(int argc, char *argv[])
   {
     foo_library::histogram_example(name);
   }
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
+  else if (example_type == "gauge")
+  {
+    foo_library::gauge_example(name);
+  }
+#endif
   else
   {
     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();
     histogram_example.join();
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
+    gauge_example.join();
+#endif
   }
 
   CleanupMetrics();

diff --git a/examples/otlp/grpc_metric_main.cc b/examples/otlp/grpc_metric_main.cc
@@ -93,15 +93,27 @@ int main(int argc, char *argv[])
   {
     foo_library::histogram_example(name);
   }
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
+  else if (example_type == "gauge")
+  {
+    foo_library::gauge_example(name);
+  }
+#endif
   else
   {
     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();
     histogram_example.join();
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
+    gauge_example.join();
+#endif
   }
 
   CleanupMetrics();

diff --git a/examples/otlp/http_metric_main.cc b/examples/otlp/http_metric_main.cc
@@ -133,15 +133,27 @@ int main(int argc, char *argv[])
   {
     foo_library::histogram_example(name);
   }
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
+  else if (example_type == "gauge")
+  {
+    foo_library::gauge_example(name);
+  }
+#endif
   else
   {
     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();
     histogram_example.join();
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
+    gauge_example.join();
+#endif
   }
 
   CleanupMetrics();

diff --git a/exporters/otlp/src/otlp_metric_utils.cc b/exporters/otlp/src/otlp_metric_utils.cc
@@ -297,6 +297,7 @@ sdk::metrics::AggregationTemporality OtlpMetricUtils::DeltaTemporalitySelector(
     case sdk::metrics::InstrumentType::kObservableCounter:
     case sdk::metrics::InstrumentType::kHistogram:
     case sdk::metrics::InstrumentType::kObservableGauge:
+    case sdk::metrics::InstrumentType::kGauge:
       return sdk::metrics::AggregationTemporality::kDelta;
     case sdk::metrics::InstrumentType::kUpDownCounter:
     case sdk::metrics::InstrumentType::kObservableUpDownCounter:
@@ -320,6 +321,7 @@ sdk::metrics::AggregationTemporality OtlpMetricUtils::LowMemoryTemporalitySelect
     case sdk::metrics::InstrumentType::kHistogram:
       return sdk::metrics::AggregationTemporality::kDelta;
     case sdk::metrics::InstrumentType::kObservableCounter:
+    case sdk::metrics::InstrumentType::kGauge:
     case sdk::metrics::InstrumentType::kObservableGauge:
     case sdk::metrics::InstrumentType::kUpDownCounter:
     case sdk::metrics::InstrumentType::kObservableUpDownCounter:

diff --git a/sdk/include/opentelemetry/sdk/metrics/aggregation/default_aggregation.h b/sdk/include/opentelemetry/sdk/metrics/aggregation/default_aggregation.h
@@ -180,6 +180,7 @@ class DefaultAggregation
         return AggregationType::kSum;
       case InstrumentType::kHistogram:
         return AggregationType::kHistogram;
+      case InstrumentType::kGauge:
       case InstrumentType::kObservableGauge:
         return AggregationType::kLastValue;
       default:

diff --git a/sdk/include/opentelemetry/sdk/metrics/instruments.h b/sdk/include/opentelemetry/sdk/metrics/instruments.h
@@ -21,7 +21,8 @@ enum class InstrumentType
   kUpDownCounter,
   kObservableCounter,
   kObservableGauge,
-  kObservableUpDownCounter
+  kObservableUpDownCounter,
+  kGauge
 };
 
 enum class InstrumentClass

diff --git a/sdk/include/opentelemetry/sdk/metrics/meter.h b/sdk/include/opentelemetry/sdk/metrics/meter.h
@@ -75,6 +75,18 @@ class Meter final : public opentelemetry::metrics::Meter
       nostd::string_view description = "",
       nostd::string_view unit        = "") noexcept override;
 
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
+  nostd::unique_ptr<opentelemetry::metrics::Gauge<int64_t>> CreateInt64Gauge(
+      nostd::string_view name,
+      nostd::string_view description = "",
+      nostd::string_view unit        = "") noexcept override;
+
+  nostd::unique_ptr<opentelemetry::metrics::Gauge<double>> CreateDoubleGauge(
+      nostd::string_view name,
+      nostd::string_view description = "",
+      nostd::string_view unit        = "") noexcept override;
+#endif
+
   nostd::shared_ptr<opentelemetry::metrics::ObservableInstrument> CreateInt64ObservableGauge(
       nostd::string_view name,
       nostd::string_view description = "",
Benchmark suite	Current: `f30ab92`	Previous: `5089105`	Ratio
`BM_SpinLockThrashing/1/process_time/real_time`	`0.2824906544583288` ms/iter	`0.09306904516722027` ms/iter	`3.04`
`BM_SpinLockThrashing/2/process_time/real_time`	`0.9704712641279035` ms/iter	`0.17345299134538503` ms/iter	`5.60`
`BM_SpinLockThrashing/4/process_time/real_time`	`2.6524214097011236` ms/iter	`0.6834950613145211` ms/iter	`3.88`
`BM_ProcYieldSpinLockThrashing/4/process_time/real_time`	`1.542646519459077` ms/iter	`0.7243640352003645` ms/iter	`2.13`
`BM_ExtractBaggageWith180Entries`	`1.5100869039502278` ns/iter	`0.707789819587833` ns/iter	`2.13`