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_COLLECTOR_H_ 9 : #define ZEPHYR_INCLUDE_PROMETHEUS_COLLECTOR_H_ 10 : 11 : /** 12 : * @file 13 : * 14 : * @brief Prometheus collector APIs. 15 : * 16 : * @defgroup prometheus Prometheus API 17 : * @since 4.0 18 : * @version 0.1.0 19 : * @ingroup networking 20 : * @{ 21 : */ 22 : 23 : #include <zephyr/kernel.h> 24 : #include <zephyr/sys/iterable_sections.h> 25 : #include <zephyr/net/prometheus/metric.h> 26 : 27 : #include <stddef.h> 28 : 29 : struct prometheus_collector; 30 : 31 : /** 32 : * @typedef prometheus_scrape_cb_t 33 : * @brief Callback used to scrape a collector for a specific metric. 34 : * 35 : * @param collector A valid pointer on the collector to scrape 36 : * @param metric A valid pointer on the metric to scrape 37 : * @param user_data A valid pointer to a user data or NULL 38 : * 39 : * @return 0 if successful, otherwise a negative error code. 40 : */ 41 1 : typedef int (*prometheus_scrape_cb_t)(struct prometheus_collector *collector, 42 : struct prometheus_metric *metric, 43 : void *user_data); 44 : 45 : /** 46 : * @brief Prometheus collector definition 47 : * 48 : * This structure defines a Prometheus collector. 49 : */ 50 1 : struct prometheus_collector { 51 : /** Name of the collector */ 52 1 : const char *name; 53 : /** Array of metrics associated with the collector */ 54 1 : sys_slist_t metrics; 55 : /** Mutex to protect the metrics list manipulation */ 56 1 : struct k_mutex lock; 57 : /** User callback function. If set, then the metric data is fetched 58 : * via the function callback. 59 : */ 60 1 : prometheus_scrape_cb_t user_cb; 61 : /** User data */ 62 1 : void *user_data; 63 : }; 64 : 65 : /** 66 : * @brief Prometheus Collector definition. 67 : * 68 : * This macro defines a Collector. 69 : * 70 : * @param _name The collector's name. 71 : * @param ... Optional user callback function. If set, this function is called 72 : * when the collector is scraped. The function should be of type 73 : * prometheus_scrape_cb_t. 74 : * Optional user data to pass to the user callback function. 75 : */ 76 1 : #define PROMETHEUS_COLLECTOR_DEFINE(_name, ...) \ 77 : STRUCT_SECTION_ITERABLE(prometheus_collector, _name) = { \ 78 : .name = STRINGIFY(_name), \ 79 : .metrics = SYS_SLIST_STATIC_INIT(&_name.metrics), \ 80 : .lock = Z_MUTEX_INITIALIZER(_name.lock), \ 81 : .user_cb = COND_CODE_0( \ 82 : NUM_VA_ARGS_LESS_1( \ 83 : LIST_DROP_EMPTY(__VA_ARGS__, _)), \ 84 : (NULL), \ 85 : (GET_ARG_N(1, __VA_ARGS__))), \ 86 : .user_data = COND_CODE_0( \ 87 : NUM_VA_ARGS_LESS_1(__VA_ARGS__), (NULL), \ 88 : (GET_ARG_N(1, \ 89 : GET_ARGS_LESS_N(1, __VA_ARGS__)))), \ 90 : } 91 : 92 : /** 93 : * @brief Register a metric with a Prometheus collector 94 : * 95 : * Registers the specified metric with the given collector. 96 : * 97 : * @param collector Pointer to the collector to register the metric with. 98 : * @param metric Pointer to the metric to register. 99 : * 100 : * @return 0 if successful, otherwise a negative error code. 101 : * @retval -EINVAL Invalid arguments. 102 : * @retval -ENOMEM Not enough memory to register the metric. 103 : */ 104 1 : int prometheus_collector_register_metric(struct prometheus_collector *collector, 105 : struct prometheus_metric *metric); 106 : 107 : /** 108 : * @brief Get a metric from a Prometheus collector 109 : * 110 : * Retrieves the metric with the specified name from the given collector. 111 : * 112 : * @param collector Pointer to the collector to retrieve the metric from. 113 : * @param name Name of the metric to retrieve. 114 : * @return Pointer to the retrieved metric, or NULL if not found. 115 : */ 116 1 : const void *prometheus_collector_get_metric(struct prometheus_collector *collector, 117 : const char *name); 118 : 119 : /** @cond INTERNAL_HIDDEN */ 120 : 121 : enum prometheus_walk_state { 122 : PROMETHEUS_WALK_START, 123 : PROMETHEUS_WALK_CONTINUE, 124 : PROMETHEUS_WALK_STOP, 125 : }; 126 : 127 : struct prometheus_collector_walk_context { 128 : struct prometheus_collector *collector; 129 : struct prometheus_metric *metric; 130 : struct prometheus_metric *tmp; 131 : enum prometheus_walk_state state; 132 : }; 133 : 134 : /** @endcond */ 135 : 136 : /** 137 : * @brief Walk through all metrics in a Prometheus collector and format them 138 : * into a buffer. 139 : * 140 : * @param ctx Pointer to the walker context. 141 : * @param buffer Pointer to the buffer to store the formatted metrics. 142 : * @param buffer_size Size of the buffer. 143 : * @return 0 if successful and we went through all metrics, -EAGAIN if we 144 : * need to call this function again, any other negative error code 145 : * means an error occurred. 146 : */ 147 1 : int prometheus_collector_walk_metrics(struct prometheus_collector_walk_context *ctx, 148 : uint8_t *buffer, size_t buffer_size); 149 : 150 : /** 151 : * @brief Initialize the walker context to walk through all metrics. 152 : * 153 : * @param ctx Pointer to the walker context. 154 : * @param collector Pointer to the collector to walk through. 155 : * 156 : * @return 0 if successful, otherwise a negative error code. 157 : */ 158 1 : static inline int prometheus_collector_walk_init(struct prometheus_collector_walk_context *ctx, 159 : struct prometheus_collector *collector) 160 : { 161 : if (collector == NULL) { 162 : return -EINVAL; 163 : } 164 : 165 : ctx->collector = collector; 166 : ctx->state = PROMETHEUS_WALK_START; 167 : ctx->metric = NULL; 168 : ctx->tmp = NULL; 169 : 170 : return 0; 171 : } 172 : 173 : /** 174 : * @} 175 : */ 176 : 177 : #endif /* ZEPHYR_INCLUDE_PROMETHEUS_COLLECTOR_H_ */
