feat: Add histogram metric type

include/triton/core/tritonserver.h

@@ -91,7 +91,7 @@ struct TRITONSERVER_MetricFamily;
 ///   }
 ///
 #define TRITONSERVER_API_VERSION_MAJOR 1
-#define TRITONSERVER_API_VERSION_MINOR 33
+#define TRITONSERVER_API_VERSION_MINOR 34
 
 /// Get the TRITONBACKEND API version supported by the Triton shared
 /// library. This value can be compared against the
@@ -2615,7 +2615,8 @@ TRITONSERVER_DECLSPEC struct TRITONSERVER_Error* TRITONSERVER_ServerInferAsync(
 ///
 typedef enum TRITONSERVER_metrickind_enum {
   TRITONSERVER_METRIC_KIND_COUNTER,
-  TRITONSERVER_METRIC_KIND_GAUGE
+  TRITONSERVER_METRIC_KIND_GAUGE,
+  TRITONSERVER_METRIC_KIND_HISTOGRAM
 } TRITONSERVER_MetricKind;
 
 /// Create a new metric family object. The caller takes ownership of the
@@ -2655,11 +2656,14 @@ TRITONSERVER_MetricFamilyDelete(struct TRITONSERVER_MetricFamily* family);
 /// \param family The metric family to add this new metric to.
 /// \param labels The array of labels to associate with this new metric.
 /// \param label_count The number of labels.
+/// \param buckets Monotonically increasing values representing the
+/// bucket boundaries. For histogram only.
 /// \return a TRITONSERVER_Error indicating success or failure.
 TRITONSERVER_DECLSPEC struct TRITONSERVER_Error* TRITONSERVER_MetricNew(
     struct TRITONSERVER_Metric** metric,
     struct TRITONSERVER_MetricFamily* family,
-    const struct TRITONSERVER_Parameter** labels, const uint64_t label_count);
+    const struct TRITONSERVER_Parameter** labels, const uint64_t label_count,
+    const void* buckets = nullptr);
 
 /// Delete a metric object.
 /// All TRITONSERVER_Metric* objects should be deleted BEFORE their
@@ -2672,9 +2676,10 @@ TRITONSERVER_DECLSPEC struct TRITONSERVER_Error* TRITONSERVER_MetricDelete(
     struct TRITONSERVER_Metric* metric);
 
 /// Get the current value of a metric object.
-/// Supports metrics of kind TRITONSERVER_METRIC_KIND_COUNTER
-/// and TRITONSERVER_METRIC_KIND_GAUGE, and returns
-/// TRITONSERVER_ERROR_UNSUPPORTED for unsupported TRITONSERVER_MetricKind.
+/// Supports metrics of kind TRITONSERVER_METRIC_KIND_COUNTER,
+/// TRITONSERVER_METRIC_KIND_GAUGE, TRITONSERVER_METRIC_KIND_HISTOGRAM, and
+/// returns TRITONSERVER_ERROR_UNSUPPORTED for unsupported
+/// TRITONSERVER_MetricKind.
 ///
 /// \param metric The metric object to query.
 /// \param value Returns the current value of the metric object.
@@ -2705,6 +2710,28 @@ TRITONSERVER_DECLSPEC struct TRITONSERVER_Error* TRITONSERVER_MetricIncrement(
 TRITONSERVER_DECLSPEC struct TRITONSERVER_Error* TRITONSERVER_MetricSet(
     struct TRITONSERVER_Metric* metric, double value);
 
+/// Observe the current value of metric to value.
+/// Supports metrics of kind TRITONSERVER_METRIC_KIND_HISTOGRAM and returns
+/// TRITONSERVER_ERROR_UNSUPPORTED for unsupported TRITONSERVER_MetricKind.
+///
+/// \param metric The metric object to update.
+/// \param value The amount to observe metric's value to.
+/// \return a TRITONSERVER_Error indicating success or failure.
+TRITONSERVER_DECLSPEC struct TRITONSERVER_Error* TRITONSERVER_MetricObserve(
+    struct TRITONSERVER_Metric* metric, double value);
+
+/// Collect metrics.
+/// Supports metrics of kind TRITONSERVER_METRIC_KIND_COUNTER,
+/// TRITONSERVER_METRIC_KIND_GAUGE, TRITONSERVER_METRIC_KIND_HISTOGRAM and
+/// returns TRITONSERVER_ERROR_UNSUPPORTED for unsupported
+/// TRITONSERVER_MetricKind.
+///
+/// \param metric The metric object to collect.
+/// \param value Returns the current value of the metric object.
+/// \return a TRITONSERVER_Error indicating success or failure.
+TRITONSERVER_DECLSPEC struct TRITONSERVER_Error* TRITONSERVER_MetricCollect(
+    struct TRITONSERVER_Metric* metric, void* value);
+
 /// Get the TRITONSERVER_MetricKind of metric and its corresponding family.
 ///
 /// \param metric The metric object to query.

python/tritonserver/_c/triton_bindings.pyi

@@ -357,6 +357,7 @@ class TRITONSERVER_Metric:
     ) -> None: ...
     def increment(self, arg0: float) -> None: ...
     def set_value(self, arg0: float) -> None: ...
