1
/**
2
 * Percentiles across hosts: the p99 of a whole service, from per-instance histograms or from raw latencies, beside
3
 * the averaged per-instance p99 a dashboard shows, and how wrong that one is.
4
 *
5
 * What is pasted decides how it is read, with no switch to set:
6
 *
7
 *  - **Prometheus buckets**, the counts `histogram_quantile` reads: lines from a `/metrics` page or a query result,
8
 *    `..._bucket{instance="a",le="0.05"} 120`, the JSON the query API returns (which is also what Amazon's and
9
 *    Azure's managed Prometheus services return), or a CSV with an `le` column. Each bucket counts every request at
10
 *    or under its edge, so counts are cumulative.
11
 *  - **Google Cloud Monitoring distributions**, the `timeSeries.list` JSON of a DISTRIBUTION metric. Its buckets are
12
 *    described by `bucketOptions` (linear, exponential or explicit) and counted per bucket, not cumulatively, with an
13
 *    underflow bucket first and an overflow bucket last.
14
 *  - **AWS X-Ray response-time histograms**, from GetServiceGraph or GetTimeSeriesServiceStatistics: pairs of a
15
 *    response time in seconds and how many requests took it.
16
 *  - **Bucket and count rows** from a log query, KQL in Azure Monitor or CloudWatch Logs Insights, as CSV or as the
17
 *    query API's JSON: a duration rounded down to a bin, and how many requests fell in it.
18
 *  - **Raw latencies**, a group per host or per minute separated by a blank line, rolled up exactly.
19
 *
20
 * Every histogram is summed across groups edge by edge, which is what `sum by (le)` does, and the quantile estimated
21
 * from the total the way Prometheus does: find the bucket the rank falls in and interpolate linearly inside it. That
22
 * estimate is only known to within the bucket, so the bucket's two edges are reported as the error bound. The share
23
 * under each edge is exact. X-Ray pairs and raw latencies are values rather than buckets, so they are ranked exactly.
24
 *
25
 * ⚠️ Some exports carry only percentiles already worked out per period or per host: CloudWatch metric statistics,
26
 * Azure Monitor metrics, a Cloud Monitoring series aligned with ALIGN_PERCENTILE_99, a query that ends in pct() or
27
 * percentile(). Those are refused with a message saying why and what to paste instead, because pooling them is the
28
 * mistake this tool exists to show, and a confident wrong number is worse than an error.
29
 *
30
 * ⚠️ The direction is the point. Averaging percentiles does not always understate the tail. When the slow instance
31
 * carries a small share of the traffic, its own p99 enters the average at full weight and the average OVERSTATES the
32
 * true p99; when it carries most of the traffic, the average understates it. The tool says which, every time.
33
 *
34
 * For raw latencies the headline uses nearest rank, the smallest measurement with at least p% at or below it, which
35
 * is always a value that was observed. The detail table also gives linear interpolation, numpy's and R's default
36
 * (Hyndman and Fan's type 7), because tools disagree and a p99 from one is not comparable with a p99 from the other.
37
 */
38
import type { Cell, Field, Output, Tool } from "@toolbench/sdk";
39

40
type Input = { values: string; percentile: string; threshold: number };
41

42
class InputError extends Error {
43
  readonly input: string;
44
  readonly at: number | undefined;
45
  readonly len: number | undefined;
46

47
  constructor(message: string, input: string, at?: number, len?: number) {
48
    super(message);
49
    this.name = "InputError";
50
    this.input = input;
51
    this.at = at;
52
    this.len = len;
53
  }
54
}
55

56
const PERCENTILES: Record<string, number> = { p50: 50, p90: 90, p95: 95, p99: 99, "p99.9": 99.9 };
57

58
const sum = (xs: number[]) => xs.reduce((a, b) => a + b, 0);
59

60
/**
61
 * Enough digits to compare, and no more: one decimal place from 100 up, two below, three significant figures under
62
 * 1, with trailing zeros dropped so integer data reads as integers.
63
 */
64
function num(v: number): string {
65
  if (v === 0) return "0";
66
  const a = Math.abs(v);
67
  const text = a >= 100 ? v.toFixed(1) : a >= 1 ? v.toFixed(2) : v.toPrecision(3);
68
  return text.includes(".") ? text.replace(/\.?0+$/, "") : text;
69
}
70
const pct = (f: number) => `${(f * 100).toFixed(3)}%`;
71
/** 100000 as 100,000, without leaning on Intl, which a tool cannot assume. */
72
function count(v: number): string {
73
  const rounded = Number.isInteger(v) ? String(v) : v.toFixed(1);
74
  const [whole, frac] = rounded.split(".");
75
  return whole!.replace(/\B(?=(\d{3})+(?!\d))/g, ",") + (frac ? `.${frac}` : "");
76
}
77
/** Bucket edges computed as offset + width x i, or scale x factor ^ i, cleaned of float noise so they compare and print. */
78
const clean = (v: number) => Number(v.toPrecision(12));
79

80
/** How a value is written once its unit is known: seconds under one are shown as milliseconds, microseconds over 1,000 too. */
81
type Unit = "s" | "ms" | "us" | "";
82
function dur(v: number, unit: Unit): string {
83
  if (v === Number.POSITIVE_INFINITY) return "no upper limit";
84
  if (unit === "s") return Math.abs(v) < 1 ? `${num(v * 1000)} ms` : `${num(v)} s`;
85
  if (unit === "ms") return `${num(v)} ms`;
86
  if (unit === "us") return Math.abs(v) >= 1000 ? `${num(v / 1000)} ms` : `${num(v)} µs`;
87
  return num(v);
88
}
89
/** A value in milliseconds for the chart, which needs one unit for every bar. */
90
function plotValue(v: number, unit: Unit): number {
91
  return Number(num(unit === "s" ? v * 1000 : unit === "us" ? v / 1000 : v));
92
}
93
const ratioNote = (ratio: number) => {
94
  if (Math.abs(ratio - 1) < 0.05) return { text: "close to the pooled value", off: false };
95
  return { text: `${ratio.toFixed(2)}x the pooled value, ${ratio > 1 ? "too high" : "too low"}`, off: true };
96
};
97

98
/** What a group is called in the output: an instance, a Cloud Monitoring series, an X-Ray period. */
99
type Noun = { one: string; many: string };
100
const INSTANCE: Noun = { one: "instance", many: "instances" };
101
const GROUP: Noun = { one: "group", many: "groups" };
102
const SERIES: Noun = { one: "series", many: "series" };
103
const PERIOD: Noun = { one: "period", many: "periods" };
104
const SERVICE: Noun = { one: "service", many: "services" };
105
const poss = (word: string) => (word.endsWith("s") ? `${word}'` : `${word}'s`);
106
const across = (n: number, noun: Noun) => (n === 1 ? `this ${noun.one}` : n === 2 ? `both ${noun.many}` : `all ${n} ${noun.many}`);
107
const capital = (word: string) => word.charAt(0).toUpperCase() + word.slice(1);
108

109
/**
110
 * The refusal for an export that holds percentiles rather than counts. It says what the input is, why it cannot be
111
 * pooled, and where to find the histogram instead, because "wrong format" alone sends a reader back to the same export.
112
 */
113
function precomputed(what: string, instead: string): InputError {
114
  return new InputError(
115
    `${what} Those are percentiles already worked out, or averages, and they cannot be added up or averaged into a correct percentile for the whole service, which is the mistake this tool exists to show. ${instead}`,
116
    "values",
117
  );
118
}
119

120
// ── Histogram buckets ────────────────────────────────────────────────────────────────────────────────────────────
121

122
/** One histogram, as cumulative counts keyed by upper edge, the way histogram_quantile reads them. */
123
type Histogram = { label: string; buckets: Map<number, number>; sum?: number; count?: number };
124

125
/** Where a set of histograms came from, which changes the words around the numbers but never the arithmetic. */
126
type HistSource = {
127
  noun: Noun;
128
  unit: Unit;
129
  /** Prometheus's le counts requests at or under an edge; Cloud Monitoring and bin() count those under it. */
130
  inclusive: boolean;
131
  edgeColumn: string;
132
  estimate: (name: string, lower: string, upper: string) => string;
133
  overflow: (highest: string) => string;
134
  pool: (q: number, name: string) => string;
135
  /** The first row's name in the comparison: what this source's pooled estimate is made of. */
136
  method: string;
137
  /** The query that pools correctly, where the source has one to give: PromQL for Prometheus. */
138
  query?: (q: number) => string;
139
  meanNote: string;
140
  /** A word for "how many buckets", where the source's buckets are not called buckets. */
141
  bucketWord: string;
142
  /** What to do when the buckets are too coarse: add edges to a Prometheus histogram, narrow a bin, choose finer bucket options. */
143
  addAbove: (highest: string) => string;
144
  addBetween: (lower: string, upper: string) => string;
145
  addAt: (threshold: string) => string;
146
};
147

148
function prometheusSource(metric: string): HistSource {
149
  return {
150
    noun: INSTANCE,
151
    unit: unitOf(metric),
152
    inclusive: true,
153
    edgeColumn: "Bucket edge (le)",
154
    estimate: (name, lower, upper) => `Estimated from the summed buckets, as histogram_quantile does, so the true ${name} is somewhere between ${lower} and ${upper}.`,
155
    overflow: (highest) => `It falls in the +Inf bucket, so all we know is that it is above ${highest}, the highest edge, which is what Prometheus reports.`,
156
    pool: () => "Sum the buckets first, then estimate, with the query below.",
157
    method: "Sum the buckets, then estimate",
158
    query: (q) => `histogram_quantile(${q}, sum by (le) (rate(${metric || "your_metric"}_bucket[5m])))`,
159
    meanNote: "Exact: every _sum over every _count.",
160
    bucketWord: "buckets",
161
    addAbove: (highest) => `Add bucket edges above ${highest}`,
162
    addBetween: (lower, upper) => `Add bucket edges between ${lower} and ${upper}`,
163
    addAt: (threshold) => `Add a bucket edge at ${threshold}`,
164
  };
165
}
166

