1
/**
2
 * Metric cardinality: how many time series one metric becomes, where it is stored, and what that backend bills.
3
 *
4
 * The product of label values is the same everywhere. What changes with the backend is what one label set
5
 * writes, whether each process writing the metric gets its own series, the limits worth knowing, and the unit
6
 * the bill is counted in. Each backend's rules are in BACKENDS below, and every one of them is a rule the
7
 * provider's own documentation states; the README's provider table quotes and links each one.
8
 *
9
 * For self-hosted Prometheus:
10
 *
11
 * Every number is a product, so nothing here is estimated except the disk, which uses the 1 to 2 bytes per sample
12
 * Prometheus's storage documentation gives:
13
 *
14
 *  - label sets are the product of each label's value count, times the share of combinations that occur;
15
 *  - each label set writes a fixed number of series for its type: a classic histogram one per bucket, +Inf
16
 *    included, plus `_sum` and `_count`; a summary one per quantile plus `_sum` and `_count`; a counter one; a
17
 *    gauge or a native histogram one. Clients that write `_created` add one more to counters, histograms and
18
 *    summaries, which prometheus_client for Python does by default;
19
 *  - every scrape target attaches its own `instance` label, so every process exposing the metric multiplies it.
20
 *
21
 * A summary's quantile count is folded into the type: Python's prometheus_client writes summaries with no
22
 * quantiles at all, and three (0.5, 0.9, 0.99) is a typical configuration, so those are the two options rather
23
 * than a number input that only one type reads.
24
 *
25
 * The mistakes it exists for are the common ones: counting a histogram as one series, forgetting the targets, and
26
 * treating a label's value count as additive rather than a multiplier.
27
 */
28
import type { Field, Output, Tool } from "@toolbench/sdk";
29

30
type Input = {
31
  backend: string;
32
  labels: string;
33
  type: string;
34
  client: string;
35
  buckets: number;
36
  created: boolean;
37
  targets: number;
38
  occur: number;
39
  interval: number;
40
  price: number;
41
};
42

43
/**
44
 * Retention is not an input. The disk figure is for Prometheus's default 15 days, which the note says, and is the
45
 * one number here that scales trivially with the reader's own retention. Cutting it left the form with one fewer
46
 * thing to fill in on the way to the series count, which is the answer people come for.
47
 */
48
const RETENTION_DAYS = 15;
49

50
/** Billing month for the per-sample and per-byte backends. AWS's own examples use 744 hours; a month is said in the note. */
51
const MONTH_S = 30 * 86_400;
52

53
type Family = "prom" | "cloudwatch" | "azure-custom" | "gcm-custom";
54

55
export type Backend = {
56
  name: string;
57
  /** How the provider's documentation names the thing it stores. */
58
  unit: "series" | "custom metrics";
59
  family: Family;
60
  /** Each target attaches its own identity: an `instance` label, or Cloud Monitoring's monitored resource. */
61
  targetsMultiply: boolean;
62
  /** What the price input is per, for this backend. */
63
  priceUnit?: string;
64
  /** A limit on series, with what it applies to. */
65
  seriesLimit?: { n: number; per: "metric" | "target"; what: string };
66
  /** A limit on labels per metric. Only those under the parser's own 30 can be broken. */
67
  labelLimit?: { n: number; what: string };
68
  /** The shortest interval the backend accepts, in seconds. */
69
  minInterval?: number;
70
  note: string;
71
};
72

73
/*
74
 * ⚠️ Every number here is quoted in the README with its source and the date it was checked. Change one only
75
 * from the provider's own page, and change the README in the same commit.
76
 *
77
 * Limits that apply to a whole workspace or subscription are judged against this one metric, so the tone is
78
 * "this metric alone breaks it", which is the case worth flagging; the method note says they are shared.
79
 */
