Line data    Source code

       1           1 : /*
       2             :  * Copyright (c) 2024 Mustafa Abdullah Kus, Sparse Technology
       3             :  * Copyright (c) 2024 Nordic Semiconductor
       4             :  *
       5             :  * SPDX-License-Identifier: Apache-2.0
       6             :  */
       7             : 
       8             : #ifndef ZEPHYR_INCLUDE_PROMETHEUS_HISTOGRAM_H_
       9             : #define ZEPHYR_INCLUDE_PROMETHEUS_HISTOGRAM_H_
      10             : 
      11             : /**
      12             :  * @file
      13             :  *
      14             :  * @brief Prometheus histogram APIs.
      15             :  *
      16             :  * @addtogroup prometheus
      17             :  * @{
      18             :  */
      19             : 
      20             : #include <zephyr/sys/iterable_sections.h>
      21             : #include <zephyr/net/prometheus/metric.h>
      22             : 
      23             : #include <stddef.h>
      24             : 
      25             : /**
      26             :  * @brief Prometheus histogram bucket definition.
      27             :  *
      28             :  * This structure defines a Prometheus histogram bucket.
      29             :  */
      30           1 : struct prometheus_histogram_bucket {
      31             :         /** Upper bound value of bucket */
      32           1 :         double upper_bound;
      33             :         /** Cumulative count of observations in the bucket */
      34           1 :         unsigned long count;
      35             : };
      36             : 
      37             : /**
      38             :  * @brief Type used to represent a Prometheus histogram metric.
      39             :  *
      40             :  * * References
      41             :  * * See https://prometheus.io/docs/concepts/metric_types/#histogram
      42             :  */
      43           1 : struct prometheus_histogram {
      44             :         /** Base of the Prometheus histogram metric */
      45           1 :         struct prometheus_metric base;
      46             :         /** Array of buckets in the histogram */
      47           1 :         struct prometheus_histogram_bucket *buckets;
      48             :         /** Number of buckets in the histogram */
      49           1 :         size_t num_buckets;
      50             :         /** Sum of all observed values in the histogram */
      51           1 :         double sum;
      52             :         /** Total count of observations in the histogram */
      53           1 :         unsigned long count;
      54             :         /** User data */
      55           1 :         void *user_data;
      56             : };
      57             : 
      58             : /**
      59             :  * @brief Prometheus Histogram definition.
      60             :  *
      61             :  * This macro defines a Histogram metric. If you want to make the histogram static,
      62             :  * then add "static" keyword before the PROMETHEUS_HISTOGRAM_DEFINE.
      63             :  *
      64             :  * @param _name The histogram metric name.
      65             :  * @param _desc Histogram description
      66             :  * @param _label Label for the metric. Additional labels can be added at runtime.
      67             :  * @param _collector Collector to map this metric. Can be set to NULL if it not yet known.
      68             :  * @param ... Optional user data specific to this metric instance.
      69             :  *
      70             :  * Example usage:
      71             :  * @code{.c}
      72             :  *
      73             :  * PROMETHEUS_HISTOGRAM_DEFINE(http_request_histogram, "HTTP request histogram",
      74             :  *                         ({ .key = "request_latency", .value = "request_latency_seconds" }),
      75             :  *                         NULL);
      76             :  *
      77             :  * @endcode
      78             :  */
      79           1 : #define PROMETHEUS_HISTOGRAM_DEFINE(_name, _desc, _label, _collector, ...) \
      80             :         STRUCT_SECTION_ITERABLE(prometheus_histogram, _name) = {        \
      81             :                 .base.name = STRINGIFY(_name),                          \
      82             :                 .base.type = PROMETHEUS_HISTOGRAM,                      \
      83             :                 .base.description = _desc,                              \
      84             :                 .base.labels[0] = __DEBRACKET _label,                   \
      85             :                 .base.num_labels = 1,                                   \
      86             :                 .base.collector = _collector,                           \
      87             :                 .buckets = NULL,                                        \
      88             :                 .num_buckets = 0,                                       \
      89             :                 .sum = 0.0,                                             \
      90             :                 .count = 0U,                                            \
      91             :                 .user_data = COND_CODE_0(                               \
      92             :                         NUM_VA_ARGS_LESS_1(LIST_DROP_EMPTY(__VA_ARGS__, _)), \
      93             :                         (NULL),                                         \
      94             :                         (GET_ARG_N(1, __VA_ARGS__))),                   \
      95             :         }
      96             : 
      97             : /**
      98             :  * @brief Observe a value in a Prometheus histogram metric
      99             :  *
     100             :  * Observes the specified value in the given histogram metric.
     101             :  *
     102             :  * @param histogram Pointer to the histogram metric to observe.
     103             :  * @param value Value to observe in the histogram metric.
     104             :  * @return 0 on success, -EINVAL if the value is negative.
     105             :  */
     106           1 : int prometheus_histogram_observe(struct prometheus_histogram *histogram, double value);
     107             : 
     108             : /**
     109             :  * @}
     110             :  */
     111             : 
     112             : #endif /* ZEPHYR_INCLUDE_PROMETHEUS_HISTOGRAM_H_ */