167
/** True when the text is Prometheus buckets rather than raw latencies: an `le` label, a `_bucket` series, or a CSV header with an `le` column. */
168
function looksLikeBuckets(text: string): boolean {
169
  return /\ble\s*=\s*"/.test(text) || /_bucket\b/.test(text) || /^[ \t]*(?:[A-Za-z_]+[ \t]*[,\t][ \t]*)?le[ \t]*[,\t]/im.test(text);
170
}
171

172
function edgeOf(raw: string, at: number): number {
173
  const t = raw.trim();
174
  if (/^\+?inf$/i.test(t)) return Number.POSITIVE_INFINITY;
175
  const v = Number(t);
176
  if (t === "" || !Number.isFinite(v)) throw new InputError(`"${t.slice(0, 20)}" is not a bucket edge. An le is a number, or +Inf.`, "values", at, Math.max(1, raw.length));
177
  return v;
178
}
179
function countOf(raw: string, at?: number): number {
180
  const t = raw.trim();
181
  const v = Number(t);
182
  if (t === "" || !Number.isFinite(v) || v < 0) {
183
    throw new InputError(`"${t.slice(0, 20)}" is not a count. A bucket's count is a number of requests, 0 or more.`, "values", at, at === undefined ? undefined : Math.max(1, raw.length));
184
  }
185
  return v;
186
}
187

188
/**
189
 * Lines in the Prometheus text format, or CSV rows, into one histogram per instance.
190
 *
191
 * The instance is the `instance` label where there is one; otherwise a `name:` line heading a block; otherwise the
192
 * block's number. Series of one instance that differ in other labels (method, status) are added edge by edge, which
193
 * is what `sum by (instance, le)` does. A line with labels and no metric name, `{instance="a",le="0.05"} 120`, is how
194
 * the Prometheus console shows the result of a `sum by (instance, le)` query, and is read the same way.
195
 */
196
function parseBuckets(text: string): { groups: Histogram[]; metric: string } {
197
  const groups = new Map<string, Histogram>();
198
  const get = (label: string) => {
199
    let g = groups.get(label);
200
    if (!g) {
201
      g = { label, buckets: new Map() };
202
      groups.set(label, g);
203
    }
204
    return g;
205
  };
206
  let metric = "";
207
  let block = 0;
208
  let heading = "";
209
  let blank = true;
210
  let csv: { instance: number; le: number; count: number } | undefined;
211
  let offset = 0;
212
  for (const line of text.split("\n")) {
213
    const at = offset;
214
    offset += line.length + 1;
215
    const trimmed = line.trim();
216
    if (trimmed === "") {
217
      blank = true;
218
      continue;
219
    }
220
    if (blank) {
221
      block++;
222
      heading = "";
223
      blank = false;
224
    }
225
    if (trimmed.startsWith("#")) continue;
226
    const lead = line.length - line.trimStart().length;
227

228
    const series = /^([A-Za-z_:][\w:]*)?(?:\{([^}]*)\})?\s+(\S+)(?:\s+\S+)?$/.exec(trimmed);
229
    const unnamed = series !== null && series[1] === undefined && series[2] !== undefined && /\ble\s*=/.test(series[2]);
230
    if (series && (unnamed || (series[1] !== undefined && /_(bucket|sum|count)$/.test(series[1])))) {
231
      const [, name = "_bucket", labelText = "", value] = series;
232
      const labels = new Map<string, string>();
233
      for (const m of labelText.matchAll(/([A-Za-z_]\w*)\s*=\s*"((?:[^"\\]|\\.)*)"/g)) labels.set(m[1]!, m[2]!);
234
      if (!unnamed) {
235
        const base = name.replace(/_(bucket|sum|count)$/, "");
236
        if (metric && base !== metric) {
237
          throw new InputError(`This is ${base}, and the lines above are ${metric}. Paste one histogram at a time.`, "values", at + lead, name.length);
238
        }
239
        metric = base;
240
      }
241
      const g = get(labels.get("instance") ?? (heading || `instance ${block}`));
242
      const valueAt = at + lead + trimmed.lastIndexOf(value!);
243
      if (name.endsWith("_bucket")) {
244
        const le = labels.get("le");
245
        if (le === undefined) throw new InputError("A _bucket line needs an le label: the edge it counts up to.", "values", at + lead, trimmed.length);
246
        const edge = edgeOf(le, at + lead + trimmed.indexOf(`"${le}"`) + 1);
247
        g.buckets.set(edge, (g.buckets.get(edge) ?? 0) + countOf(value!, valueAt));
248
      } else if (name.endsWith("_sum")) {
249
        const v = Number(value);
250
        if (!Number.isFinite(v)) throw new InputError(`"${value!.slice(0, 20)}" is not a number.`, "values", valueAt, value!.length);
251
        g.sum = (g.sum ?? 0) + v;
252
      } else {
253
        g.count = (g.count ?? 0) + countOf(value!, valueAt);
254
      }
255
      continue;
256
    }
257

258
    const cells = trimmed.split(/\s*[,\t]\s*/);
259
    const header = cells.map((c) => c.toLowerCase().replace(/^"|"$/g, ""));
260
    if (header.includes("le")) {
261
      const le = header.indexOf("le");
262
      const counted = header.findIndex((c) => c === "count" || c === "value" || c === "requests");
263
      const instance = header.findIndex((c) => c === "instance" || c === "host" || c === "name");
264
      if (counted < 0) throw new InputError("A CSV header with an le column also needs a count column.", "values", at + lead, trimmed.length);
265
      csv = { instance, le, count: counted };
266
      continue;
267
    }
268
    const named = /^([^\d,\t+.][^,\t:]*):$/.exec(trimmed);
269
    if (named) {
270
      heading = named[1]!.trim().slice(0, 40);
271
      continue;
272
    }
273
    const layout = csv ?? (cells.length === 3 ? { instance: 0, le: 1, count: 2 } : { instance: -1, le: 0, count: 1 });
274
    if (cells.length < 2 || cells.length <= Math.max(layout.le, layout.count, layout.instance)) {
275
      throw new InputError("This line is neither a Prometheus bucket line nor a CSV row of instance, le and count.", "values", at + lead, trimmed.length);
276
    }
277
    const cellAt = (i: number) => at + lead + Math.max(0, trimmed.indexOf(cells[i]!));
278
    const label = layout.instance >= 0 ? cells[layout.instance]!.replace(/^"|"$/g, "").slice(0, 40) : heading || `instance ${block}`;
279
    const g = get(label);
280
    const edge = edgeOf(cells[layout.le]!, cellAt(layout.le));
281
    g.buckets.set(edge, (g.buckets.get(edge) ?? 0) + countOf(cells[layout.count]!, cellAt(layout.count)));
282
  }
283

284
  const list = [...groups.values()].filter((g) => g.buckets.size > 0);
285
  if (list.length === 0) throw new InputError("No bucket counts found. Paste _bucket lines, or a CSV of instance, le and count.", "values");
286
  return { groups: list, metric };
287
}
288

289
type Sorted = { edges: number[]; counts: number[] };
290

291
/** Buckets in edge order, checked the way histogram_quantile needs them: a +Inf bucket, and counts that never fall. */
292
function sortBuckets(g: Histogram): Sorted {
293
  const edges = [...g.buckets.keys()].sort((a, b) => a - b);
294
  if (edges.at(-1) !== Number.POSITIVE_INFINITY) {
295
    throw new InputError(`${g.label} has no le="+Inf" bucket. That bucket holds the total, and histogram_quantile needs it.`, "values");
296
  }
297
  if (edges.length < 2) throw new InputError(`${g.label} has only the +Inf bucket, so there is no edge to estimate from.`, "values");
298
  const counts = edges.map((e) => g.buckets.get(e)!);
299
  for (let i = 1; i < counts.length; i++) {
300
    if (counts[i]! >= counts[i - 1]!) continue;
301
    // rate() can leave a count a hair under the one before it; Prometheus evens those out, and so does this.
302
    if (counts[i - 1]! - counts[i]! <= 1e-6 * Math.max(1, counts.at(-1)!)) {
303
      counts[i] = counts[i - 1]!;
304
      continue;
305
    }
306
    throw new InputError(
307
      `${g.label} counts ${count(counts[i]!)} at le=${edges[i]} but ${count(counts[i - 1]!)} at le=${edges[i - 1]}. Prometheus buckets are cumulative, each counting every request at or under its edge, so a count never falls. These look like counts per bucket: add each one to the counts before it.`,
308
      "values",
309
    );
310
  }
311
  return { edges, counts };
312
}
313

314
type Estimate = { value: number; lower: number; upper: number };
315

316
/** histogram_quantile, as Prometheus computes it: the bucket the rank falls in, and a straight line inside it. */
317
function bucketQuantile(q: number, { edges, counts }: Sorted): Estimate | undefined {
318
  const total = counts.at(-1)!;
319
  if (total === 0) return undefined;
320
  const rank = q * total;
321
  const b = counts.findIndex((c) => c >= rank);
322
  if (b === edges.length - 1) return { value: edges.at(-2)!, lower: edges.at(-2)!, upper: Number.POSITIVE_INFINITY };
323
  if (b === 0 && edges[0]! <= 0) return { value: edges[0]!, lower: edges[0]!, upper: edges[0]! };
324
  const lower = b === 0 ? 0 : edges[b - 1]!;
325
  const below = b === 0 ? 0 : counts[b - 1]!;
326
  const inBucket = counts[b]! - below;
327
  return { value: lower + (edges[b]! - lower) * ((rank - below) / inBucket), lower, upper: edges[b]! };
328
}
329

