-
Notifications
You must be signed in to change notification settings - Fork 73
/
prom_gauge.h
155 lines (139 loc) · 6.12 KB
/
prom_gauge.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
/*
Copyright 2019-2020 DigitalOcean Inc.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/
/**
* @file prom_gauge.h
* @brief https://prometheus.io/docs/concepts/metric_types/#gauge
*/
#ifndef PROM_GAUGE_H
#define PROM_GAUGE_H
#include <stdlib.h>
#include "prom_metric.h"
/**
* @brief A prometheus gauge.
*
* References
* * See https://prometheus.io/docs/concepts/metric_types/#gauge
*/
typedef prom_metric_t prom_gauge_t;
/**
* @brief Constructs a prom_gauge_t*
* @param name The name of the metric
* @param help The metric description
* @param label_key_count The number of labels associated with the given metric. Pass 0 if the metric does not
* require labels.
* @param label_keys A collection of label keys. The number of keys MUST match the value passed as label_key_count. If
* no labels are required, pass NULL. Otherwise, it may be convenient to pass this value as a
* literal.
* @return The constructed prom_guage_t*
*
* // An example with labels
* prom_gauge_new("foo", "foo is a gauge with labels", 2, (const char**) { "one", "two" });
*
* // An example without labels
* prom_gauge_new("foo", "foo is a gauge without labels", 0, NULL);
*/
prom_gauge_t *prom_gauge_new(const char *name, const char *help, size_t label_key_count, const char **label_keys);
/**
* @brief Destroys a prom_gauge_t*. You must set self to NULL after destruction. A non-zero integer value will be
* returned on failure.
* @param self The target prom_gauge_t*
* @return A non-zero integer value upon failure
*/
int prom_gauge_destroy(prom_gauge_t *self);
/**
* @brief Increment the prom_gauge_t* by 1.
* @param self The target prom_gauger_t*
* @param label_values The label values associated with the metric sample being updated. The number of labels must
* match the value passed to label_key_count in the gauge's constructor. If no label values are
* necessary, pass NULL. Otherwise, It may be convenient to pass this value as a literal.
* @return A non-zero integer value upon failure
* *Example*
*
* // An example with labels
* prom_gauge_inc(foo_gauge, (const char**) { "bar", "bang" });
*
* // An example without labels
* prom_gauge_inc(foo_gauge, NULL);
*/
int prom_gauge_inc(prom_gauge_t *self, const char **label_values);
/**
* @brief Decrement the prom_gauge_t* by 1.
* @param self The target prom_gauger_t*
* @param label_values The label values associated with the metric sample being updated. The number of labels must
* match the value passed to label_key_count in the gauge's constructor. If no label values are
* necessary, pass NULL. Otherwise, It may be convenient to pass this value as a literal.
* @return A non-zero integer value upon failure.
* *Example*
*
* // An example with labels
* prom_gauge_dec(foo_gauge, (const char**) { "bar", "bang" });
*
* // An example without labels
* prom_gauge_dec(foo_gauge, NULL);
*/
int prom_gauge_dec(prom_gauge_t *self, const char **label_values);
/**
* @brief Add the value to the prom_gauge_t*.
* @param self The target prom_gauge_t*
* @param r_value The double to add to the prom_gauge_t passed as self.
* @param label_values The label values associated with the metric sample being updated. The number of labels must
* match the value passed to label_key_count in the gauge's constructor. If no label values are
* necessary, pass NULL. Otherwise, It may be convenient to pass this value as a literal.
* @return A non-zero integer value upon failure.
*
* *Example*
*
* // An example with labels
* prom_gauge_add(foo_gauge 22, (const char**) { "bar", "bang" });
*
* // An example without labels
* prom_gauge_add(foo_gauge, 22, NULL);
*/
int prom_gauge_add(prom_gauge_t *self, double r_value, const char **label_values);
/**
* @brief Subtract the value to the prom_gauge. A non-zero integer value will be returned on failure.
* @param self The target prom_gauge_t*
* @param r_value The double to add to the prom_gauge_t passed as self.
* @param label_values The label values associated with the metric sample being updated. The number of labels must
* match the value passed to label_key_count in the gauge's constructor. If no label values are
* necessary, pass NULL. Otherwise, It may be convenient to pass this value as a literal.
* @return A non-zero integer value upon failure.
*
* *Example*
*
* // An example with labels
* prom_gauge_sub(foo_gauge 22, (const char**) { "bar", "bang" });
*
* // An example without labels
* prom_gauge_sub(foo_gauge, 22, NULL);
*/
int prom_gauge_sub(prom_gauge_t *self, double r_value, const char **label_values);
/**
* @brief Set the value for the prom_gauge_t*
* @param self The target prom_gauge_t*
* @param r_value The double to which the prom_gauge_t* passed as self will be set
* @param label_values The label values associated with the metric sample being updated. The number of labels must
* match the value passed to label_key_count in the gauge's constructor. If no label values are
* necessary, pass NULL. Otherwise, It may be convenient to pass this value as a literal.
* @return A non-zero integer value upon failure.
*
* *Example*
*
* // An example with labels
* prom_gauge_set(foo_gauge 22, (const char**) { "bar", "bang" });
*
* // An example without labels
* prom_gauge_set(foo_gauge, 22, NULL);
*/
int prom_gauge_set(prom_gauge_t *self, double r_value, const char **label_values);
#endif // PROM_GAUGE_H