+    def observe(self, arg0: float) -> None: ...
     @property
     def kind(self) -> TRITONSERVER_MetricKind: ...
     @property
@@ -384,6 +385,7 @@ class TRITONSERVER_MetricKind:
     __members__: ClassVar[dict] = ...  # read-only
     COUNTER: ClassVar[TRITONSERVER_MetricKind] = ...
     GAUGE: ClassVar[TRITONSERVER_MetricKind] = ...
+    HISTOGRAM: ClassVar[TRITONSERVER_MetricKind] = ...
     __entries: ClassVar[dict] = ...
     def __init__(self, value: int) -> None: ...
     def __eq__(self, other: object) -> bool: ...

python/tritonserver/_c/tritonserver_pybind.cc

@@ -1672,14 +1672,16 @@ class PyMetric : public PyWrapper<struct TRITONSERVER_Metric> {
   DESTRUCTOR_WITH_LOG(PyMetric, TRITONSERVER_MetricDelete);
   PyMetric(
       PyMetricFamily& family,
-      const std::vector<std::shared_ptr<PyParameter>>& labels)
+      const std::vector<std::shared_ptr<PyParameter>>& labels,
+      const std::vector<double>* buckets)
   {
     std::vector<const struct TRITONSERVER_Parameter*> params;
     for (const auto& label : labels) {
       params.emplace_back(label->Ptr());
     }
     ThrowIfError(TRITONSERVER_MetricNew(
-        &triton_object_, family.Ptr(), params.data(), params.size()));
+        &triton_object_, family.Ptr(), params.data(), params.size(),
+        reinterpret_cast<const void*>(buckets)));
     owned_ = true;
   }
 
@@ -1700,6 +1702,11 @@ class PyMetric : public PyWrapper<struct TRITONSERVER_Metric> {
     ThrowIfError(TRITONSERVER_MetricSet(triton_object_, val));
   }
 