330
function unitOf(metric: string): Unit {
331
  if (/(^|_)seconds$/.test(metric)) return "s";
332
  if (/(^|_)(milliseconds|ms)$/.test(metric)) return "ms";
333
  return "";
334
}
335

336
function histogramRollup(groups: Histogram[], src: HistSource, name: string, q: number, threshold: number): Output {
337
  const sorted = groups.map(sortBuckets);
338
  const edges = sorted[0]!.edges;
339
  for (const [i, s] of sorted.entries()) {
340
    if (s.edges.length !== edges.length || s.edges.some((e, j) => e !== edges[j])) {
341
      throw new InputError(
342
        `${groups[i]!.label} has different bucket edges from ${groups[0]!.label}. Summing buckets edge by edge only works when every ${src.noun.one} uses the same edges.`,
343
        "values",
344
      );
345
    }
346
  }
347
  const { noun } = src;
348
  const d = (v: number) => dur(v, src.unit);
349
  const under = src.inclusive ? "at or under" : "under";
350
  const Under = capital(under);
351
  const pooled: Sorted = { edges, counts: edges.map((_, j) => sum(sorted.map((s) => s.counts[j]!))) };
352
  const total = pooled.counts.at(-1)!;
353
  if (total === 0) throw new InputError("Every bucket is empty, so there is no request to estimate from.", "values");
354
  const est = bucketQuantile(q, pooled)!;
355
  const each = sorted.map((s) => bucketQuantile(q, s));
356
  const counted = each.filter((e): e is Estimate => e !== undefined);
357
  const averaged = sum(counted.map((e) => e.value)) / counted.length;
358
  const unbounded = est.upper === Number.POSITIVE_INFINITY;
359
  const width = est.upper - est.lower;
360

361
  const edgeAt = edges.findIndex((e) => Math.abs(e - threshold) <= 1e-9 * Math.max(1, threshold));
362
  const share = (c: number) => c / total;
363
  const below = edges.findLastIndex((e) => e < threshold);
364
  const above = edges.findIndex((e) => e > threshold);
365
  const sharePrecise = edgeAt >= 0;
366
  const shareLow = sharePrecise ? share(pooled.counts[edgeAt]!) : below >= 0 ? share(pooled.counts[below]!) : 0;
367
  const shareHigh = sharePrecise ? shareLow : share(pooled.counts[above]!);
368

369
  const r = groups.length > 1 && counted.length > 0 ? ratioNote(averaged / est.value) : undefined;
370
  const off = r?.off ?? false;
371
  const many = groups.length > 1 && counted.length > 0;
372

373
  /*
374
   * The answer is the two methods side by side: the buckets only support a range, so the pooled value is rounded to a
375
   * tenth of the bucket's order of magnitude (1 ms in a 25 ms bucket, 10 ms in a 250 ms one) and written beside the
376
   * bucket, not to hundredths. Neither row is toned: they share one frame, and the third column says which way the
377
   * average is wrong.
378
   */
379
  const rough = (v: number) => {
380
    if (!(width > 0) || !Number.isFinite(width)) return v;
381
    const step = 10 ** (Math.floor(Math.log10(width)) - 1);
382
    const r2 = clean(Math.round(v / step) * step);
383
    return r2 >= est.lower && r2 <= est.upper ? r2 : v;
384
  };
385
  const parts: Output[] = [
386
    {
387
      kind: "table",
388
      role: "comparison",
389
      caption: `${name} across ${across(groups.length, noun)}`,
390
      columns: [
391
        { label: "Method", wrap: "prose" },
392
        { label: name, align: "end", mono: true, wrap: "none" },
393
        { label: "What you can claim", wrap: "prose" },
394
      ],
395
      rows: [
396
        [
397
          src.method,
398
          { text: unbounded ? `above ${d(est.lower)}` : `about ${d(rough(est.value))}`, mono: true },
399
          unbounded ? "no upper bound: it is past the highest edge" : est.lower > 0 ? `somewhere in ${d(est.lower)} to ${d(est.upper)}` : `somewhere under ${d(est.upper)}`,
400
        ],
401
        ...(many ? [[`Average of the ${poss(noun.many)} ${name}s`, { text: d(averaged), mono: true }, r!.text] as Cell[]] : []),
402
      ],
403
    },
404
  ];
405

406
  /*
407
   * Why the answer is a range: the share of requests slower than each edge, on log axes, with the percentile's line.
408
   * The line crosses it inside one bucket, and the estimate can be anywhere in that bucket. The share at each edge is
409
   * exact; the straight line between two edges is the assumption histogram_quantile makes.
410
   */
411
  const finite = edges.map((e, j) => [e, j] as const).filter(([e]) => e !== Number.POSITIVE_INFINITY && e > 0);
412
  if (finite.length >= 2) {
413
    const plot = (v: number) => plotValue(v, src.unit);
414
    const tail = 100 * (1 - q);
415
    parts.push({
416
      kind: "series",
417
      chart: {
418
        xLabel: src.edgeColumn,
419
        ...(src.unit === "" ? {} : { xUnit: "ms" }),
420
        yLabel: `Share slower than the edge`,
421
        yUnit: "%",
422
        xScale: "log",
423
        yScale: "log",
424
        x: finite.map(([e]) => plot(e)),
425
        series: [
426
          {
427
            label: `Requests ${src.inclusive ? "over" : "at or over"} each edge`,
428
            shape: "line",
429
            markers: true,
430
            unit: "%",
431
            points: finite.map(([, j]) => Number((100 * (1 - share(pooled.counts[j]!))).toPrecision(4))),
432
          },
433
        ],
434
        thresholds: [{ y: Number(tail.toPrecision(4)), label: `${num(tail)}% slower: the ${name}` }],
435
        annotations: [
436
          ...(est.lower > 0 ? [{ x: plot(est.lower), label: unbounded ? `${name} above here` : "from" }] : []),
437
          ...(unbounded ? [] : [{ x: plot(est.upper), label: "to" }]),
438
        ],
439
      },
440
    });
441
  }
442

443
  const metrics: Field[] = [
444
    {
445
      label: `${Under} ${d(threshold)}`,
446
      value: sharePrecise ? pct(shareLow) : `${pct(shareLow)} to ${pct(shareHigh)}`,
447
      note: sharePrecise ? `exact: ${count(pooled.counts[edgeAt]!)} of ${count(total)}` : `no bucket edge at ${d(threshold)}, so the range between the edges either side`,
448
    },
449
  ];
450
  if (groups.every((g) => g.sum !== undefined && g.count !== undefined) && sum(groups.map((g) => g.count!)) > 0) {
451
    metrics.push({ label: "Mean", value: d(sum(groups.map((g) => g.sum!)) / sum(groups.map((g) => g.count!))), note: src.meanNote });
452
  }
453
  metrics.push({ label: "Requests", value: count(total), note: `${groups.length} ${groups.length === 1 ? noun.one : noun.many}, ${edges.length} ${src.bucketWord} each` });
454
  parts.push({ kind: "fields", role: "metrics", fields: metrics });
455

456
  const actions: { tone: "bad" | "warn"; what: string; why: string }[] = [];
457
  if (unbounded) {
458
    actions.push({
459
      tone: "bad",
460
      what: src.addAbove(d(est.lower)),
461
      why: `More than ${pct(1 - q)} of requests are slower than the highest edge, so the ${name} has no upper bound.`,
462
    });
463
  }
464
  if (off) {
465
    const ratio = averaged / est.value;
466
    actions.push({ tone: ratio > 2 || ratio < 0.5 ? "bad" : "warn", what: `Stop averaging per-${noun.one} ${name}s`, why: src.pool(q, name) });
467
  }
468
  if (!unbounded && width > 0.25 * est.value) {
469
    actions.push({
470
      tone: "warn",
471
      what: src.addBetween(d(est.lower), d(est.upper)),
472
      why: `The ${name} can be anywhere in that bucket, a range of ${d(width)}, which is ${Math.round((100 * width) / est.value)}% of the estimate.`,
473
    });
474
  }
475
  if (!sharePrecise) {
476
    actions.push({
477
      tone: "warn",
478
      what: src.addAt(d(threshold)),
479
      why: `Without one, the share of requests ${under} it is only known to be between ${pct(shareLow)} and ${pct(shareHigh)}.`,
480
    });
481
  }
482
  if (actions.length > 0) {
483
    parts.push({
484
      kind: "table",
485
      role: "actions",
486
      caption: "What to change, worst first",
487
      columns: [{ label: "What to do" }, { label: "Why" }],
488
      rows: actions.sort((a, b) => (a.tone === b.tone ? 0 : a.tone === "bad" ? -1 : 1)).map((a) => [{ text: a.what, tone: a.tone }, a.why]),
489
    });
490
  }
491
  if (src.query) parts.push({ kind: "code", lang: "promql", source: src.query(q) });
492

493
  // Slowest first, so the instance that decides the tail is the first row.
494
  const order = groups.map((_, i) => i).sort((a, b) => (each[b]?.value ?? -1) - (each[a]?.value ?? -1));
495
  parts.push({
496
    kind: "table",
497
    caption: `Each ${noun.one} on its own, slowest first, estimated from its own buckets`,
498
    columns: [
499
      { label: capital(noun.one), wrap: "none", rowHeader: true },
500
      { label: "Requests", align: "end", mono: true, wrap: "none" },
501
      { label: `${name} estimate`, align: "end", mono: true, wrap: "none" },
502
      { label: "Somewhere between", align: "end", mono: true, wrap: "none" },
503
      { label: `${Under} ${d(threshold)}`, align: "end", mono: true, wrap: "none" },
504
    ],
505
    rows: order.map((i) => {
506
      const g = groups[i]!;
507
      const e = each[i];
508
      const n = sorted[i]!.counts.at(-1)!;
509
      const own = !sharePrecise ? "no edge there" : n > 0 ? pct(sorted[i]!.counts[edgeAt]! / n) : "no requests";
510
      return [
511
        g.label,
512
        { text: count(n), mono: true },
513
        { text: e ? d(e.value) : "no requests", mono: true },
514
        { text: !e ? "" : e.upper === Number.POSITIVE_INFINITY ? `above ${d(e.lower)}` : `${d(e.lower)} to ${d(e.upper)}`, mono: true },
515
        { text: own, mono: true },
516
      ];
517
    }),
518
  });
519
  parts.push({
520
    kind: "table",
521
    caption: `Every ${noun.one} together: the share ${under} each edge is exact`,
522
    columns: [
523
      { label: src.edgeColumn, mono: true, wrap: "none", rowHeader: true },
524
      { label: `Requests ${under} it`, align: "end", mono: true, wrap: "none" },
525
      { label: "Share", align: "end", mono: true, wrap: "none" },
526
      { label: "Note", wrap: "prose" },
527
    ],
528
    rows: edges.map((e, j) => {
529
      const words = [j === edgeAt ? "your threshold" : "", e === est.upper && !unbounded ? `the ${name} falls in the bucket ending here` : ""].filter(Boolean).join("; ");
530
      return [
531
        { text: e === Number.POSITIVE_INFINITY ? "+Inf" : `${num(e)}${src.unit === "s" ? ` (${d(e)})` : ""}`, mono: true },
532
        { text: count(pooled.counts[j]!), mono: true },
533
        { text: pct(share(pooled.counts[j]!)), mono: true },
534
        words,
535
      ];
536
    }),
537
  });
538
  return { kind: "group", parts };
539
}
540