80
export const BACKENDS: Record<string, Backend> = {
81
  prometheus: {
82
    name: "Prometheus, self-hosted",
83
    unit: "series",
84
    family: "prom",
85
    targetsMultiply: true,
86
    priceUnit: "1,000 active series",
87
    note: "Kept on your own servers.",
88
  },
89
  amp: {
90
    name: "Amazon Managed Service for Prometheus",
91
    unit: "series",
92
    family: "prom",
93
    targetsMultiply: true,
94
    priceUnit: "10 million samples ingested",
95
    seriesLimit: { n: 50_000_000, per: "metric", what: "active series per workspace, the default quota" },
96
    note: "Billed per metric sample ingested; storage and query samples are billed separately.",
97
  },
98
  "azure-prom": {
99
    name: "Azure Monitor managed service for Prometheus",
100
    unit: "series",
101
    family: "prom",
102
    targetsMultiply: true,
103
    priceUnit: "10 million samples ingested",
104
    seriesLimit: {
105
      n: 1_000_000,
106
      per: "metric",
107
      what: "active time series per Azure Monitor workspace, the default limit",
108
    },
109
    note: "Billed per sample ingested, retention included; query samples are billed separately.",
110
  },
111
  gmp: {
112
    name: "Google Cloud Managed Service for Prometheus",
113
    unit: "series",
114
    family: "prom",
115
    targetsMultiply: true,
116
    priceUnit: "1 million samples ingested",
117
    seriesLimit: { n: 1_000_000, per: "target", what: "active time series from Prometheus per monitored resource" },
118
    minInterval: 5,
119
    note: "Billed per sample ingested. A histogram is stored as one distribution series.",
120
  },
121
  cloudwatch: {
122
    name: "Amazon CloudWatch custom metrics",
123
    unit: "custom metrics",
124
    family: "cloudwatch",
125
    targetsMultiply: false,
126
    priceUnit: "metric-month",
127
    note: "Published with PutMetricData, or extracted from Embedded Metric Format logs.",
128
  },
129
  "azure-custom": {
130
    name: "Azure Monitor custom metrics",
131
    unit: "series",
132
    family: "azure-custom",
133
    targetsMultiply: false,
134
    seriesLimit: { n: 50_000, per: "metric", what: "active time series in a subscription per region" },
135
    labelLimit: { n: 10, what: "dimension keys per metric" },
136
    note: "In preview, and Microsoft says it won't become generally available.",
137
  },
138
  "gcm-custom": {
139
    name: "Google Cloud Monitoring custom metrics",
140
    unit: "series",
141
    family: "gcm-custom",
142
    targetsMultiply: true,
143
    priceUnit: "MiB ingested",
144
    seriesLimit: { n: 200_000, per: "target", what: "active time series from custom metrics per monitored resource" },
145
    minInterval: 5,
146
    note: "Billed per byte ingested: 8 bytes a point for a number, 80 for a distribution.",
147
  },
148
};
149

150
class InputError extends Error {
151
  readonly input: string;
152
  constructor(message: string, input: string) {
153
    super(message);
154
    this.input = input;
155
  }
156
}
157

158
export type Label = { name: string; values: number };
159

160
const NAME = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
161
/** Labels the client or the server already owns for a type, so a user label by that name collides. */
162
const RESERVED: Record<string, string[]> = { histogram: ["le"], summary: ["quantile"], summary3: ["quantile"] };
163
/** Types whose clients may write `_created`. */
164
const HAS_CREATED = new Set(["counter", "histogram", "summary", "summary3"]);
165

166
/**
167
 * One label per line, or comma-separated: `route 12`, `route=12` and `route: 12` all read the same. Prometheus's
168
 * naming rule is checked only for a Prometheus backend; CloudWatch dimensions and Azure dimensions take other names.
169
 */