+  void Observe(double val) const
+  {
+    ThrowIfError(TRITONSERVER_MetricObserve(triton_object_, val));
+  }
+
   TRITONSERVER_MetricKind Kind() const
   {
     TRITONSERVER_MetricKind val = TRITONSERVER_METRIC_KIND_COUNTER;
@@ -2140,7 +2147,8 @@ PYBIND11_MODULE(triton_bindings, m)
   // TRITONSERVER_MetricKind
   py::enum_<TRITONSERVER_MetricKind>(m, "TRITONSERVER_MetricKind")
       .value("COUNTER", TRITONSERVER_METRIC_KIND_COUNTER)
-      .value("GAUGE", TRITONSERVER_METRIC_KIND_GAUGE);
+      .value("GAUGE", TRITONSERVER_METRIC_KIND_GAUGE)
+      .value("HISTOGRAM", TRITONSERVER_METRIC_KIND_HISTOGRAM);
   // TRITONSERVER_MetricFamily
   py::class_<PyMetricFamily>(m, "TRITONSERVER_MetricFamily")
       .def(py::init<
@@ -2149,12 +2157,13 @@ PYBIND11_MODULE(triton_bindings, m)
   py::class_<PyMetric>(m, "TRITONSERVER_Metric")
       .def(
           py::init<
-              PyMetricFamily&,
-              const std::vector<std::shared_ptr<PyParameter>>&>(),
+              PyMetricFamily&, const std::vector<std::shared_ptr<PyParameter>>&,
+              const std::vector<double>*>(),
           py::keep_alive<1, 2>())
       .def_property_readonly("value", &PyMetric::Value)
       .def("increment", &PyMetric::Increment)
       .def("set_value", &PyMetric::SetValue)
+      .def("observe", &PyMetric::Observe)
       .def_property_readonly("kind", &PyMetric::Kind);
 }
 

src/metric_family.cc

@@ -1,4 +1,5 @@
-// Copyright (c) 2022, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// Copyright (c) 2022-2024, NVIDIA CORPORATION & AFFILIATES. All rights
+// reserved.
 //
 // Redistribution and use in source and binary forms, with or without
 // modification, are permitted provided that the following conditions
@@ -54,6 +55,12 @@ MetricFamily::MetricFamily(
                                              .Help(description)
                                              .Register(*registry));
       break;
+    case TRITONSERVER_METRIC_KIND_HISTOGRAM:
+      family_ = reinterpret_cast<void*>(&prometheus::BuildHistogram()
+                                             .Name(name)
+                                             .Help(description)
+                                             .Register(*registry));
+      break;
     default:
       throw std::invalid_argument(
           "Unsupported kind passed to MetricFamily constructor.");
@@ -63,24 +70,45 @@ MetricFamily::MetricFamily(
 }
 
 void*
-MetricFamily::Add(std::map<std::string, std::string> label_map, Metric* metric)
+MetricFamily::Add(
+    std::map<std::string, std::string> label_map, Metric* metric,
+    const std::vector<double>* buckets)
 {
   void* prom_metric = nullptr;
   switch (kind_) {
     case TRITONSERVER_METRIC_KIND_COUNTER: {
+      if (buckets != nullptr) {
+        throw std::invalid_argument(
+            "Unexpected buckets found in counter Metric constructor.");
+      }
       auto counter_family_ptr =
           reinterpret_cast<prometheus::Family<prometheus::Counter>*>(family_);
       auto counter_ptr = &counter_family_ptr->Add(label_map);
       prom_metric = reinterpret_cast<void*>(counter_ptr);
       break;
     }
     case TRITONSERVER_METRIC_KIND_GAUGE: {
+      if (buckets != nullptr) {
+        throw std::invalid_argument(
+            "Unexpected buckets found in gauge Metric constructor.");
+      }
       auto gauge_family_ptr =
           reinterpret_cast<prometheus::Family<prometheus::Gauge>*>(family_);
       auto gauge_ptr = &gauge_family_ptr->Add(label_map);
       prom_metric = reinterpret_cast<void*>(gauge_ptr);
       break;
     }
+    case TRITONSERVER_METRIC_KIND_HISTOGRAM: {
+      if (buckets == nullptr) {
+        throw std::invalid_argument(
+            "Missing required buckets in histogram Metric constructor.");
+      }
+      auto histogram_family_ptr =
+          reinterpret_cast<prometheus::Family<prometheus::Histogram>*>(family_);
+      auto histogram_ptr = &histogram_family_ptr->Add(label_map, *buckets);
+      prom_metric = reinterpret_cast<void*>(histogram_ptr);
+      break;
+    }
     default:
       throw std::invalid_argument(
           "Unsupported family kind passed to Metric constructor.");
@@ -134,6 +162,14 @@ MetricFamily::Remove(void* prom_metric, Metric* metric)
       gauge_family_ptr->Remove(gauge_ptr);
       break;
     }
+    case TRITONSERVER_METRIC_KIND_HISTOGRAM: {
+      auto histogram_family_ptr =
+          reinterpret_cast<prometheus::Family<prometheus::Histogram>*>(family_);
+      auto histogram_ptr =
+          reinterpret_cast<prometheus::Histogram*>(prom_metric);
+      histogram_family_ptr->Remove(histogram_ptr);
+      break;
+    }
     default:
       // Invalid kind should be caught in constructor
       LOG_ERROR << "Unsupported kind in Metric destructor.";
@@ -169,7 +205,8 @@ MetricFamily::~MetricFamily()
 //
 Metric::Metric(
     TRITONSERVER_MetricFamily* family,
-    std::vector<const InferenceParameter*> labels)
+    std::vector<const InferenceParameter*> labels,
+    const std::vector<double>* buckets)
 {
   family_ = reinterpret_cast<MetricFamily*>(family);
   kind_ = family_->Kind();
@@ -188,7 +225,7 @@ Metric::Metric(
         std::string(reinterpret_cast<const char*>(param->ValuePointer()));
   }
 
-  metric_ = family_->Add(label_map, this);
+  metric_ = family_->Add(label_map, this, buckets);
 }
 
 Metric::~Metric()
@@ -235,6 +272,11 @@ Metric::Value(double* value)
       *value = gauge_ptr->Value();
       break;
     }
+    case TRITONSERVER_METRIC_KIND_HISTOGRAM: {
+      return TRITONSERVER_ErrorNew(
+          TRITONSERVER_ERROR_UNSUPPORTED,
+          "TRITONSERVER_METRIC_KIND_HISTOGRAM does not support Value");
+    }
     default:
       return TRITONSERVER_ErrorNew(
           TRITONSERVER_ERROR_UNSUPPORTED,
@@ -279,6 +321,11 @@ Metric::Increment(double value)
       }
       break;
     }
+    case TRITONSERVER_METRIC_KIND_HISTOGRAM: {
+      return TRITONSERVER_ErrorNew(
+          TRITONSERVER_ERROR_UNSUPPORTED,
+          "TRITONSERVER_METRIC_KIND_HISTOGRAM does not support Increment");
+    }
     default:
       return TRITONSERVER_ErrorNew(
           TRITONSERVER_ERROR_UNSUPPORTED,
@@ -308,6 +355,79 @@ Metric::Set(double value)
       gauge_ptr->Set(value);
       break;
     }
