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_HISTOGRAM_H_ 8 : #define ZEPHYR_INCLUDE_PROMETHEUS_HISTOGRAM_H_ 9 : 10 : /** 11 : * @file 12 : * 13 : * @brief Prometheus histogram 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 histogram bucket definition. 26 : * 27 : * This structure defines a Prometheus histogram bucket. 28 : */ 29 1 : struct prometheus_histogram_bucket { 30 : /** Upper bound value of bucket */ 31 1 : double upper_bound; 32 : /** Cumulative count of observations in the bucket */ 33 1 : unsigned long count; 34 : }; 35 : 36 : /** 37 : * @brief Type used to represent a Prometheus histogram metric. 38 : * 39 : * * References 40 : * * See https://prometheus.io/docs/concepts/metric_types/#histogram 41 : */ 42 1 : struct prometheus_histogram { 43 : /** Base of the Prometheus histogram metric */ 44 1 : struct prometheus_metric *base; 45 : /** Array of buckets in the histogram */ 46 1 : struct prometheus_histogram_bucket *buckets; 47 : /** Number of buckets in the histogram */ 48 1 : size_t num_buckets; 49 : /** Sum of all observed values in the histogram */ 50 1 : double sum; 51 : /** Total count of observations in the histogram */ 52 1 : unsigned long count; 53 : }; 54 : 55 : /** 56 : * @brief Prometheus Histogram definition. 57 : * 58 : * This macro defines a Histogram 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_HISTOGRAM, 68 : * .name = "http_request_histograms", 69 : * .description = "HTTP request histogram", 70 : * .num_labels = 1, 71 : * .labels = { 72 : * { .key = "request_latency", .value = "request_latency_seconds",} 73 : * }, 74 : * }; 75 : * 76 : * PROMETHEUS_HISTOGRAM_DEFINE(test_histogram, &test_histogram_metric); 77 : * 78 : * @endcode 79 : */ 80 1 : #define PROMETHEUS_HISTOGRAM_DEFINE(_name, _detail) \ 81 : static STRUCT_SECTION_ITERABLE(prometheus_histogram, _name) = {.base = (void *)(_detail), \ 82 : .buckets = NULL, \ 83 : .num_buckets = 0, \ 84 : .sum = 0, \ 85 : .count = 0} 86 : 87 : /** 88 : * @brief Observe a value in a Prometheus histogram metric 89 : * 90 : * Observes the specified value in the given histogram metric. 91 : * 92 : * @param histogram Pointer to the histogram metric to observe. 93 : * @param value Value to observe in the histogram metric. 94 : * @return 0 on success, -EINVAL if the value is negative. 95 : */ 96 1 : int prometheus_histogram_observe(struct prometheus_histogram *histogram, double value); 97 : 98 : /** 99 : * @} 100 : */ 101 : 102 : #endif /* ZEPHYR_INCLUDE_PROMETHEUS_HISTOGRAM_H_ */