541
// ── JSON exports from the cloud providers ────────────────────────────────────────────────────────────────────────
542

543
type Json = null | boolean | number | string | Json[] | { [key: string]: Json };
544
type Obj = { [key: string]: Json };
545
const isObj = (v: Json | undefined): v is Obj => typeof v === "object" && v !== null && !Array.isArray(v);
546
const arr = (v: Json | undefined): Json[] => (Array.isArray(v) ? v : []);
547
/** int64 fields arrive as strings in Cloud Monitoring's JSON, and as numbers everywhere else. */
548
const numberOf = (v: Json | undefined): number => (typeof v === "number" ? v : typeof v === "string" && v.trim() !== "" ? Number(v) : Number.NaN);
549

550
/**
551
 * Cloud Monitoring's BucketOptions as the finite upper edges, in bucket order.
552
 *
553
 * Bucket 0 is the underflow bucket and the last is the overflow bucket. Bucket i's upper edge is offset + width x i
554
 * for linear buckets, scale x growthFactor ^ i for exponential ones, and bounds[i] for explicit ones, for i from 0 to
555
 * N - 2, so there is one more bucket than there are finite edges, and the overflow bucket becomes +Inf here. Proto3
556
 * JSON leaves out a field whose value is zero, which is why a missing offset is 0 rather than an error.
557
 */
558
function gcpEdges(options: Json | undefined, where: string): number[] {
559
  if (!isObj(options)) throw new InputError(`${where} has no bucketOptions, so its buckets have no edges.`, "values");
560
  const finite = (n: number) => {
561
    if (!Number.isInteger(n) || n < 1) throw new InputError(`${where}: numFiniteBuckets must be a whole number of 1 or more.`, "values");
562
    if (n > 2000) throw new InputError(`${where} has ${count(n)} finite buckets, more than this tool lays out. 2,000 is the limit.`, "values");
563
    return n;
564
  };
565
  const linearOpts = options.linearBuckets;
566
  if (isObj(linearOpts)) {
567
    const n = finite(numberOf(linearOpts.numFiniteBuckets));
568
    const width = numberOf(linearOpts.width);
569
    const offset = linearOpts.offset === undefined ? 0 : numberOf(linearOpts.offset);
570
    if (!(width > 0) || !Number.isFinite(offset)) throw new InputError(`${where}: linear buckets need a width above 0 and a numeric offset.`, "values");
571
    return Array.from({ length: n + 1 }, (_, i) => clean(offset + width * i));
572
  }
573
  const exponential = options.exponentialBuckets;
574
  if (isObj(exponential)) {
575
    const n = finite(numberOf(exponential.numFiniteBuckets));
576
    const factor = numberOf(exponential.growthFactor);
577
    const scale = numberOf(exponential.scale);
578
    if (!(factor > 1) || !(scale > 0)) throw new InputError(`${where}: exponential buckets need a growthFactor above 1 and a scale above 0.`, "values");
579
    return Array.from({ length: n + 1 }, (_, i) => clean(scale * factor ** i));
580
  }
581
  const explicit = options.explicitBuckets;
582
  if (isObj(explicit)) {
583
    const bounds = arr(explicit.bounds).map(numberOf);
584
    if (bounds.length === 0 || bounds.some((b) => !Number.isFinite(b))) throw new InputError(`${where}: explicit buckets need a list of numeric bounds.`, "values");
585
    if (bounds.some((b, i) => i > 0 && b <= bounds[i - 1]!)) throw new InputError(`${where}: explicit bounds must increase from one to the next.`, "values");
586
    if (bounds.length > 2001) throw new InputError(`${where} has ${count(bounds.length)} bounds, more than this tool lays out. 2,001 is the limit.`, "values");
587
    return bounds;
588
  }
589
  throw new InputError(`${where}: bucketOptions has none of linearBuckets, exponentialBuckets or explicitBuckets.`, "values");
590
}
591

592
/** One Distribution's per-bucket counts as cumulative counts at each finite edge, with the total beside them. */
593
function gcpBuckets(dist: Obj, where: string): { edges: number[]; counts: number[]; total: number; mean: number | undefined } {
594
  const edges = gcpEdges(dist.bucketOptions, where);
595
  const n = edges.length + 1;
596
  const raw = arr(dist.bucketCounts);
597
  if (raw.length > n) throw new InputError(`${where} has ${raw.length} bucket counts, but its bucketOptions describe only ${n} buckets.`, "values");
598
  // A shorter list leaves the rest at zero: Cloud Monitoring may drop trailing empty buckets.
599
  const perBucket = Array.from({ length: n }, (_, i) => (i < raw.length ? countOf(String(raw[i])) : 0));
600
  const counts: number[] = [];
601
  let running = 0;
602
  for (const c of perBucket) {
603
    running += c;
604
    counts.push(running);
605
  }
606
  const declared = dist.count === undefined ? running : numberOf(dist.count);
607
  if (Number.isFinite(declared) && Math.abs(declared - running) > 1e-6 * Math.max(1, running)) {
608
    throw new InputError(`${where} says its count is ${count(declared)}, but its bucket counts add up to ${count(running)}. The two must match.`, "values");
609
  }
610
  // Proto3 JSON drops a zero mean too, so a missing mean is 0 only when there is nothing to average.
611
  const mean = dist.mean === undefined ? (running === 0 ? 0 : undefined) : numberOf(dist.mean);
612
  return { edges, counts: counts.slice(0, edges.length), total: running, mean: mean !== undefined && Number.isFinite(mean) ? mean : undefined };
613
}
614

615
/** A Cloud Monitoring unit as one this tool prints. Anything else is shown as plain numbers. */
616
function gcpUnit(unit: Json | undefined): Unit {
617
  if (unit === "s") return "s";
618
  if (unit === "ms") return "ms";
619
  if (unit === "us") return "us";
620
  return "";
621
}
622

623
const GCP: Omit<HistSource, "unit"> = {
624
  noun: SERIES,
625
  inclusive: false,
626
  edgeColumn: "Bucket upper edge",
627
  estimate: (name, lower, upper) =>
628
    `Estimated from the summed distributions, interpolating inside a bucket as Prometheus's histogram_quantile does, so the true ${name} is somewhere between ${lower} and ${upper}.`,
629
  overflow: (highest) => `It falls in the overflow bucket, so all we know is that it is above ${highest}, the highest edge.`,
630
  pool: (_q, name) =>
631
    `Add the distributions together first, then take the ${name}, as this tool does. In Cloud Monitoring, REDUCE_SUM across the series keeps a distribution; a ${name} worked out per series cannot be combined afterwards.`,
632
  method: "Add the distributions, then estimate",
633
  meanNote: "Exact: each distribution's mean, weighted by its count.",
634
  bucketWord: "buckets",
635
  // A built-in metric's buckets come with it; only a metric you write yourself can be given other bucket options.
636
  addAbove: (highest) => `For a metric you write, use bucket options that reach above ${highest}`,
637
  addBetween: (lower, upper) => `For a metric you write, use finer buckets between ${lower} and ${upper}`,
638
  addAt: (threshold) => `For a metric you write, put a bucket boundary at ${threshold}`,
639
};
640

641
/**
642
 * Cloud Monitoring's JSON into one histogram per time series: a timeSeries.list response, a list of TimeSeries, one
643
 * TimeSeries, or a bare Distribution.
644
 *
645
 * A DELTA or GAUGE series holds one distribution per interval, and those add up. A CUMULATIVE series holds running
646
 * totals since its start time, so adding its points would count early requests again; the newest point already holds
647
 * them all, and it is the one used.
648
 */