170
export function parseLabels(text: string, prom = true): Label[] {
171
  const out: Label[] = [];
172
  const parts = text
173
    .split(/[\n,]/)
174
    .map((s) => s.trim())
175
    .filter((s) => s && !s.startsWith("#"));
176
  for (const part of parts) {
177
    const m = /^([^\s=:]+)\s*[=:\s]\s*([0-9][0-9_]*)$/.exec(part);
178
    if (!m) throw new InputError(`"${part}" is not a label and a count, such as "route 12".`, "labels");
179
    const name = m[1]!;
180
    if (prom && !NAME.test(name))
181
      throw new InputError(
182
        `"${name}" is not a valid label name: letters, digits and _, not starting with a digit.`,
183
        "labels",
184
      );
185
    if (prom && name.startsWith("__"))
186
      throw new InputError("Label names starting with __ are reserved for Prometheus itself.", "labels");
187
    const values = Number(m[2]!.replace(/_/g, ""));
188
    if (!Number.isSafeInteger(values) || values < 1) throw new InputError(`${name} needs at least 1 value.`, "labels");
189
    if (out.some((l) => l.name === name)) throw new InputError(`${name} is listed twice.`, "labels");
190
    out.push({ name, values });
191
  }
192
  if (out.length > 30) throw new InputError("At most 30 labels.", "labels");
193
  return out;
194
}
195

196
/** Series one label set writes, by type. */
197
export function perLabelSet(
198
  type: string,
199
  buckets: number,
200
  quantiles: number,
201
  created: boolean,
202
): { n: number; parts: string } {
203
  const c = created && HAS_CREATED.has(type) ? 1 : 0;
204
  const cr = c ? " + _created" : "";
205
  switch (type) {
206
    case "counter":
207
      return { n: 1 + c, parts: `_total${cr}` };
208
    case "gauge":
209
      return { n: 1, parts: "the value" };
210
    case "histogram":
211
      return { n: buckets + 1 + 2 + c, parts: `${buckets} buckets + le="+Inf" + _sum + _count${cr}` };
212
    case "summary":
213
    case "summary3": {
214
      const q = type === "summary3" ? 3 : quantiles;
215
      return { n: q + 2 + c, parts: `${q ? `${q} quantiles + ` : ""}_sum + _count${cr}` };
216
    }
217
    case "native":
218
      return { n: 1, parts: "one native histogram sample, its buckets inside it" };
219
    default:
220
      throw new InputError(`Unknown metric type "${type}".`, "type");
221
  }
222
}
223

224
/** 12345678 -> "12,345,678"; small fractions keep two digits. */
225
export function num(x: number): string {
226
  if (x >= 100 || Number.isInteger(x)) return Math.round(x).toLocaleString("en-US");
227
  return (Math.round(x * 100) / 100).toLocaleString("en-US");
228
}
229

230
/** Bytes in the largest unit that keeps the number at or above 1. */
231
export function bytes(n: number): string {
232
  const units = ["B", "KB", "MB", "GB", "TB", "PB"];
233
  let x = n;
234
  let i = 0;
235
  while (x >= 1000 && i < units.length - 1) {
236
    x /= 1000;
237
    i++;
238
  }
239
  return `${x >= 100 ? Math.round(x) : Math.round(x * 10) / 10} ${units[i]}`;
240
}
241

242
const money = (x: number) => (x >= 100 ? `$${Math.round(x).toLocaleString("en-US")}` : `$${x.toFixed(2)}`);
243
const plural = (n: number, one: string, many = `${one}s`) => `${num(n)} ${n === 1 ? one : many}`;
244
/** "45%", or "under 1%" for a share that would otherwise round to nothing. */
245
const pct = (part: number, whole: number) => {
246
  const p = (100 * part) / whole;
247
  if (p > 0 && p < 1) return "under 1%";
248
  if (p > 99 && p < 100) return "over 99%";
249
  return `${Math.round(p)}%`;
250
};
251

