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_GAUGE_H_
       9             : #define ZEPHYR_INCLUDE_PROMETHEUS_GAUGE_H_
      10             : 
      11             : /**
      12             :  * @file
      13             :  *
      14             :  * @brief Prometheus gauge APIs.
      15             :  *
      16             :  * @addtogroup prometheus
      17             :  * @{
      18             :  */
      19             : 
      20             : #include <zephyr/sys/iterable_sections.h>
      21             : #include <zephyr/net/prometheus/metric.h>
      22             : 
      23             : /**
      24             :  * @brief Type used to represent a Prometheus gauge metric.
      25             :  *
      26             :  * * References
      27             :  * * See https://prometheus.io/docs/concepts/metric_types/#gauge
      28             :  */
      29           1 : struct prometheus_gauge {
      30             :         /** Base of the Prometheus gauge metric */
      31           1 :         struct prometheus_metric base;
      32             :         /** Value of the Prometheus gauge metric */
      33           1 :         double value;
      34             :         /** User data */
      35           1 :         void *user_data;
      36             : };
      37             : 
      38             : /**
      39             :  * @brief Prometheus Gauge definition.
      40             :  *
      41             :  * This macro defines a Gauge metric. If you want to make the gauge static,
      42             :  * then add "static" keyword before the PROMETHEUS_GAUGE_DEFINE.
      43             :  *
      44             :  * @param _name The gauge metric name.
      45             :  * @param _desc Gauge description
      46             :  * @param _label Label for the metric. Additional labels can be added at runtime.
      47             :  * @param _collector Collector to map this metric. Can be set to NULL if it not yet known.
      48             :  * @param ... Optional user data specific to this metric instance.
      49             :  *
      50             :  * Example usage:
      51             :  * @code{.c}
      52             :  *
      53             :  * PROMETHEUS_GAUGE_DEFINE(http_request_gauge, "HTTP request gauge",
      54             :  *                         ({ .key = "http_request", .value = "request_count" }),
      55             :  *                         NULL);
      56             :  *
      57             :  * @endcode
      58             :  */
      59           1 : #define PROMETHEUS_GAUGE_DEFINE(_name, _desc, _label, _collector, ...)  \
      60             :         STRUCT_SECTION_ITERABLE(prometheus_gauge, _name) = {            \
      61             :                 .base.name = STRINGIFY(_name),                          \
      62             :                 .base.type = PROMETHEUS_GAUGE,                          \
      63             :                 .base.description = _desc,                              \
      64             :                 .base.labels[0] = __DEBRACKET _label,                   \
      65             :                 .base.num_labels = 1,                                   \
      66             :                 .base.collector = _collector,                           \
      67             :                 .value = 0.0,                                           \
      68             :                 .user_data = COND_CODE_0(                               \
      69             :                         NUM_VA_ARGS_LESS_1(LIST_DROP_EMPTY(__VA_ARGS__, _)), \
      70             :                         (NULL),                                         \
      71             :                         (GET_ARG_N(1, __VA_ARGS__))),                   \
      72             :         }
      73             : 
      74             : /**
      75             :  * @brief Set the value of a Prometheus gauge metric
      76             :  *
      77             :  * Sets the value of the specified gauge metric to the given value.
      78             :  *
      79             :  * @param gauge Pointer to the gauge metric to set.
      80             :  * @param value Value to set the gauge metric to.
      81             :  *
      82             :  * @return 0 on success, -EINVAL if the value is negative.
      83             :  */
      84           1 : int prometheus_gauge_set(struct prometheus_gauge *gauge, double value);
      85             : 
      86             : /**
      87             :  * @}
      88             :  */
      89             : 
      90             : #endif /* ZEPHYR_INCLUDE_PROMETHEUS_GAUGE_H_ */