| 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
| Branch | True | False | Total |
| 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
| Branch | True | False | Total |
| 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
| Branch | True | False | Total |
| 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
| Branch | True | False | Total |
| 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
| Branch | True | False | Total |
| 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
| Branch | True | False | Total |
| 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
| Branch | True | False | Total |
| if (!p) return; |
0 |
4051 |
4051 |
|
| 143 |
4051 |
▶ | if (p->key) SvREFCNT_dec(p->key); |
Branch: 1 branch
| Branch | True | False | Total |
| if (p->key) SvREFCNT_dec(p->key); |
4051 |
0 |
4051 |
|
| 144 |
4051 |
▶ | if (p->attrs) SvREFCNT_dec((SV *)p->attrs); |
Branch: 1 branch
| Branch | True | False | Total |
| 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
| Branch | True | False | Total |
| 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
| Branch | True | False | Total |
| 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
| Branch | True | False | Total |
| 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
| Branch | True | False | Total |
| 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
| Branch | True | False | Total |
| 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
| Branch | True | False | Total |
| if (!span) return; /* trace_based: no span, none */ |
5372 |
9 |
5381 |
|
| 202 |
9 |
▶ | if (bucket >= 0 && bucket < OTEL_EXEMPLAR_MAX) { |
Branch: 2 branches
| Branch | True | False | Total |
| 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
| Branch | True | False | Total |
| 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
| Branch | True | False | Total |
| 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
| Branch | True | False | Total |
| 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
| Branch | True | False | Total |
| 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
| Branch | True | False | Total |
| 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
| Branch | True | False | Total |
| if (v < p->min) p->min = v; |
19 |
10 |
29 |
|
| 256 |
29 |
▶ | if (v > p->max) p->max = v; |
Branch: 1 branch
| Branch | True | False | Total |
| if (v > p->max) p->max = v; |
29 |
0 |
29 |
|
| 257 |
29 |
▶ | if (b <= OTEL_MAX_BOUNDS) p->buckets[b]++; |
Branch: 1 branch
| Branch | True | False | Total |
| 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
| Branch | True | False | Total |
| 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 */ |