252
export function count(labels: Label[], occur: number): number {
253
  const product = labels.reduce((p, l) => p * l.values, 1);
254
  return Math.max(1, Math.ceil((product * occur) / 100));
255
}
256

257
/** 1,306,368,000 -> "1.31 billion"; below a million, the whole number. */
258
export function big(x: number): string {
259
  if (x >= 1e9) return `${num(Math.round(x / 1e7) / 100)} billion`;
260
  if (x >= 1e6) return `${num(Math.round(x / 1e4) / 100)} million`;
261
  return num(Math.round(x));
262
}
263

264
export type Writes = {
265
  /** Series one label set writes. */
266
  n: number;
267
  parts: string;
268
  /** Samples one label set writes per scrape or write, where the backend bills samples. */
269
  samples: number;
270
  /** "" exact, "up to" when it depends on how many buckets have counts, "at least" for the same, the other way. */
271
  bound: "" | "up to" | "at least";
272
  /** Where samples can't be counted from the inputs: the reason. */
273
  uncounted?: string;
274
  /** Bytes per point, for Cloud Monitoring's byte billing. */
275
  bytes: number;
276
};
277

278
/** What one label set writes, on this backend. */
279
export function writes(id: string, type: string, buckets: number, created: boolean): Writes {
280
  const b = BACKENDS[id]!;
281
  if (b.family === "cloudwatch") {
282
    perLabelSet(type, buckets, 0, false);
283
    return { n: 1, parts: "one metric per dimension combination, whatever the type", samples: 1, bound: "", bytes: 0 };
284
  }
285
  if (b.family === "azure-custom") {
286
    perLabelSet(type, buckets, 0, false);
287
    return {
288
      n: 1,
289
      parts: "one time series per combination of dimensions, whatever the type",
290
      samples: 1,
291
      bound: "",
292
      bytes: 0,
293
    };
294
  }
295
  if (b.family === "gcm-custom") {
296
    if (type === "histogram" || type === "native")
297
      return { n: 1, parts: "one distribution series, its buckets inside it", samples: 1, bound: "", bytes: 80 };
298
    const per = perLabelSet(type, buckets, 0, false);
299
    return { n: per.n, parts: per.parts, samples: per.n, bound: "", bytes: 8 };
300
  }
301
  const per = perLabelSet(type, buckets, 0, created);
302
  if (id === "gmp" && type === "histogram") {
303
    const c = per.n - (buckets + 3);
304
    return {
305
      n: 1 + c,
306
      parts: `one distribution series, its ${buckets + 1} buckets inside it${c ? " + _created" : ""}`,
307
      samples: buckets + 3 + c,
308
      bound: "up to",
309
      bytes: 0,
310
    };
311
  }
312
  if (id === "gmp" && type === "native") return { ...per, samples: 2, bound: "at least", bytes: 0 };
313
  if (id === "amp" && type === "native")
314
    return {
315
      ...per,
316
      samples: 0,
317
      bound: "",
318
      uncounted:
319
        "Amazon meters a native histogram at 0.25 of a sample per bucket with counts in it, which depends on your data.",
320
      bytes: 0,
321
    };
322
  if (id === "azure-prom" && type === "native")
323
    return {
324
      ...per,
325
      samples: 0,
326
      bound: "",
327
      uncounted: "Azure's pricing page doesn't say how a native histogram is counted.",
328
      bytes: 0,
329
    };
330
  return { ...per, samples: per.n, bound: "", bytes: 0 };
331
}
332

