Line data    Source code

       1           1 : /*
       2             :  * Copyright (c) 2024 Mustafa Abdullah Kus, Sparse Technology
       3             :  *
       4             :  * SPDX-License-Identifier: Apache-2.0
       5             :  */
       6             : 
       7             : #ifndef ZEPHYR_INCLUDE_PROMETHEUS_SUMMARY_H_
       8             : #define ZEPHYR_INCLUDE_PROMETHEUS_SUMMARY_H_
       9             : 
      10             : /**
      11             :  * @file
      12             :  *
      13             :  * @brief Prometheus summary APIs.
      14             :  *
      15             :  * @addtogroup prometheus
      16             :  * @{
      17             :  */
      18             : 
      19             : #include <zephyr/sys/iterable_sections.h>
      20             : #include <zephyr/net/prometheus/metric.h>
      21             : 
      22             : #include <stddef.h>
      23             : 
      24             : /**
      25             :  * @brief Prometheus summary quantile definition.
      26             :  *
      27             :  * This structure defines a Prometheus summary quantile.
      28             :  */
      29           1 : struct prometheus_summary_quantile {
      30             :         /** Quantile of the summary */
      31           1 :         double quantile;
      32             :         /** Value of the quantile */
      33           1 :         double value;
      34             : };
      35             : 
      36             : /**
      37             :  * @brief Type used to represent a Prometheus summary metric.
      38             :  *
      39             :  * * References
      40             :  * * See https://prometheus.io/docs/concepts/metric_types/#summary
      41             :  */
      42           1 : struct prometheus_summary {
      43             :         /** Base of the Prometheus summary metric */
      44           1 :         struct prometheus_metric *base;
      45             :         /** Array of quantiles associated with the Prometheus summary metric */
      46           1 :         struct prometheus_summary_quantile *quantiles;
      47             :         /** Number of quantiles associated with the Prometheus summary metric */
      48           1 :         size_t num_quantiles;
      49             :         /** Sum of all observed values in the summary metric */
      50           1 :         double sum;
      51             :         /** Total count of observations in the summary metric */
      52           1 :         unsigned long count;
      53             : };
      54             : 
      55             : /**
      56             :  * @brief Prometheus Summary definition.
      57             :  *
      58             :  * This macro defines a Summary metric.
      59             :  *
      60             :  * @param _name The channel's name.
      61             :  * @param _detail The metric base.
      62             :  *
      63             :  * Example usage:
      64             :  * @code{.c}
      65             :  *
      66             :  * struct prometheus_metric http_request_gauge = {
      67             :  *      .type = PROMETHEUS_SUMMARY,
      68             :  *      .name = "http_request_summary",
      69             :  *      .description = "HTTP request summary",
      70             :  *      .num_labels = 1,
      71             :  *      .labels = {
      72             :  *              { .key = "request_latency", .value = "request_latency_seconds",}
      73             :  *      },
      74             :  * };
      75             :  *
      76             :  * PROMETHEUS_SUMMARY_DEFINE(test_summary, &test_summary_metric);
      77             :  *
      78             :  * @endcode
      79             :  */
      80             : 
      81           1 : #define PROMETHEUS_SUMMARY_DEFINE(_name, _detail)                                                  \
      82             :         static STRUCT_SECTION_ITERABLE(prometheus_summary, _name) = {.base = (void *)(_detail),    \
      83             :                                                                      .quantiles = NULL,            \
      84             :                                                                      .num_quantiles = 0,           \
      85             :                                                                      .sum = 0,                     \
      86             :                                                                      .count = 0}
      87             : 
      88             : /**
      89             :  * @brief Observes a value in a Prometheus summary metric
      90             :  *
      91             :  * Observes the specified value in the given summary metric.
      92             :  *
      93             :  * @param summary Pointer to the summary metric to observe.
      94             :  * @param value Value to observe in the summary metric.
      95             :  * @return 0 on success, -EINVAL if the value is negative.
      96             :  */
      97           1 : int prometheus_summary_observe(struct prometheus_summary *summary, double value);
      98             : 
      99             : /**
     100             :  * @}
     101             :  */
     102             : 
     103             : #endif /* ZEPHYR_INCLUDE_PROMETHEUS_SUMMARY_H_ */