include/otel_metric.h

filter: Statementstmt 97.3% 109 / 112 Branchbran 72.2% 52 / 72 Conditioncond n/a MC/DCmcdc n/a Subroutinesub n/a Podpod n/a totaltotal 87.5% 161 / 184 CC 0 SCAR 0
CC
0
Cov
0%
CRAP 0
« include/otel_signal_pb.h ↑ Summary include/otel_config.h »
1 /* otel_metric.h - the metrics data model.
2 *
3 * THE THING THAT MAKES METRICS DIFFERENT FROM TRACES: state.
4 *
5 * A span is created, ended and forgotten. A metric point is accumulated
6 * across every export interval for the life of the process, per attribute
7 * set, and both of those words are where the trouble is.
8 *
9 * PER ATTRIBUTE SET means the number of accumulators is the number of
10 * distinct attribute combinations the application produces, which is a number
11 * the application does not know and an attacker may choose. So there is a
12 * CARDINALITY CAP, and past it everything folds into one overflow series
13 * marked otel.metric.overflow. Without a cap, one unbounded attribute - a URL
14 * path, a user id, a client-supplied header - turns a web server into an
15 * out-of-memory incident, and the attribute most likely to do it is exactly
16 * the one somebody added to "make the dashboard more useful".
17 *
18 * FOR THE LIFE OF THE PROCESS means a cumulative series is identified by its
19 * resource plus its attributes, and its start timestamp must stay FIXED. If
20 * that identity is not unique per process, a collector receives several
21 * contradictory monotonic series claiming to be one, and resolves it by
22 * resetting, summing, or taking the last write - all three wrong, none of
23 * them wrong-looking on a dashboard. That is why service.instance.id must
24 * differ per worker, and why this file refuses to be shared across a fork.
25 */
26  
27 #ifndef OTEL_METRIC_H
28 #define OTEL_METRIC_H
29  
30 #include "otel_clock.h"
31 #include "otel_expo.h"
32 #include "otel_value.h"
33  
34 /* instrument kinds */
35 #define OTEL_INSTR_COUNTER 1
36 #define OTEL_INSTR_UPDOWNCOUNTER 2
37 #define OTEL_INSTR_HISTOGRAM 3
38 #define OTEL_INSTR_GAUGE 4
39  
40 /* aggregations */
41 #define OTEL_AGG_DROP 0
42 #define OTEL_AGG_SUM 1
43 #define OTEL_AGG_LASTVALUE 2
44 #define OTEL_AGG_HISTOGRAM 3 /* explicit buckets */
45 #define OTEL_AGG_EXPO 4 /* base-2 exponential */
46  
47 /* temporality */
48 #define OTEL_TEMP_CUMULATIVE 1
49 #define OTEL_TEMP_DELTA 2
50  
51 #define OTEL_CARDINALITY_MAX 2000
52 #define OTEL_MAX_BOUNDS 64
53  
54 /* The conventions' default bucket boundaries for a duration in SECONDS. Not
55 * a round-number guess: they are dense where web latencies actually live. */
56 #define OTEL_DEFAULT_BOUNDS_N 14
57 static const double OTEL_DEFAULT_BOUNDS[OTEL_DEFAULT_BOUNDS_N] = {
58 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5,
59 0.75, 1.0, 2.5, 5.0, 7.5, 10.0
60 };
61  
62 /* One exemplar: a raw measurement stapled to a point, carrying the trace it
63 * came from. What turns "the p99 is bad" into "here is a trace of one". */
64 typedef struct {
65 double value;
66 U64TYPE time;
67 unsigned char trace_id[16];
68 unsigned char span_id[8];
69 int has_span;
70 } otel_exemplar;
71  
72 #define OTEL_EXEMPLAR_MAX 4
73  
74 typedef struct otel_point {
75 SV *key; /* the serialised attribute set: identity */
76 HV *attrs; /* +1 owned */
77 U64TYPE start_nanos; /* FIXED for a cumulative series */
78 U64TYPE time_nanos;
79  
80 double sum; /* Sum / Histogram */
81 double last; /* LastValue */
82 IV count;
83 double min, max;
84 IV buckets[OTEL_MAX_BOUNDS + 1];
85 otel_expo expo;
86  
87 otel_exemplar ex[OTEL_EXEMPLAR_MAX];
88 int n_ex, ex_seen; /* seen: for reservoir sampling */
89  
90 struct otel_point *next;
91 } otel_point;
92  
93 typedef struct otel_instrument {
94 SV *name, *description, *unit;
95 int kind, aggregation, temporality;
96 double bounds[OTEL_MAX_BOUNDS];
97 int nbounds;
98 otel_point *points;
99 int npoints;
100 IV overflow; /* attribute sets past the cardinality cap */
101 struct otel_instrument *next;
102 } otel_instrument;
103  
104 /* ---- attribute-set identity --------------------------------------------- *
105 * The key is the sorted key=value pairs, joined. Sorted because two hashes
106 * with the same pairs in different orders are the SAME series, and Perl's
107 * hash order is randomised - so an unsorted key would split one series into
108 * many, per process, at random. */
109 5385 static SV *otel_attrs_key(pTHX_ HV *attrs) {
110 5385 SV *out = newSVpvs("");
111 AV *keys;
112 SSize_t i, n;
113 5385 ▶ if (!attrs || !HvUSEDKEYS(attrs)) return out;
Branch: 3 branches
BranchTrueFalseTotal
if (!attrs || !HvUSEDKEYS(attrs)) return out; 5385 0 5385
if (!attrs || !HvUSEDKEYS(attrs)) return out; 0 5385 5385
if (!attrs || !HvUSEDKEYS(attrs)) return out; 170 5215 5385
114 5215 keys = otel_attr_keys(aTHX_ attrs); /* sorted; shared with the encoder */
115 5215 n = av_len(keys) + 1;
116 10443 ▶ for (i = 0; i < n; i++) {
Branch: 1 branch
BranchTrueFalseTotal
for (i = 0; i < n; i++) { 5228 5215 10443
117 5228 SV **kp = av_fetch(keys, i, 0);
118 HE *e;
119 5228 ▶ if (!(kp && *kp)) continue;
Branch: 2 branches
BranchTrueFalseTotal
if (!(kp && *kp)) continue; 5228 0 5228
if (!(kp && *kp)) continue; 0 5228 5228
120 5228 ▶ if (SvCUR(out)) sv_catpvs(out, "\x1f"); /* a separator no key holds */
Branch: 1 branch
BranchTrueFalseTotal
if (SvCUR(out)) sv_catpvs(out, "\x1f"); /* a separator no key holds */ 13 5215 5228
121 5228 sv_catsv(out, *kp);
122 5228 sv_catpvs(out, "\x1e");
123 5228 e = hv_fetch_ent(attrs, *kp, 0, 0);
124 5228 ▶ if (e && HeVAL(e) && SvOK(HeVAL(e))) sv_catsv(out, HeVAL(e));
Branch: 3 branches
BranchTrueFalseTotal
if (e && HeVAL(e) && SvOK(HeVAL(e))) sv_catsv(out, HeVAL(e)); 5228 0 5228
if (e && HeVAL(e) && SvOK(HeVAL(e))) sv_catsv(out, HeVAL(e)); 5228 0 5228
if (e && HeVAL(e) && SvOK(HeVAL(e))) sv_catsv(out, HeVAL(e)); 5228 0 5228
125 }
126 5215 return out;
127 }
128  
129 4051 static otel_point *otel_point_new(pTHX_ SV *key, HV *attrs) {
130 otel_point *p;
131 4051 Newxz(p, 1, otel_point);
132 4051 p->key = key; /* takes ownership */
133 4051 ▶ p->attrs = attrs ? (HV *)SvREFCNT_inc((SV *)attrs) : newHV();
Branch: 1 branch
BranchTrueFalseTotal
p->attrs = attrs ? (HV *)SvREFCNT_inc((SV *)attrs) : newHV(); 4051 0 4051
134 4051 p->start_nanos = otel_wall_nanos();
135 4051 p->min = 1.0 / 0.0;
136 4051 p->max = -1.0 / 0.0;
137 4051 otel_expo_init(&p->expo, 20);
138 4051 return p;
139 }
140  
141 4051 static void otel_point_free(pTHX_ otel_point *p) {
142 4051 ▶ if (!p) return;
Branch: 1 branch
BranchTrueFalseTotal
if (!p) return; 0 4051 4051
143 4051 ▶ if (p->key) SvREFCNT_dec(p->key);
Branch: 1 branch
BranchTrueFalseTotal
if (p->key) SvREFCNT_dec(p->key); 4051 0 4051
144 4051 ▶ if (p->attrs) SvREFCNT_dec((SV *)p->attrs);
Branch: 1 branch
BranchTrueFalseTotal
if (p->attrs) SvREFCNT_dec((SV *)p->attrs); 4051 0 4051
145 4051 Safefree(p);
146 }
147  
148 /* Find or create the point for an attribute set.
149 *
150 * Past the cardinality cap every further set folds into ONE overflow point,
151 * whose single attribute is otel.metric.overflow. The series stops being
152 * useful at that moment, which is the intended signal: a metric that has
153 * overflowed says so, rather than quietly costing memory until something
154 * dies. */
155 5385 static otel_point *otel_instr_point(pTHX_ otel_instrument *in, HV *attrs) {
156 5385 SV *key = otel_attrs_key(aTHX_ attrs);
157 otel_point *p;
158 STRLEN kl;
159 5385 const char *ks = SvPV_const(key, kl);
160  
161 6004386 ▶ for (p = in->points; p; p = p->next) {
Branch: 1 branch
BranchTrueFalseTotal
for (p = in->points; p; p = p->next) { 5999337 5049 6004386
162 STRLEN pl;
163 5999337 const char *ps = SvPV_const(p->key, pl);
164 5999337 ▶ if (pl == kl && (kl == 0 || memEQ(ps, ks, kl))) {
Branch: 3 branches
BranchTrueFalseTotal
if (pl == kl && (kl == 0 || memEQ(ps, ks, kl))) { 2819520 3179817 5999337
if (pl == kl && (kl == 0 || memEQ(ps, ks, kl))) { 2819384 136 2819520
if (pl == kl && (kl == 0 || memEQ(ps, ks, kl))) { 200 2819184 2819384
165 336 SvREFCNT_dec(key);
166 336 return p;
167 }
168 }
169 5049 ▶ if (in->npoints >= OTEL_CARDINALITY_MAX) {
Branch: 1 branch
BranchTrueFalseTotal
if (in->npoints >= OTEL_CARDINALITY_MAX) { 1000 4049 5049
170 HV *ov;
171 1000 SvREFCNT_dec(key);
172 1000 in->overflow++;
173 /* reuse the one overflow point, creating it once */
174 5000 ▶ for (p = in->points; p; p = p->next) {
Branch: 1 branch
BranchTrueFalseTotal
for (p = in->points; p; p = p->next) { 4998 2 5000
175 STRLEN pl;
176 4998 const char *ps = SvPV_const(p->key, pl);
177 4998 ▶ if (pl == 20 && memEQ(ps, "otel.metric.overflow", 20)) return p;
Branch: 2 branches
BranchTrueFalseTotal
if (pl == 20 && memEQ(ps, "otel.metric.overflow", 20)) return p; 998 4000 4998
if (pl == 20 && memEQ(ps, "otel.metric.overflow", 20)) return p; 998 0 998
178 }
179 2 ov = newHV();
180 2 (void)hv_stores(ov, "otel.metric.overflow", newSViv(1));
181 2 p = otel_point_new(aTHX_ newSVpvs("otel.metric.overflow"), ov);
182 2 SvREFCNT_dec((SV *)ov);
183 2 p->next = in->points;
184 2 in->points = p;
185 2 return p;
186 }
187 4049 p = otel_point_new(aTHX_ key, attrs);
188 4049 p->next = in->points;
189 4049 in->points = p;
190 4049 in->npoints++;
191 4049 return p;
192 }
193  
194 /* ---- exemplars ---------------------------------------------------------- *
195 * The default filter is TRACE_BASED: record one only when there is a sampled
196 * span in context, because an exemplar whose trace was never recorded is a
197 * pointer to nothing. */
198 5381 static void otel_point_exemplar(otel_point *p, double v, otel_span *span,
199 int bucket) {
200 otel_exemplar *slot;
201 5381 ▶ if (!span) return; /* trace_based: no span, none */
Branch: 1 branch
BranchTrueFalseTotal
if (!span) return; /* trace_based: no span, none */ 5372 9 5381
202 9 ▶ if (bucket >= 0 && bucket < OTEL_EXEMPLAR_MAX) {
Branch: 2 branches
BranchTrueFalseTotal
if (bucket >= 0 && bucket < OTEL_EXEMPLAR_MAX) { 9 0 9
if (bucket >= 0 && bucket < OTEL_EXEMPLAR_MAX) { 5 4 9
203 /* aligned-bucket reservoir: one per bucket, so a histogram's
204 * exemplars span its range instead of clustering in the busiest
205 * bucket */
206 5 slot = &p->ex[bucket];
207 5 ▶ if (bucket >= p->n_ex) p->n_ex = bucket + 1;
Branch: 1 branch
BranchTrueFalseTotal
if (bucket >= p->n_ex) p->n_ex = bucket + 1; 5 0 5
208 }
209 else {
210 /* simple fixed-size reservoir */
211 4 p->ex_seen++;
212 4 ▶ if (p->n_ex < OTEL_EXEMPLAR_MAX) slot = &p->ex[p->n_ex++];
Branch: 1 branch
BranchTrueFalseTotal
if (p->n_ex < OTEL_EXEMPLAR_MAX) slot = &p->ex[p->n_ex++]; 4 0 4
213 else {
214 0 int r = (int)(otel_wall_nanos() % (U64TYPE)p->ex_seen);
215 0 ▶ if (r >= OTEL_EXEMPLAR_MAX) return;
Branch: 1 branch
BranchTrueFalseTotal
if (r >= OTEL_EXEMPLAR_MAX) return; 0 0 0
216 0 slot = &p->ex[r];
217 }
218 }
219 9 slot->value = v;
220 9 slot->time = otel_wall_nanos();
221 9 Copy(span->trace_id, slot->trace_id, 16, unsigned char);
222 9 Copy(span->span_id, slot->span_id, 8, unsigned char);
223 9 slot->has_span = 1;
224 }
225  
226 /* ---- recording ---------------------------------------------------------- */
227  
228 29 static int otel_bucket_of(const otel_instrument *in, double v) {
229 int i;
230 155 ▶ for (i = 0; i < in->nbounds; i++) if (v <= in->bounds[i]) return i;
Branch: 2 branches
BranchTrueFalseTotal
for (i = 0; i < in->nbounds; i++) if (v <= in->bounds[i]) return i; 27 126 153
for (i = 0; i < in->nbounds; i++) if (v <= in->bounds[i]) return i; 153 2 155
231 2 return in->nbounds;
232 }
233  
234 5391 static void otel_instr_record(pTHX_ otel_instrument *in, double v, HV *attrs,
235 otel_span *span) {
236 otel_point *p;
237 5391 ▶ if (!in || in->aggregation == OTEL_AGG_DROP) return;
Branch: 2 branches
BranchTrueFalseTotal
if (!in || in->aggregation == OTEL_AGG_DROP) return; 5391 0 5391
if (!in || in->aggregation == OTEL_AGG_DROP) return; 6 5385 5391
238 5385 p = otel_instr_point(aTHX_ in, attrs);
239 5385 p->time_nanos = otel_wall_nanos();
240  
241 5385 switch (in->aggregation) {
242 5232 case OTEL_AGG_SUM:
243 5232 p->sum += v;
244 5232 p->count++;
245 5232 otel_point_exemplar(p, v, span, -1);
246 5232 break;
247 4 case OTEL_AGG_LASTVALUE:
248 4 p->last = v;
249 4 p->count++;
250 4 break;
251 29 case OTEL_AGG_HISTOGRAM: {
252 29 int b = otel_bucket_of(in, v);
253 29 p->sum += v;
254 29 p->count++;
255 29 ▶ if (v < p->min) p->min = v;
Branch: 1 branch
BranchTrueFalseTotal
if (v < p->min) p->min = v; 19 10 29
256 29 ▶ if (v > p->max) p->max = v;
Branch: 1 branch
BranchTrueFalseTotal
if (v > p->max) p->max = v; 29 0 29
257 29 ▶ if (b <= OTEL_MAX_BOUNDS) p->buckets[b]++;
Branch: 1 branch
BranchTrueFalseTotal
if (b <= OTEL_MAX_BOUNDS) p->buckets[b]++; 29 0 29
258 29 otel_point_exemplar(p, v, span, b);
259 29 break;
260 }
261 120 case OTEL_AGG_EXPO:
262 120 otel_expo_record(&p->expo, v);
263 120 p->sum = p->expo.sum;
264 120 p->count = p->expo.count;
265 120 otel_point_exemplar(p, v, span, -1);
266 120 break;
267 }
268 }
269  
270 /* After a DELTA collection, every accumulator resets and the next interval
271 * starts now. Under CUMULATIVE nothing is reset and start_nanos stays put -
272 * which is the whole distinction, and the thing a backend notices when it is
273 * wrong. */
274 7 static void otel_point_reset(otel_point *p) {
275 7 U64TYPE now = otel_wall_nanos();
276 int i;
277 7 p->sum = 0;
278 7 p->count = 0;
279 7 p->min = 1.0 / 0.0;
280 7 p->max = -1.0 / 0.0;
281 462 ▶ for (i = 0; i <= OTEL_MAX_BOUNDS; i++) p->buckets[i] = 0;
Branch: 1 branch
BranchTrueFalseTotal
for (i = 0; i <= OTEL_MAX_BOUNDS; i++) p->buckets[i] = 0; 455 7 462
282 7 otel_expo_init(&p->expo, p->expo.scale);
283 7 p->n_ex = p->ex_seen = 0;
284 7 p->start_nanos = now;
285 7 }
286  
287 #endif /* OTEL_METRIC_H */
« include/otel_signal_pb.h ↑ Summary include/otel_config.h »