333
export default {
334
  run(input: Input) {
335
    try {
336
      const id = String(input.backend ?? "prometheus");
337
      const backend = BACKENDS[id];
338
      if (!backend) throw new InputError(`Unknown backend "${id}".`, "backend");
339
      const prom = backend.family === "prom";
340
      const labels = parseLabels(String(input.labels ?? ""), prom);
341
      const type = String(input.type);
342
      for (const l of labels) {
343
        if (prom && (RESERVED[type] ?? []).includes(l.name)) {
344
          const what = type === "histogram" ? "histogram" : "summary";
345
          throw new InputError(
346
            `"${l.name}" is the label a ${what} writes itself, so yours would collide with it.`,
347
            "labels",
348
          );
349
        }
350
      }
351
      const buckets = Number(input.buckets);
352
      if (type === "histogram" && (!Number.isInteger(buckets) || buckets < 0 || buckets > 1000)) {
353
        throw new InputError("Buckets is a whole number from 0 to 1,000, not counting +Inf.", "buckets");
354
      }
355
      if (id === "gcm-custom" && type === "histogram" && buckets + 1 > 200) {
356
        throw new InputError("Cloud Monitoring allows at most 200 buckets in a custom distribution.", "buckets");
357
      }
358
      const targets = Number(input.targets);
359
      if (!Number.isInteger(targets) || targets < 1)
360
        throw new InputError("At least 1 target exposes the metric.", "targets");
361
      const occur = Number(input.occur);
362
      if (!(occur > 0 && occur <= 100))
363
        throw new InputError("The share that occurs is above 0% and at most 100%.", "occur");
364
      const interval = Number(input.interval);
365
      if (!(interval > 0)) throw new InputError("The scrape interval is a positive number of seconds.", "interval");
366
      if (backend.minInterval && interval < backend.minInterval)
367
        throw new InputError(
368
          `${backend.name} accepts at most one point every ${backend.minInterval} s per series, so the interval is at least that.`,
369
          "interval",
370
        );
371
      const price = Number(input.price ?? 0);
372
      if (!(price >= 0)) throw new InputError("The price can't be negative.", "price");
373
      const created = prom && Boolean(input.created);
374

375
      const w = writes(id, type, buckets, created);
376
      const per = { n: w.n, parts: w.parts };
377
      const sets = count(labels, occur);
378
      const tf = backend.targetsMultiply ? targets : 1;
379
      const series = sets * per.n * tf;
380
      const without = (l: Label) =>
381
        count(
382
          labels.filter((x) => x !== l),
383
          occur,
384
        ) *
385
        per.n *
386
        tf;
387

388
      /*
389
       * Prometheus's instrumentation guide: keep a metric's cardinality below 10, and investigate anything over
390
       * 100. Its "cardinality" is label sets, before the type multiplies them, which is the number judged here.
391
       * The guide is Prometheus's, so only the Prometheus backends show it.
392
       */
393
      const tone = sets > 100 ? "bad" : sets >= 10 ? "warn" : undefined;
394
      const guide =
395
        sets > 100
396
          ? "Over 100, where Prometheus's guide says to look for another way."
397
          : sets >= 10
398
            ? "Prometheus's guide aims for fewer than 10."
399
            : "Fewer than 10, as Prometheus's guide aims for.";
400
      const ceiling =
401
        occur === 100 && labels.filter((l) => l.values > 1).length >= 2
402
          ? " Assumes every combination of values occurs; set the share that does if you know it."
403
          : "";
404

405
      /*
406
       * The multiplication, factor by factor, so the answer can be checked by hand. The share that occurs is a
407
       * factor of its own, and the label sets are rounded up after it, so with a share the product is the
408
       * ceiling and the series count can sit a few above it. A backend where every process writes into the
409
       * same metric has no targets factor, and the method says why.
410
       */
411
      const one = backend.unit === "custom metrics" ? "metric" : "series";
412
      const factors = labels.length
413
        ? labels.map(
414
            (l, i) =>
415
              `${num(l.values)} ${l.name}${i === labels.length - 1 ? (l.values === 1 ? " value" : " values") : ""}`,
416
          )
417
        : ["1 label set"];
418
      if (occur < 100) factors.push(`${num(occur)}% that occur`);
419
      factors.push(`${per.n} ${per.n === 1 ? one : one === "metric" ? "metrics" : "series"} per label set`);
420
      if (backend.targetsMultiply) factors.push(plural(targets, "target"));
421

422
      /*
423
       * Each change the reader can make, scored by the same multiplication with it made, fewest series first. The
424
       * native histogram is in it where a classic histogram is many series, because there it is usually the
425
       * biggest cut.
426
       *
427
       * ⚠️ A label's row is what DROPPING it leaves. Grouping its values into a few leaves something between that
428
       * and today, which is why the row says "Without route" and the method notes say how to group.
429
       */
430
      type Change = { name: string; after: number };
431
      const changes: Change[] = [];
432
      for (const l of labels) if (l.values > 1) changes.push({ name: `Without ${l.name}`, after: without(l) });
433
      if (prom && type === "histogram" && per.n > 1 + (created ? 1 : 0))
434
        changes.push({ name: "Native histogram", after: sets * tf });
435
      if (created && HAS_CREATED.has(type)) changes.push({ name: "Without _created", after: sets * (per.n - 1) * tf });
436
      changes.sort((a, b) => a.after - b.after);
437

438
      const metrics: Field[] = [];
439
      if (prom)
440
        metrics.push({ label: "Label sets", value: num(sets), note: `${guide}${ceiling}`, ...(tone ? { tone } : {}) });
441

442
      /* What the backend bills, in its own unit, and the bill when the reader gives their price for it. */
443
      let bill: number | undefined;
444
      const bound = w.bound ? `${w.bound[0]!.toUpperCase()}${w.bound.slice(1)} ` : "";
445
      if (id === "prometheus") {
446
        const perSecond = series / interval;
447
        const kept = perSecond * 86_400 * RETENTION_DAYS;
448
        metrics.push(
449
          { label: "Samples", value: `${num(perSecond)} a second`, note: `One per series every ${num(interval)} s.` },
450
          {
451
            label: "Disk",
452
            value: `${bytes(kept)} to ${bytes(kept * 2)}`,
453
            note: `Over ${RETENTION_DAYS} days, Prometheus's default retention, at 1 to 2 bytes a sample.`,
454
          },
455
        );
456
        bill = (series / 1000) * price;
457
      } else if (prom) {
458
        const monthly = (sets * tf * w.samples * MONTH_S) / interval;
459
        if (w.uncounted) {
460
          metrics.push({ label: "Samples ingested", value: "Not countable from these inputs", note: w.uncounted });
461
        } else {
462
          const how =
463
            id === "gmp" && type === "histogram"
464
              ? `Each scrape of a histogram is 2 samples plus 1 per bucket with a count in it, ${buckets + 1} buckets here.`
465
              : id === "gmp" && type === "native"
466
                ? "Each scrape of a native histogram is 2 samples plus 1 per 8 buckets with counts in them."
467
                : `One per series every ${num(interval)} s.`;
468
          metrics.push({
469
            label: "Samples ingested",
470
            value: `${bound}${big(monthly)} a month`,
471
            note: `${how} In a 30-day month.`,
472
          });
473
          bill = (monthly / (id === "gmp" ? 1e6 : 1e7)) * price;
474
        }
475
      } else if (id === "gcm-custom") {
476
        const mib = (sets * tf * w.samples * w.bytes * MONTH_S) / interval / 2 ** 20;
477
        metrics.push({
478
          label: "Bytes ingested",
479
          value: `${num(mib)} MiB a month`,
480
          note: `${w.bytes} bytes a point, one point per series every ${num(interval)} s, in a 30-day month. The first 150 MiB a month of each billing account are free.`,
481
        });
482
        bill = mib * price;
483
      } else if (id === "cloudwatch") {
484
        metrics.push({
485
          label: "Billed as",
486
          value: `${plural(series, "metric-month")}`,
487
          note: "Prorated by the hour, for the hours a metric gets data. PutMetricData requests, or an EMF log's ingestion, are billed on top.",
488
        });
489
        bill = series * price;
490
      } else {
491
        metrics.push({
492
          label: "Billed as",
493
          value: "Free during the preview",
494
          note: "For new work Microsoft points to OpenTelemetry metrics in an Azure Monitor workspace, billed per sample ingested.",
495
        });
496
      }
497
      if (bill !== undefined && price > 0) {
498
        metrics.push({
499
          label: "Bill",
500
          value: `${bound}${money(bill)} a month`,
501
          note: `At ${money(price)} per ${backend.priceUnit}.`,
502
        });
503
      }
504

505
      /* A provider's limit is flagged only when this metric alone breaks it. */
506
      const lim = backend.seriesLimit;
507
      if (lim) {
508
        const mine = lim.per === "target" ? series / tf : series;
509
        if (mine > lim.n)
510
          metrics.push({
511
            label: "Series limit",
512
            value: `${num(mine)} of ${num(lim.n)}`,
513
            note: `${backend.name} allows ${num(lim.n)} ${lim.what}${lim.per === "target" ? "; this is one target's share" : ""}.`,
514
            tone: "bad",
515
          });
516
      }
517
      if (id === "azure-prom") {
518
        const perMinute = (series * 60) / interval;
519
        if (perMinute > 1_000_000)
520
          metrics.push({
521
            label: "Ingest limit",
522
            value: `${num(perMinute)} events a minute`,
523
            note: "Azure allows 1,000,000 events per minute ingested into a workspace.",
524
            tone: "bad",
525
          });
526
      }
527
      if (backend.labelLimit && labels.length > backend.labelLimit.n)
528
        metrics.push({
529
          label: "Label limit",
530
          value: `${labels.length} labels`,
531
          note: `${backend.name} allows ${backend.labelLimit.n} ${backend.labelLimit.what}.`,
532
          tone: "bad",
533
        });
534

535
      const key = backend.unit === "custom metrics" ? plural(series, "custom metric") : `${num(series)} series`;
536
      const parts: Output[] = [
537
        {
538
          kind: "fields",
539
          role: "key",
540
          fields: [{ label: backend.unit === "custom metrics" ? "Custom metrics" : "Time series", value: key }],
541
        },
542
        { kind: "text", role: "formula", mono: true, text: factors.join(" x ") },
543
      ];
544
      if (changes.length) {
545
        parts.push({
546
          kind: "series",
547
          chart: {
548
            id: "changes",
549
            xLabel: "Change",
550
            yLabel: backend.unit === "custom metrics" ? "Metrics" : "Series",
551
            orientation: "horizontal",
552
            x: [...changes.map((c) => c.name), "Now"],
553
            series: [
554
              {
555
                label: backend.unit === "custom metrics" ? "Metrics" : "Series",
556
                shape: "bar",
557
                points: [...changes.map((c) => c.after), series],
558
              },
559
            ],
560
            readout: { highlightTable: true },
561
          },
562
        });
563
        parts.push({
564
          kind: "table",
565
          role: "comparison",
566
          caption: "Each change on its own",
567
          columns: [
568
            { label: "Change", wrap: "prose", rowHeader: true },
569
            {
570
              label: `${backend.unit === "custom metrics" ? "Metrics" : "Series"} after`,
571
              align: "end",
572
              mono: true,
573
              wrap: "none",
574
            },
575
            { label: "Saves", align: "end", mono: true, wrap: "none" },
576
          ],
577
          rows: changes.map((c) => [
578
            c.name,
579
            { text: num(c.after), mono: true },
580
            { text: `${num(series - c.after)} (${pct(series - c.after, series)})`, mono: true },
581
          ]),
582
          link: { chart: "changes", keys: changes.map((c) => c.name) },
583
        });
584
      }
585
      parts.push({ kind: "fields", role: "metrics", fields: metrics });
586

587
      const how = "How to make each change";
588
      const worked = "How this was worked out";
589
      const method: Field[] = [
590
        {
591
          group: worked,
592
          label: prom
593
            ? "Series per label set"
594
            : backend.unit === "custom metrics"
595
              ? "Metrics per label set"
596
              : "Series per label set",
597
          value: String(per.n),
598
          note: per.parts,
599
        },
600
      ];
601
      if (id !== "prometheus")
602
        method.push({ group: worked, label: "Stored in", value: backend.name, note: backend.note, mono: false });
603
      if (!backend.targetsMultiply && targets > 1) {
604
        method.push({
605
          group: worked,
606
          label: "Targets",
607
          value: "Not a factor here",
608
          note:
609
            id === "cloudwatch"
610
              ? `CloudWatch treats each unique combination of dimensions as one metric, so ${num(targets)} processes publishing the same dimensions write the same metrics. If each adds its own, such as a host, list it as a label.`
611
              : `Microsoft counts a time series per unique combination of metric and dimension values, so ${num(targets)} processes sending the same dimensions to the same resource count once. If each adds its own, such as a host, list it as a label.`,
612
        });
613
      }
614
      if (id === "gcm-custom" && targets > 1) {
615
        method.push({
616
          group: worked,
617
          label: "Targets",
618
          value: "Each its own monitored resource",
619
          note: "A time series is its metric labels plus the monitored resource it is written against, such as one k8s_container.",
620
        });
621
      }
622
      if (id === "azure-custom") {
623
        method.push({
624
          group: worked,
625
          label: "Interval",
626
          value: "60 s, fixed",
627
          note: "Azure Monitor ingests custom metrics once a minute, however often they are sent.",
628
        });
629
      }
630
      if (lim && !metrics.some((m) => m.label === "Series limit")) {
631
        method.push({
632
          group: worked,
633
          label: "Limit",
634
          value: `${num(lim.n)} ${lim.what}`,
635
          mono: false,
636
          note: lim.per === "target" ? "Counted per target." : "Shared by every metric there, not this one alone.",
637
        });
638
      }
639
      if (id === "gmp" && created) {
640
        method.push({
641
          group: worked,
642
          label: "_created",
643
          value: "Counted as the toggle says",
644
          note: "Google's pages checked don't say whether its collector stores _created as a series.",
645
        });
646
      }
647
      if (changes.some((c) => c.name.startsWith("Without ") && c.name !== "Without _created")) {
648
        method.push({
649
          group: how,
650
          label: "A label",
651
          value: "Drop it, or group its values into a few",
652
          mono: false,
653
          note: "The table counts dropping it; grouping leaves more. Put the detail on a span or a log line instead.",
654
        });
655
      }
656
      if (changes.some((c) => c.name === "Native histogram")) {
657
        method.push({
658
          group: how,
659
          label: "Native histogram",
660
          value: "All the buckets in one series",
661
          note:
662
            id === "prometheus"
663
              ? "Prometheus has to have native histograms turned on."
664
              : id === "amp"
665
                ? "Amazon accepts them, and meters each scrape at 0.25 of a sample per bucket with counts in it."
666
                : "Microsoft's limits and pricing pages don't mention native histograms; check that yours are accepted.",
667
        });
668
      }
669
      if (changes.some((c) => c.name === "Without _created")) {
670
        method.push({
671
          group: how,
672
          label: "_created",
673
          value: "PROMETHEUS_DISABLE_CREATED_SERIES=True",
674
          note: "In Python's prometheus_client. Newer Prometheus servers can store it as metadata instead.",
675
        });
676
      }
677
      parts.push({ kind: "fields", role: "method", fields: method });
678
      return { kind: "group", parts };
679
    } catch (error) {
680
      if (error instanceof InputError) return { kind: "error", message: error.message, input: error.input };
681
      throw error;
682
    }
683
  },
684
} satisfies Tool<Input>;