+    case TRITONSERVER_METRIC_KIND_HISTOGRAM: {
+      return TRITONSERVER_ErrorNew(
+          TRITONSERVER_ERROR_UNSUPPORTED,
+          "TRITONSERVER_METRIC_KIND_HISTOGRAM does not support Set");
+    }
+    default:
+      return TRITONSERVER_ErrorNew(
+          TRITONSERVER_ERROR_UNSUPPORTED,
+          "Unsupported TRITONSERVER_MetricKind");
+  }
+
+  return nullptr;  // Success
+}
+
+TRITONSERVER_Error*
+Metric::Observe(double value)
+{
+  if (metric_ == nullptr) {
+    return TRITONSERVER_ErrorNew(
+        TRITONSERVER_ERROR_INTERNAL,
+        "Could not set metric value. Metric has been invalidated.");
+  }
+
+  switch (kind_) {
+    case TRITONSERVER_METRIC_KIND_COUNTER: {
+      return TRITONSERVER_ErrorNew(
+          TRITONSERVER_ERROR_UNSUPPORTED,
+          "TRITONSERVER_METRIC_KIND_COUNTER does not support Observe");
+    }
+    case TRITONSERVER_METRIC_KIND_GAUGE: {
+      return TRITONSERVER_ErrorNew(
+          TRITONSERVER_ERROR_UNSUPPORTED,
+          "TRITONSERVER_METRIC_KIND_GAUGE does not support Observe");
+    }
+    case TRITONSERVER_METRIC_KIND_HISTOGRAM: {
+      auto histogram_ptr = reinterpret_cast<prometheus::Histogram*>(metric_);
+      histogram_ptr->Observe(value);
+      break;
+    }
+    default:
+      return TRITONSERVER_ErrorNew(
+          TRITONSERVER_ERROR_UNSUPPORTED,
+          "Unsupported TRITONSERVER_MetricKind");
+  }
+
+  return nullptr;  // Success
+}
+
+TRITONSERVER_Error*
+Metric::Collect(prometheus::ClientMetric* value)
+{
+  if (metric_ == nullptr) {
+    return TRITONSERVER_ErrorNew(
+        TRITONSERVER_ERROR_INTERNAL,
+        "Could not collect metric value. Metric has been invalidated.");
+  }
+
+  switch (kind_) {
+    case TRITONSERVER_METRIC_KIND_COUNTER: {
+      auto counter_ptr = reinterpret_cast<prometheus::Counter*>(metric_);
+      *value = counter_ptr->Collect();
+      break;
+    }
+    case TRITONSERVER_METRIC_KIND_GAUGE: {
+      auto gauge_ptr = reinterpret_cast<prometheus::Gauge*>(metric_);
+      *value = gauge_ptr->Collect();
+      break;
+    }
+    case TRITONSERVER_METRIC_KIND_HISTOGRAM: {
+      auto histogram_ptr = reinterpret_cast<prometheus::Histogram*>(metric_);
+      *value = histogram_ptr->Collect();
+      break;
+    }
     default:
       return TRITONSERVER_ErrorNew(
           TRITONSERVER_ERROR_UNSUPPORTED,

src/metric_family.h

@@ -1,4 +1,5 @@
-// Copyright (c) 2022, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// Copyright (c) 2022-2024, NVIDIA CORPORATION & AFFILIATES. All rights
+// reserved.
 //
 // Redistribution and use in source and binary forms, with or without
 // modification, are permitted provided that the following conditions
@@ -50,7 +51,9 @@ class MetricFamily {
   void* Family() const { return family_; }
   TRITONSERVER_MetricKind Kind() const { return kind_; }
 
-  void* Add(std::map<std::string, std::string> label_map, Metric* metric);
+  void* Add(
+      std::map<std::string, std::string> label_map, Metric* metric,
+      const std::vector<double>* buckets = nullptr);
   void Remove(void* prom_metric, Metric* metric);
 
   int NumMetrics()
@@ -86,7 +89,8 @@ class Metric {
  public:
   Metric(
       TRITONSERVER_MetricFamily* family,
-      std::vector<const InferenceParameter*> labels);
+      std::vector<const InferenceParameter*> labels,
+      const std::vector<double>* buckets = nullptr);
   ~Metric();
 
   MetricFamily* Family() const { return family_; }
@@ -95,6 +99,8 @@ class Metric {
   TRITONSERVER_Error* Value(double* value);
   TRITONSERVER_Error* Increment(double value);
   TRITONSERVER_Error* Set(double value);
+  TRITONSERVER_Error* Observe(double value);
+  TRITONSERVER_Error* Collect(prometheus::ClientMetric* value);
 
   // If a MetricFamily is deleted before its dependent Metric, we want to
   // invalidate the references so we don't access invalid memory.