649
function gcpHistograms(json: Json): { groups: Histogram[]; src: HistSource } | undefined {
650
  let series: Obj[];
651
  if (isObj(json) && Array.isArray(json.timeSeries)) series = json.timeSeries.filter(isObj);
652
  else if (Array.isArray(json) && json.length > 0 && json.every((s) => isObj(s) && Array.isArray(s.points))) series = json as Obj[];
653
  else if (isObj(json) && Array.isArray(json.points)) series = [json];
654
  else if (isObj(json) && (isObj(json.bucketOptions) || isObj(json.distributionValue))) {
655
    series = [{ points: [{ value: { distributionValue: isObj(json.distributionValue) ? json.distributionValue : json } }] }];
656
  } else return undefined;
657
  if (series.length === 0) {
658
    throw new InputError("This timeSeries.list response has no time series in it. Check the filter and the interval, then paste the response again.", "values");
659
  }
660

661
  const labelsOf = (s: Obj): Record<string, string> => {
662
    const out: Record<string, string> = {};
663
    for (const part of [s.resource, s.metric]) {
664
      const labels = isObj(part) ? part.labels : undefined;
665
      if (isObj(labels)) for (const [k, v] of Object.entries(labels)) out[k] = String(v);
666
    }
667
    return out;
668
  };
669
  const all = series.map(labelsOf);
670
  const keys = [...new Set(all.flatMap((l) => Object.keys(l)))];
671
  const varying = keys.filter((k) => new Set(all.map((l) => l[k] ?? "")).size > 1);
672

673
  const units = new Set(series.map((s) => gcpUnit(s.unit)));
674
  if (units.size > 1) throw new InputError("These series are in different units. Paste series of one metric.", "values");
675
  const groups: Histogram[] = [];
676
  for (const [i, s] of series.entries()) {
677
    const label = (varying.map((k) => all[i]![k]).filter(Boolean).join(" / ") || `series ${i + 1}`).slice(0, 40);
678
    const points = arr(s.points).filter(isObj);
679
    if (points.length === 0) continue;
680
    const values = points.map((p) => (isObj(p.value) ? p.value : {}));
681
    if (values.every((v) => !isObj(v.distributionValue))) {
682
      if (values.some((v) => v.doubleValue !== undefined || v.int64Value !== undefined)) {
683
        throw precomputed(
684
          `${label} holds single numbers, not distributions. A series aligned with a percentile aligner, such as ALIGN_PERCENTILE_99, comes back like this.`,
685
          "Ask for the series with ALIGN_DELTA, or with no aligner, and the points stay distributions, with every bucket count in them.",
686
        );
687
      }
688
      throw new InputError(`${label} has no distributionValue in its points. Paste a series of a DISTRIBUTION metric.`, "values");
689
    }
690
    const endOf = (p: Obj) => {
691
      const interval = isObj(p.interval) ? p.interval : {};
692
      return typeof interval.endTime === "string" ? Date.parse(interval.endTime) : 0;
693
    };
694
    const chosen = s.metricKind === "CUMULATIVE" ? [points.reduce((a, b) => (endOf(b) > endOf(a) ? b : a))] : points;
695
    let edges: number[] | undefined;
696
    let counts: number[] = [];
697
    let weighted = 0;
698
    let total = 0;
699
    let meanKnown = true;
700
    for (const p of chosen) {
701
      const dist = isObj(p.value) ? p.value.distributionValue : undefined;
702
      if (!isObj(dist)) continue;
703
      const b = gcpBuckets(dist, label);
704
      if (edges && (edges.length !== b.edges.length || edges.some((e, j) => e !== b.edges[j]))) {
705
        throw new InputError(`${label} changes its bucket options between points, so its points cannot be added edge by edge.`, "values");
706
      }
707
      edges = b.edges;
708
      counts = counts.length === 0 ? b.counts : counts.map((c, j) => c + b.counts[j]!);
709
      total += b.total;
710
      if (b.mean === undefined) meanKnown = false;
711
      else weighted += b.mean * b.total;
712
    }
713
    if (!edges) continue;
714
    const buckets = new Map<number, number>();
715
    edges.forEach((e, j) => buckets.set(e, counts[j]!));
716
    buckets.set(Number.POSITIVE_INFINITY, total);
717
    groups.push({ label, buckets, ...(meanKnown ? { sum: weighted, count: total } : {}) });
718
  }
719
  if (groups.length === 0) throw new InputError("None of these series has a point with a distribution in it.", "values");
720
  return { groups, src: { ...GCP, unit: [...units][0]! } };
721
}
722

723
/**
724
 * The Prometheus query API's JSON, which Amazon Managed Service for Prometheus and Azure Monitor's managed Prometheus
725
 * return as well: an instant query over the buckets, one sample per series, each with its le label.
726
 */
727
function prometheusJson(json: Obj): { groups: Histogram[]; src: HistSource } {
728
  const data = isObj(json.data) ? json.data : {};
729
  if (json.status === "error") throw new InputError(`The query failed: ${String(json.error ?? "no reason given").slice(0, 200)}`, "values");
730
  const result = arr(data.result).filter(isObj);
731
  if (data.resultType === "matrix") {
732
    throw new InputError(
733
      "This is a range query, a sample per step for each series. Run it as an instant query over the window instead, such as sum by (instance, le) (increase(your_metric_bucket[1h])), so each bucket has one count.",
734
      "values",
735
    );
736
  }
737
  if (result.some((r) => r.histogram !== undefined)) {
738
    throw new InputError("These are native histograms, Prometheus's newer sparse kind, which this tool does not read. Query a classic histogram's _bucket series instead.", "values");
739
  }
740
  if (result.length === 0) throw new InputError("This query returned no series. Check the metric name and the time.", "values");
741
  const metrics = result.map((r) => (isObj(r.metric) ? r.metric : {}));
742
  if (metrics.every((m) => m.le === undefined)) {
743
    throw precomputed(
744
      "These series have no le label, so each is one number rather than a bucket. A histogram_quantile() query returns this.",
745
      "Query the buckets themselves, such as sum by (instance, le) (increase(your_metric_bucket[1h])), and paste that.",
746
    );
747
  }
748
  const names = new Set(metrics.map((m) => String(m.__name__ ?? "")).filter(Boolean));
749
  if (names.size > 1) throw new InputError(`This result holds ${[...names].join(" and ")}. Query one histogram at a time.`, "values");
750
  const metric = [...names][0]?.replace(/_bucket$/, "") ?? "";
751
  const groups = new Map<string, Histogram>();
752
  for (const [i, r] of result.entries()) {
753
    const m = metrics[i]!;
754
    if (m.le === undefined) continue;
755
    const others = Object.entries(m)
756
      .filter(([k]) => k !== "le" && k !== "__name__")
757
      .map(([, v]) => String(v))
758
      .join(" / ");
759
    const label = String(m.instance ?? (others || "all instances")).slice(0, 40);
760
    let g = groups.get(label);
761
    if (!g) {
762
      g = { label, buckets: new Map() };
763
      groups.set(label, g);
764
    }
765
    const edge = edgeOf(String(m.le), 0);
766
    g.buckets.set(edge, (g.buckets.get(edge) ?? 0) + countOf(String(arr(r.value)[1] ?? "")));
767
  }
768
  return { groups: [...groups.values()], src: prometheusSource(metric) };
769
}
770

771
// ── Bucket and count rows from a log query ───────────────────────────────────────────────────────────────────────
772

773
/** A CSV line into cells, honouring quotes, so `"pct(@duration, 99)"` is one cell. Tabs separate as well as commas. */
774
function splitCsv(line: string): string[] {
775
  const cells: string[] = [];
776
  let cell = "";
777
  let quoted = false;
778
  for (let i = 0; i < line.length; i++) {
779
    const ch = line[i]!;
780
    if (quoted) {
781
      if (ch === '"' && line[i + 1] === '"') {
782
        cell += '"';
783
        i++;
784
      } else if (ch === '"') quoted = false;
785
      else cell += ch;
786
    } else if (ch === '"') quoted = true;
787
    else if (ch === "," || ch === "\t") {
788
      cells.push(cell.trim());
789
      cell = "";
790
    } else cell += ch;
791
  }
792
  cells.push(cell.trim());
793
  return cells;
794
}
795

