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_SUMMARY_H_
       9              : #define ZEPHYR_INCLUDE_PROMETHEUS_SUMMARY_H_
      10              : 
      11              : /**
      12              :  * @file
      13              :  *
      14              :  * @brief Prometheus summary 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 summary quantile definition.
      27              :  *
      28              :  * This structure defines a Prometheus summary quantile.
      29              :  */
      30            1 : struct prometheus_summary_quantile {
      31              :         /** Quantile of the summary */
      32            1 :         double quantile;
      33              :         /** Value of the quantile */
      34            1 :         double value;
      35              :         /** User data */
      36            1 :         void *user_data;
      37              : };
      38              : 
      39              : /**
      40              :  * @brief Type used to represent a Prometheus summary metric.
      41              :  *
      42              :  * * References
      43              :  * * See https://prometheus.io/docs/concepts/metric_types/#summary
      44              :  */
      45            1 : struct prometheus_summary {
      46              :         /** Base of the Prometheus summary metric */
      47            1 :         struct prometheus_metric base;
      48              :         /** Array of quantiles associated with the Prometheus summary metric */
      49            1 :         struct prometheus_summary_quantile *quantiles;
      50              :         /** Number of quantiles associated with the Prometheus summary metric */
      51            1 :         size_t num_quantiles;
      52              :         /** Sum of all observed values in the summary metric */
      53            1 :         double sum;
      54              :         /** Total count of observations in the summary metric */
      55            1 :         unsigned long count;
      56              :         /** User data */
      57            1 :         void *user_data;
      58              : };
      59              : 
      60              : /**
      61              :  * @brief Prometheus Summary definition.
      62              :  *
      63              :  * This macro defines a Summary metric. If you want to make the summary static,
      64              :  * then add "static" keyword before the PROMETHEUS_SUMMARY_DEFINE.
      65              :  *
      66              :  * @param _name The summary metric name.
      67              :  * @param _desc Summary description
      68              :  * @param _label Label for the metric. Additional labels can be added at runtime.
      69              :  * @param _collector Collector to map this metric. Can be set to NULL if it not yet known.
      70              :  * @param ... Optional user data specific to this metric instance.
      71              :  *
      72              :  *
      73              :  * Example usage:
      74              :  * @code{.c}
      75              :  *
      76              :  * PROMETHEUS_SUMMARY_DEFINE(http_request_summary, "HTTP request summary",
      77              :  *                           ({ .key = "request_latency",
      78              :  *                              .value = "request_latency_seconds" }), NULL);
      79              :  *
      80              :  * @endcode
      81              :  */
      82              : 
      83            1 : #define PROMETHEUS_SUMMARY_DEFINE(_name, _desc, _label, _collector, ...) \
      84              :         STRUCT_SECTION_ITERABLE(prometheus_summary, _name) = {          \
      85              :                 .base.name = STRINGIFY(_name),                          \
      86              :                 .base.type = PROMETHEUS_SUMMARY,                        \
      87              :                 .base.description = _desc,                              \
      88              :                 .base.labels[0] = __DEBRACKET _label,                   \
      89              :                 .base.num_labels = 1,                                   \
      90              :                 .base.collector = _collector,                           \
      91              :                 .quantiles = NULL,                                      \
      92              :                 .num_quantiles = 0,                                     \
      93              :                 .sum = 0.0,                                             \
      94              :                 .count = 0U,                                            \
      95              :                 .user_data = COND_CODE_0(                               \
      96              :                         NUM_VA_ARGS_LESS_1(LIST_DROP_EMPTY(__VA_ARGS__, _)), \
      97              :                         (NULL),                                         \
      98              :                         (GET_ARG_N(1, __VA_ARGS__))),                   \
      99              :         }
     100              : 
     101              : /**
     102              :  * @brief Observes a value in a Prometheus summary metric
     103              :  *
     104              :  * Observes the specified value in the given summary metric.
     105              :  *
     106              :  * @param summary Pointer to the summary metric to observe.
     107              :  * @param value Value to observe in the summary metric.
     108              :  * @return 0 on success, -EINVAL if the value is negative.
     109              :  */
     110            1 : int prometheus_summary_observe(struct prometheus_summary *summary, double value);
     111              : 
     112              : /**
     113              :  * @brief Set the summary value to specific value.
     114              :  * The new value must be higher than the current value. This function can be used
     115              :  * if we cannot add individual increments to the summary but need to periodically
     116              :  * update the counter value. This function will add the difference between the
     117              :  * new value and the old value to the summary fields.
     118              :  * @param summary Pointer to the summary metric to increment.
     119              :  * @param value New value of the summary.
     120              :  * @param count New counter value of the summary.
     121              :  * @return 0 on success, negative errno on error.
     122              :  */
     123            1 : int prometheus_summary_observe_set(struct prometheus_summary *summary,
     124              :                                    double value, unsigned long count);
     125              : 
     126              : /**
     127              :  * @}
     128              :  */
     129              : 
     130              : #endif /* ZEPHYR_INCLUDE_PROMETHEUS_SUMMARY_H_ */