796
const isNumeric = (s: string) => s.trim() !== "" && Number.isFinite(Number(s));
797
/** KQL's count() is count_, sum(ItemCount) is sum_ItemCount; Logs Insights' count(*) keeps its spelling unless aliased. */
798
const COUNT_COLUMN = /^(count_?|count\(\*?\)|requests|sum_itemcount|itemcount|frequency)$/i;
799
/** percentile_DurationMs_99, percentiles_duration_99, pct(@duration, 99), p99: a percentile already worked out. */
800
const PERCENTILE_COLUMN = /^(percentiles?_|percentile\s*\(|pct\s*\()|^p\d+(\.\d+)?$/i;
801

802
type Table = { header: string[]; rows: { cells: string[]; at: number }[]; source: "kql" | "insights" | "csv" };
803

804
/** A CSV whose first line names its columns, one of them a count or a percentile and none of them le: a log query's result. */
805
function binTable(text: string): Table | undefined {
806
  let offset = 0;
807
  let header: string[] | undefined;
808
  const rows: Table["rows"] = [];
809
  for (const line of text.split("\n")) {
810
    const at = offset;
811
    offset += line.length + 1;
812
    const trimmed = line.trim();
813
    if (trimmed === "" || trimmed.startsWith("#")) continue;
814
    const cells = splitCsv(trimmed);
815
    if (!header) {
816
      if (cells.length < 2 || cells.some((c) => c === "" || isNumeric(c))) return undefined;
817
      if (!cells.some((c) => COUNT_COLUMN.test(c) || PERCENTILE_COLUMN.test(c))) return undefined;
818
      header = cells;
819
      continue;
820
    }
821
    rows.push({ cells, at: at + (line.length - line.trimStart().length) });
822
  }
823
  if (!header) return undefined;
824
  // The column names say which query language wrote the table, which only changes the advice on how to pool.
825
  const source = header.some((h) => /^(count_|sum_itemcount|durationms|approleinstance|cloud_roleinstance)$/i.test(h))
826
    ? "kql"
827
    : header.some((h) => /^count\(\*?\)$|^@/.test(h))
828
      ? "insights"
829
      : "csv";
830
  return { header, rows, source };
831
}
832

833
/** Log Analytics' {"tables": [{columns, rows}]}, and Logs Insights' {"results": [[{field, value}]]}, as one table. */
834
function jsonTable(json: Obj): Table | undefined {
835
  const tables = arr(json.tables).filter(isObj);
836
  if (tables.length > 0) {
837
    const t = tables[0]!;
838
    const header = arr(t.columns).map((c) => (isObj(c) ? String(c.name ?? "") : String(c)));
839
    const rows = arr(t.rows).map((r) => ({ cells: arr(r).map((v) => (v === null ? "" : String(v))), at: 0 }));
840
    return { header, rows, source: "kql" };
841
  }
842
  if (Array.isArray(json.results) && json.results.every(Array.isArray)) {
843
    if (json.status !== undefined && json.status !== "Complete") {
844
      throw new InputError(`This Logs Insights query is ${String(json.status)}, not Complete, so its counts may be partial. Wait for it to finish, then paste the results again.`, "values");
845
    }
846
    const header: string[] = [];
847
    const records = json.results.map((r) => {
848
      const fields = new Map<string, string>();
849
      for (const f of arr(r).filter(isObj)) {
850
        const name = String(f.field ?? "");
851
        if (name === "@ptr") continue;
852
        if (!header.includes(name)) header.push(name);
853
        fields.set(name, String(f.value ?? ""));
854
      }
855
      return fields;
856
    });
857
    return { header, rows: records.map((f) => ({ cells: header.map((h) => f.get(h) ?? ""), at: 0 })), source: "insights" };
858
  }
859
  return undefined;
860
}
861

862
/** The unit a bin column's name gives away: DurationMs and Lambda's @duration are milliseconds. Otherwise none. */
863
function binUnit(column: string): Unit {
864
  if (/^@?duration$/i.test(column) || /(ms|millis|milliseconds)$/i.test(column)) return "ms";
865
  if (/(_us|micros|microseconds)$/i.test(column)) return "us";
866
  if (/(_s|_sec|seconds)$/i.test(column)) return "s";
867
  return "";
868
}
869

870
const BIN_POOL: Record<Table["source"], (q: number, name: string) => string> = {
871
  kql: (_q, name) => `Take the ${name} over every request at once, as this tool does with the bins. In KQL that is one percentile() with no split by instance, never an average of per-instance results.`,
872
  insights: (_q, name) => `Take the ${name} over every request at once, as this tool does with the bins. In Logs Insights that is one pct() with no by clause, never an average of per-group results.`,
873
  csv: (_q, name) => `Take the ${name} over every request at once, as this tool does with the bins, never an average of per-instance results.`,
874
};
875

876
/**
877
 * Bucket and count rows into histograms: a duration rounded down to a bin, as KQL's bin() and Logs Insights' floor()
878
 * produce, and how many requests fell in it.
879
 *
880
 * The bin width is not in the result, so it is read from the spacing: the smallest gap between two bin values, which
881
 * every bin must sit a whole number of widths from. A bin from b covers b up to b + width, so both are edges, and a
882
 * bin with no row is simply empty. Every group gets the same edges, which is what lets the counts be added edge by edge.
883
 */
884
function binHistograms(table: Table): { groups: Histogram[]; src: HistSource } {
885
  const { header, rows } = table;
886
  const numeric = header.map((_, i) => rows.length > 0 && rows.every((r) => isNumeric(r.cells[i] ?? "")));
887
  const countAt = header.findIndex((h) => COUNT_COLUMN.test(h));
888
  const percentileCols = header.filter((h) => PERCENTILE_COLUMN.test(h));
889
  const candidates = header.map((h, i) => ({ h, i })).filter(({ h, i }) => numeric[i] && i !== countAt && !PERCENTILE_COLUMN.test(h));
890
  if (countAt < 0 || candidates.length === 0) {
891
    if (percentileCols.length > 0) {
892
      throw precomputed(
893
        `${percentileCols[0]} is a percentile worked out for each row.`,
894
        "Run the query again counting requests in duration bins instead, such as AppRequests | summarize requests = sum(ItemCount) by AppRoleInstance, bin(DurationMs, 10) in KQL, and paste that.",
895
      );
896
    }
897
    if (countAt < 0) throw new InputError(`A table of bins needs a count column, named count_, count(*), requests or sum_ItemCount. This one has ${header.join(", ")}.`, "values");
898
    throw new InputError("This table has a count column but no numeric column of bin values beside it, so there is no duration to place the counts at.", "values");
899
  }
900
  let bin = candidates[0]!;
901
  if (candidates.length > 1) {
902
    const named = candidates.filter(({ h }) => /bin|bucket|duration|latency|elapsed|response|time/i.test(h));
903
    if (named.length !== 1) {
904
      throw new InputError(`Which column is the bin? ${candidates.map(({ h }) => h).join(" and ")} are all numbers. Keep one bin column, the count, and any instance column.`, "values");
905
    }
906
    bin = named[0]!;
907
  }
908
  const labelCols = header.map((_, i) => i).filter((i) => i !== countAt && i !== bin.i && !numeric[i] && !PERCENTILE_COLUMN.test(header[i]!));
909

910
  const parsed: { label: string; lower: number; n: number }[] = [];
911
  for (const r of rows) {
912
    const at = r.at > 0 ? r.at : undefined;
913
    if (r.cells.length !== header.length) {
914
      throw new InputError(`This row has ${r.cells.length} cells, and the header names ${header.length} columns.`, "values", at, at === undefined ? undefined : 1);
915
    }
916
    const lower = Number(r.cells[bin.i]);
917
    if (lower < 0) throw new InputError(`A bin starts at ${r.cells[bin.i]}, and a duration can't be negative.`, "values", at, at === undefined ? undefined : 1);
918
    const label = (labelCols.map((i) => r.cells[i]!).filter(Boolean).join(" / ") || "all requests").slice(0, 40);
919
    parsed.push({ label, lower, n: countOf(r.cells[countAt]!) });
920
  }
921
  if (parsed.length === 0) throw new InputError("The table has a header and no rows.", "values");
922
  const lowers = [...new Set(parsed.map((p) => p.lower))].sort((a, b) => a - b);
923
  if (lowers.length < 2) throw new InputError("Every row is in the same bin, so the bin width can't be read from the spacing. Use a narrower bin.", "values");
924
  if (lowers.length > 1000) throw new InputError(`There are ${count(lowers.length)} bins, more than this tool lays out. Use a wider bin, so there are 1,000 or fewer.`, "values");
925
  const width = clean(Math.min(...lowers.slice(1).map((v, i) => v - lowers[i]!)));
926
  const base = lowers[0]!;
927
  const misplaced = lowers.find((v) => Math.abs((v - base) / width - Math.round((v - base) / width)) > 1e-6);
928
  if (misplaced !== undefined) {
929
    throw new InputError(
930
      `The bins are not evenly spaced: ${num(misplaced)} is not a whole number of ${num(width)}-wide bins from ${num(base)}. Use one bin() size for every row.`,
931
      "values",
932
    );
933
  }
934
  const edges = [...new Set(lowers.flatMap((v) => [clean(v), clean(v + width)]))].filter((e) => e > 0).sort((a, b) => a - b);
935

936
  const byLabel = new Map<string, Map<number, number>>();
937
  for (const p of parsed) {
938
    const g = byLabel.get(p.label) ?? new Map<number, number>();
939
    const upper = clean(p.lower + width);
940
    g.set(upper, (g.get(upper) ?? 0) + p.n);
941
    byLabel.set(p.label, g);
942
  }
943
  const groups: Histogram[] = [...byLabel.entries()].map(([label, perBin]) => {
944
    const buckets = new Map<number, number>();
945
    let running = 0;
946
    for (const e of edges) {
947
      running += perBin.get(e) ?? 0;
948
      buckets.set(e, running);
949
    }
950
    buckets.set(Number.POSITIVE_INFINITY, running);
951
    return { label, buckets };
952
  });
953
  const unit = binUnit(bin.h);
954
  return {
955
    groups,
956
    src: {
957
      noun: labelCols.length > 0 ? INSTANCE : GROUP,
958
      unit,
959
      inclusive: false,
960
      edgeColumn: "Bin upper edge",
961
      estimate: (name, lower, upper) =>
962
        `Estimated from the summed bins, ${dur(width, unit)} wide, interpolating inside a bin as Prometheus's histogram_quantile does, so the true ${name} is somewhere between ${lower} and ${upper}.`,
963
      overflow: (highest) => `It is above ${highest}, the top of the highest bin.`,
964
      pool: BIN_POOL[table.source],
965
      method: "Add the bins, then estimate",
966
      meanNote: "",
967
      bucketWord: "edges",
968
      addAbove: (highest) => `Count the requests above ${highest} too`,
969
      addBetween: () => `Use a narrower bin than ${dur(width, unit)}`,
970
      addAt: (threshold) => `Choose a bin size that puts an edge at ${threshold}`,
971
    },
972
  };
973
}
974

975
// ── Raw latencies, and X-Ray's value and count pairs ─────────────────────────────────────────────────────────────
976

977
/** A group of measurements as distinct values in order, each with how many times it occurred. Raw latencies count 1 each. */
978
type Weighted = { label: string; values: number[]; counts: number[]; n: number };
979

980
function weigh(label: string, pairs: [number, number][]): Weighted {
981
  const merged = new Map<number, number>();
982
  for (const [v, c] of pairs) if (c > 0) merged.set(v, (merged.get(v) ?? 0) + c);
983
  const values = [...merged.keys()].sort((a, b) => a - b);
984
  const counts = values.map((v) => merged.get(v)!);
985
  return { label, values, counts, n: sum(counts) };
986
}
987

988
/** The value at a 0-based rank, as if every value were written out as many times as it occurred. */
989
function atRank(g: Weighted, k: number): number {
990
  let seen = 0;
991
  for (let i = 0; i < g.values.length; i++) {
992
    seen += g.counts[i]!;
993
    if (seen > k) return g.values[i]!;
994
  }
995
  return g.values.at(-1)!;
996
}
997

998
/** Nearest rank: the smallest value with at least p% of the measurements at or below it. */
999
function nearest(g: Weighted, p: number): number {
1000
  return atRank(g, Math.max(0, Math.ceil((p / 100) * g.n) - 1));
1001
}
1002

1003
/** Linear interpolation between closest ranks, numpy's default. */
1004
function linear(g: Weighted, p: number): number {
1005
  const h = (g.n - 1) * (p / 100);
1006
  const lo = Math.floor(h);
1007
  const hi = Math.min(lo + 1, g.n - 1);
1008
  const a = atRank(g, lo);
1009
  return a + (h - lo) * (atRank(g, hi) - a);
1010
}
1011

1012
/** Where a set of value groups came from: the words around the numbers, never the arithmetic. */
1013
type RawSource = { noun: Noun; unit: Unit; things: string; perWhat: string; single: string; pool: (truth: string, averaged: string) => string };
1014

1015
const RAW: RawSource = {
1016
  noun: GROUP,
1017
  unit: "",
1018
  things: "measurements",
1019
  perWhat: "per-host",
1020
  single: "One group, so there is nothing to roll up: paste two or more, one per host or per minute, separated by a blank line.",
1021
  pool: (truth, averaged) =>
1022
    `The average is ${averaged} against ${truth} for every measurement together. Pool the measurements, or record a histogram with the same bucket edges on every host and sum it.`,
1023
};
1024

1025
function xraySource(noun: Noun): RawSource {
1026
  return {
1027
    noun,
1028
    unit: "s",
1029
    things: "requests",
1030
    perWhat: `per-${noun.one}`,
1031
    single: "One histogram, so there is nothing to roll up. GetTimeSeriesServiceStatistics with a Period of 60 returns one per minute, the figures a dashboard averages.",
1032
    pool: (truth, averaged) =>
1033
      `The average is ${averaged} against ${truth} for every request together. Add the histograms up, as this tool does, or ask X-Ray for one histogram covering the whole window, and take the percentile of that.`,
1034
  };
1035
}
1036

1037
/** X-Ray's HistogramEntry list: a response time in seconds, and the number of requests that took it. */
1038
function xrayEntries(list: Json | undefined, label: string): Weighted {
1039
  const pairs: [number, number][] = [];
1040
  for (const e of arr(list)) {
1041
    if (!isObj(e)) continue;
1042
    const v = numberOf(e.Value);
1043
    const c = numberOf(e.Count);
1044
    if (!Number.isFinite(v) || v < 0) throw new InputError(`${label} has a histogram Value of ${String(e.Value)}, and a response time is a number of seconds, 0 or more.`, "values");
1045
    if (!Number.isFinite(c) || c < 0) throw new InputError(`${label} has a histogram Count of ${String(e.Count)}, and a count is a number of requests, 0 or more.`, "values");
1046
    pairs.push([v, c]);
1047
  }
1048
  return weigh(label, pairs);
1049
}
1050

1051
/** An X-Ray timestamp, epoch seconds from the API or ISO 8601 from the AWS CLI, as the minute it starts, in UTC. */
1052
function minuteOf(t: Json | undefined): string {
1053
  const ms = typeof t === "number" ? t * 1000 : typeof t === "string" ? Date.parse(t) : Number.NaN;
1054
  if (!Number.isFinite(ms)) return "";
1055
  return new Date(ms).toISOString().slice(11, 16);
1056
}
1057

1058
/**
1059
 * GetTimeSeriesServiceStatistics (a histogram per period), GetServiceGraph (a histogram per service), or one bare
1060
 * HistogramEntry list. The client node of a service graph stands for the callers, not a service, so it is left out.
1061
 */
1062
function xrayGroups(json: Json): { groups: Weighted[]; src: RawSource } | undefined {
1063
  const isEntryList = (v: Json | undefined) => Array.isArray(v) && v.length > 0 && v.every((e) => isObj(e) && "Value" in e && "Count" in e);
1064
  if (isObj(json) && Array.isArray(json.TimeSeriesServiceStatistics)) {
1065
    const stats = json.TimeSeriesServiceStatistics.filter(isObj);
1066
    const labels = stats.map((s) => minuteOf(s.Timestamp));
1067
    const clash = new Set(labels).size !== labels.length || labels.some((l) => l === "");
1068
    const groups = stats.map((s, i) => xrayEntries(s.ResponseTimeHistogram, clash ? `period ${i + 1}` : `${labels[i]} UTC`)).filter((g) => g.n > 0);
1069
    if (groups.length === 0) throw new InputError("None of these periods has a response-time histogram with requests in it.", "values");
1070
    return { groups, src: xraySource(PERIOD) };
1071
  }
1072
  if (isObj(json) && Array.isArray(json.Services)) {
1073
    const services = json.Services.filter(isObj).filter((s) => s.Type !== "client");
1074
    const groups = services.map((s, i) => xrayEntries(s.ResponseTimeHistogram, String(s.Name ?? `service ${i + 1}`).slice(0, 40))).filter((g) => g.n > 0);
1075
    if (groups.length === 0) throw new InputError("None of these services has a response-time histogram with requests in it.", "values");
1076
    return { groups, src: xraySource(SERVICE) };
1077
  }
1078
  if (isEntryList(json)) return { groups: [xrayEntries(json, "histogram")], src: xraySource(GROUP) };
1079
  if (isObj(json) && isEntryList(json.ResponseTimeHistogram)) {
1080
    return { groups: [xrayEntries(json.ResponseTimeHistogram, String(json.Name ?? "histogram").slice(0, 40))], src: xraySource(GROUP) };
1081
  }
1082
  return undefined;
1083
}
1084

1085
/**
1086
 * Groups separated by one or more blank lines, each optionally starting with a label and a colon: `host 1: 12 14`.
1087
 *
1088
 * ⚠️ A comma between two digits is refused rather than guessed at, the same rule as the Percentiles tool in
1089
 * toolbench, for the same reason: `1,204` is one number to someone pasting from a dashboard and two to someone
1090
 * pasting a list, and a confident wrong percentile is worse than an error. A comma followed by a space separates.
1091
 */
1092
function parse(text: string): Weighted[] {
1093
  const groups: Weighted[] = [];
1094
  const blocks = [...text.matchAll(/[^\n]*\S[^\n]*(?:\n[^\n]*\S[^\n]*)*/g)];
1095
  const lines = text.split("\n").filter((l) => l.trim() !== "");
1096
  const allPairs = lines.length > 0 && lines.every((l) => /^\s*[\d.]+,[\d.]+\s*$/.test(l));
1097
  for (const block of blocks) {
1098
    let body = block[0];
1099
    let offset = block.index ?? 0;
1100
    let label = `group ${groups.length + 1}`;
1101
    const head = /^\s*([^\n:]*[^\s\d.,;:\n][^\n:]*):/.exec(body);
1102
    if (head) {
1103
      label = head[1]!.trim().slice(0, 40);
1104
      offset += head[0].length;
1105
      body = body.slice(head[0].length);
1106
    }
1107
    const values: [number, number][] = [];
1108
    for (const token of body.matchAll(/[^\s;]+/g)) {
1109
      const raw = token[0];
1110
      const at = offset + (token.index ?? 0);
1111
      const comma = /\d,\d/.exec(raw);
1112
      if (comma) {
1113
        throw new InputError(
1114
          allPairs
1115
            ? "These look like bucket edges and counts. Add a header line, le,count, so they are read as a histogram."
1116
            : "A comma between two digits could be a thousands separator or two numbers run together. Write 1204, or put a space after each comma.",
1117
          "values",
1118
          at + comma.index + 1,
1119
          1,
1120
        );
1121
      }
1122
      for (const part of raw.split(",")) {
1123
        if (part === "") continue;
1124
        const v = Number(part);
1125
        if (/^-\d/.test(part)) {
1126
          throw new InputError(`${part.slice(0, 20)} is negative, and a duration can't be.`, "values", at + raw.indexOf(part), part.length);
1127
        }
1128
        if (!/^[+]?(\d+\.?\d*|\.\d+)(e[+-]?\d+)?$/i.test(part) || !Number.isFinite(v)) {
1129
          throw new InputError(`"${part.slice(0, 20)}" is not a number.`, "values", at + raw.indexOf(part), part.length);
1130
        }
1131
        values.push([v, 1]);
1132
      }
1133
    }
1134
    if (values.length > 0) groups.push(weigh(label, values));
1135
  }
1136
  return groups;
1137
}
1138

1139
function rawRollup(groups: Weighted[], src: RawSource, name: string, p: number, threshold: number): Output {
1140
  if (groups.length === 0) throw new InputError("Paste some measurements first, or Prometheus bucket lines.", "values");
1141
  const { noun } = src;
1142
  const d = (v: number) => dur(v, src.unit);
1143
  const pooled = weigh(
1144
    "all",
1145
    groups.flatMap((g) => g.values.map((v, i): [number, number] => [v, g.counts[i]!])),
1146
  );
1147
  const n = pooled.n;
1148

1149
  const truth = nearest(pooled, p);
1150
  const each = groups.map((g) => nearest(g, p));
1151
  const averaged = sum(each) / each.length;
1152
  const below = (g: Weighted) => sum(g.values.map((v, i) => (v < threshold ? g.counts[i]! : 0)));
1153
  const under = groups.map(below);
1154
  const good = sum(under);
1155
  const total = (g: Weighted) => sum(g.values.map((v, i) => v * g.counts[i]!));
1156
  const mean = total(pooled) / n;
1157
  const plainMean = sum(groups.map((g) => total(g) / g.n)) / groups.length;
1158
  const r = groups.length > 1 && truth > 0 ? ratioNote(averaged / truth) : undefined;
1159

1160
  // Every value is known, so the pooled row is exact and needs no range beside it.
1161
  const parts: Output[] = [
1162
    {
1163
      kind: "table",
1164
      role: "comparison",
1165
      caption: `${name} across ${across(groups.length, noun)}`,
1166
      columns: [
1167
        { label: "Method", wrap: "prose" },
1168
        { label: name, align: "end", mono: true, wrap: "none" },
1169
        { label: "What you can claim", wrap: "prose" },
1170
      ],
1171
      rows: [
1172
        [`Every ${src.things === "requests" ? "request" : "measurement"}, ranked`, { text: d(truth), mono: true }, `exact: nearest rank of ${count(n)}`],
1173
        ...(groups.length > 1 ? [[`Average of the ${poss(noun.many)} ${name}s`, { text: d(averaged), mono: true }, r ? r.text : "the true value is 0"] as Cell[]] : []),
1174
      ],
1175
    },
1176
  ];
1177

1178
  // The share slower than each observed value, as a step: between two observed values nothing was measured, so it holds.
1179
  const plot = (v: number) => plotValue(v, src.unit);
1180
  const steps = pooled.values.map((v, i) => [v, i] as const).filter(([v]) => v > 0);
1181
  if (steps.length >= 2 && steps.length <= 400) {
1182
    let seen = 0;
1183
    const slower = pooled.counts.map((c) => {
1184
      seen += c;
1185
      return Number((100 * (1 - seen / n)).toPrecision(4));
1186
    });
1187
    const tail = 100 - p;
1188
    parts.push({
1189
      kind: "series",
1190
      chart: {
1191
        xLabel: capital(src.things === "requests" ? "response time" : "measurement"),
1192
        ...(src.unit === "" ? {} : { xUnit: "ms" }),
1193
        yLabel: "Share slower",
1194
        yUnit: "%",
1195
        xScale: "log",
1196
        yScale: "log",
1197
        x: steps.map(([v]) => plot(v)),
1198
        series: [{ label: `${capital(src.things)} slower than each value`, shape: "step", unit: "%", points: steps.map(([, i]) => slower[i]!) }],
1199
        thresholds: [{ y: Number(tail.toPrecision(4)), label: `${num(tail)}% slower: the ${name}` }],
1200
        annotations: [{ x: plot(truth), label: `${name}, ${d(truth)}` }],
1201
      },
1202
    });
1203
  }
1204

1205
  parts.push({
1206
    kind: "fields",
1207
    role: "metrics",
1208
    fields: [
1209
      {
1210
        label: `Under ${d(threshold)}`,
1211
        value: pct(good / n),
1212
        note: `exact: ${count(good)} of ${count(n)}`,
1213
      },
1214
      {
1215
        label: "Mean",
1216
        value: d(mean),
1217
        note: groups.length > 1 ? `weighted by count; the plain average of the ${noun.one} means is ${d(plainMean)}` : "for capacity, not for describing a request",
1218
      },
1219
      { label: capital(src.things), value: count(n), note: `${groups.length} ${groups.length === 1 ? noun.one : noun.many}` },
1220
    ],
1221
  });
1222
  if (r?.off) {
1223
    parts.push({
1224
      kind: "table",
1225
      role: "actions",
1226
      caption: "What to change",
1227
      columns: [{ label: "What to do" }, { label: "Why" }],
1228
      rows: [[{ text: `Stop averaging ${src.perWhat} ${name}s`, tone: "warn" }, src.pool(d(truth), d(averaged))]],
1229
    });
1230
  }
1231

1232
  const order = groups.map((_, i) => i).sort((a, b) => each[b]! - each[a]!);
1233
  parts.push({
1234
    kind: "table",
1235
    caption: `Each ${noun.one} on its own, slowest first, nearest rank`,
1236
    columns: [
1237
      { label: capital(noun.one), wrap: "none", rowHeader: true },
1238
      { label: "Count", align: "end", mono: true, wrap: "none" },
1239
      { label: "Mean", align: "end", mono: true, wrap: "none" },
1240
      { label: "p50", align: "end", mono: true, wrap: "none" },
1241
      { label: name, align: "end", mono: true, wrap: "none" },
1242
      { label: `Under ${d(threshold)}`, align: "end", mono: true, wrap: "none" },
1243
    ],
1244
    rows: order.map((i) => {
1245
      const g = groups[i]!;
1246
      return [
1247
        g.label,
1248
        { text: count(g.n), mono: true },
1249
        { text: d(total(g) / g.n), mono: true },
1250
        { text: d(nearest(g, 50)), mono: true },
1251
        { text: d(each[i]!), mono: true },
1252
        { text: pct(under[i]! / g.n), mono: true },
1253
      ];
1254
    }),
1255
  });
1256
  parts.push({
1257
    kind: "table",
1258
    caption: `Every ${src.things === "requests" ? "request" : "measurement"} together, under both definitions. On a small or lumpy sample they disagree.`,
1259
    columns: [
1260
      { label: "Percentile", wrap: "none", rowHeader: true },
1261
      { label: "Nearest rank", align: "end", mono: true, wrap: "none" },
1262
      { label: "Linear, as numpy and R", align: "end", mono: true, wrap: "none" },
1263
    ],
1264
    rows: Object.entries(PERCENTILES).map(([label, q]) => [label, { text: d(nearest(pooled, q)), mono: true }, { text: d(linear(pooled, q)), mono: true }]),
1265
  });
1266
  if (groups.length === 1) parts.push({ kind: "fields", role: "method", fields: [{ label: "One group", value: src.single, mono: false }] });
1267
  return { kind: "group", parts };
1268
}
1269

1270
// ── Reading what was pasted ──────────────────────────────────────────────────────────────────────────────────────
1271

1272
/** Exports that carry statistics rather than a distribution, each refused with where to find the histogram instead. */
1273
function refuseStatistics(json: Json): void {
1274
  if (!isObj(json)) return;
1275
  if (Array.isArray(json.MetricDataResults) || Array.isArray(json.Datapoints)) {
1276
    throw precomputed(
1277
      "This is CloudWatch metric data: one statistic per period, such as p99 or Average, and never the distribution behind it.",
1278
      "Ask CloudWatch for the p99 over the whole window and every dimension at once, so it is computed from the raw data, or count requests under your threshold with the PR(:0.1) or TC(:0.1) statistic. For a histogram, count requests per duration bin in CloudWatch Logs Insights, or use X-Ray's response-time histogram, and paste that.",
1279
    );
1280
  }
1281
  if (arr(json.value).some((m) => isObj(m) && Array.isArray(m.timeseries))) {
1282
    throw precomputed(
1283
      "This is Azure Monitor metrics data, which keeps only a sum, a count, a minimum, a maximum and an average per interval.",
1284
      "For a histogram, query the requests in Log Analytics instead, such as AppRequests | summarize requests = sum(ItemCount) by AppRoleInstance, bin(DurationMs, 10), and paste the result.",
1285
    );
1286
  }
1287
}
1288

1289
function fromJson(text: string, name: string, q: number, threshold: number): Output {
1290
  let json: Json;
1291
  try {
1292
    json = JSON.parse(text) as Json;
1293
  } catch (error) {
1294
    const reason = error instanceof Error ? error.message : "";
1295
    throw new InputError(`This starts like JSON but does not parse${reason ? `: ${reason.slice(0, 120)}` : ""}. Paste the whole response, from its first brace to its last.`, "values");
1296
  }
1297
  refuseStatistics(json);
1298
  if (isObj(json) && isObj(json.data) && "result" in json.data) {
1299
    const { groups, src } = prometheusJson(json);
1300
    return histogramRollup(groups, src, name, q, threshold);
1301
  }
1302
  const gcp = gcpHistograms(json);
1303
  if (gcp) return histogramRollup(gcp.groups, gcp.src, name, q, threshold);
1304
  const xray = xrayGroups(json);
1305
  if (xray) return rawRollup(xray.groups, xray.src, name, q * 100, threshold);
1306
  const table = isObj(json) ? jsonTable(json) : undefined;
1307
  if (table) {
1308
    const { groups, src } = binHistograms(table);
1309
    return histogramRollup(groups, src, name, q, threshold);
1310
  }
1311
  throw new InputError(
1312
    "This JSON is not a format this tool reads. It reads Cloud Monitoring's timeSeries.list, X-Ray's GetServiceGraph and GetTimeSeriesServiceStatistics, the Prometheus query API, and Log Analytics and CloudWatch Logs Insights query results.",
1313
    "values",
1314
  );
1315
}
1316

1317
export default {
1318
  run({ values, percentile, threshold }: Input) {
1319
    try {
1320
      const p = PERCENTILES[percentile];
1321
      if (p === undefined) throw new InputError("Pick one of the listed percentiles.", "percentile");
1322
      if (!(threshold > 0)) throw new InputError("The threshold must be greater than zero.", "threshold");
1323
      const q = p / 100;
1324
      const start = values.trimStart();
1325
      // A line such as {instance="a",le="0.1"} 12 starts with a brace too, and is Prometheus text, not JSON.
1326
      if ((start.startsWith("{") || start.startsWith("[")) && !/^\{[^}\n]*\ble\s*=\s*"[^"\n]*"[^}\n]*\}\s+\S/.test(start)) return fromJson(values, percentile, q, threshold);
1327
      if (looksLikeBuckets(values)) {
1328
        const { groups, metric } = parseBuckets(values);
1329
        return histogramRollup(groups, prometheusSource(metric), percentile, q, threshold);
1330
      }
1331
      const table = binTable(values);
1332
      if (table) {
1333
        const { groups, src } = binHistograms(table);
1334
        return histogramRollup(groups, src, percentile, q, threshold);
1335
      }
1336
      return rawRollup(parse(values), RAW, percentile, p, threshold);
1337
    } catch (error) {
1338
      if (error instanceof InputError) {
1339
        return {
1340
          kind: "error",
1341
          message: error.message,
1342
          input: error.input,
1343
          ...(error.at !== undefined ? { at: error.at } : {}),
1344
          ...(error.len !== undefined ? { len: error.len } : {}),
1345
        };
1346
      }
1347
      throw error;
1348
    }
1349
  },
1350
} satisfies Tool<Input>;