@intentius/chant-lexicon-terraform 0.124.87 → 0.124.89

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (82) hide show
  1. package/dist/action-ops.d.ts.map +1 -1
  2. package/dist/action-ops.js +3 -1
  3. package/dist/chant-floors.d.ts +30 -0
  4. package/dist/chant-floors.d.ts.map +1 -0
  5. package/dist/chant-floors.js +29 -0
  6. package/dist/components/capability-plugin.d.ts +15 -1
  7. package/dist/components/capability-plugin.d.ts.map +1 -1
  8. package/dist/components/capability-plugin.js +13 -5
  9. package/dist/components/compose-group.d.ts +5 -1
  10. package/dist/components/compose-group.d.ts.map +1 -1
  11. package/dist/components/compose-group.js +7 -4
  12. package/dist/engine-runner.d.ts +86 -0
  13. package/dist/engine-runner.d.ts.map +1 -0
  14. package/dist/engine-runner.js +134 -0
  15. package/dist/engine-timings.d.ts +249 -0
  16. package/dist/engine-timings.d.ts.map +1 -0
  17. package/dist/engine-timings.js +569 -0
  18. package/dist/integrity.json +2 -2
  19. package/dist/live-roots.d.ts +143 -0
  20. package/dist/live-roots.d.ts.map +1 -0
  21. package/dist/live-roots.js +304 -0
  22. package/dist/manifest.json +1 -1
  23. package/dist/migration-history.d.ts +105 -0
  24. package/dist/migration-history.d.ts.map +1 -0
  25. package/dist/migration-history.js +159 -0
  26. package/dist/module-catalog/index.d.ts +1 -0
  27. package/dist/module-catalog/index.d.ts.map +1 -1
  28. package/dist/module-catalog/index.js +3 -1
  29. package/dist/op/activities/live-detect.d.ts +15 -0
  30. package/dist/op/activities/live-detect.d.ts.map +1 -1
  31. package/dist/op/activities/live-detect.js +94 -0
  32. package/dist/op/activities/terraform.d.ts +1 -65
  33. package/dist/op/activities/terraform.d.ts.map +1 -1
  34. package/dist/op/activities/terraform.js +4 -54
  35. package/dist/op/command-hook.d.ts +98 -0
  36. package/dist/op/command-hook.d.ts.map +1 -0
  37. package/dist/op/command-hook.js +115 -0
  38. package/dist/registry/index.d.ts +1 -0
  39. package/dist/registry/index.d.ts.map +1 -1
  40. package/dist/registry/index.js +1 -0
  41. package/dist/state/exec.d.ts +23 -0
  42. package/dist/state/exec.d.ts.map +1 -1
  43. package/dist/state/exec.js +38 -0
  44. package/dist/state-ops.d.ts.map +1 -1
  45. package/dist/state-ops.js +3 -1
  46. package/dist/terragrunt/index.d.ts +3 -1
  47. package/dist/terragrunt/index.d.ts.map +1 -1
  48. package/dist/terragrunt/index.js +3 -1
  49. package/dist/terragrunt/place.d.ts +27 -0
  50. package/dist/terragrunt/place.d.ts.map +1 -0
  51. package/dist/terragrunt/place.js +52 -0
  52. package/dist/terragrunt/run.d.ts +23 -0
  53. package/dist/terragrunt/run.d.ts.map +1 -1
  54. package/dist/terragrunt/run.js +107 -3
  55. package/package.json +2 -2
  56. package/src/action-ops.ts +3 -1
  57. package/src/chant-floors.ts +32 -0
  58. package/src/components/capability-plugin.ts +27 -6
  59. package/src/components/compose-group.test.ts +29 -0
  60. package/src/components/compose-group.ts +12 -5
  61. package/src/components/terraform-apply-command-hook.test.ts +43 -0
  62. package/src/engine-runner.test.ts +261 -0
  63. package/src/engine-runner.ts +191 -0
  64. package/src/engine-timings.test.ts +203 -0
  65. package/src/engine-timings.ts +718 -0
  66. package/src/live-record-store.test.ts +76 -0
  67. package/src/live-roots.test.ts +80 -0
  68. package/src/live-roots.ts +347 -0
  69. package/src/migration-history.test.ts +83 -0
  70. package/src/migration-history.ts +199 -0
  71. package/src/module-catalog/index.ts +4 -1
  72. package/src/op/activities/live-detect.ts +87 -0
  73. package/src/op/activities/terraform.ts +12 -111
  74. package/src/op/command-hook.ts +189 -0
  75. package/src/registry/index.ts +1 -0
  76. package/src/state/engine-env.test.ts +18 -0
  77. package/src/state/exec.ts +38 -0
  78. package/src/state-ops.ts +3 -1
  79. package/src/terragrunt/index.ts +3 -1
  80. package/src/terragrunt/place.test.ts +42 -0
  81. package/src/terragrunt/place.ts +75 -0
  82. package/src/terragrunt/run.ts +128 -4
@@ -0,0 +1,718 @@
1
+ /**
2
+ * Per-root engine timings for `terraform-apply` (chant#4887): how long each
3
+ * root's init, plan and apply ran, and the engine's own spans, read into the
4
+ * slowest resources and provider calls, provider start-up and state lock
5
+ * waits, for a plain wave and a composed one.
6
+ *
7
+ * {@link engineTimings} gives a {@link TerraformCommandHook} to pass as
8
+ * `terraformApplyCapabilityWith({ onCommand })` (chant#4865). It listens on
9
+ * a loopback port for the run and points each command's OTLP trace exporter
10
+ * at it (`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`), with a header naming the
11
+ * root and the command the spans came from. OpenTofu and choudoufu export
12
+ * OTLP/HTTP protobuf, so the receiver decodes the few protobuf messages a
13
+ * trace export holds; OTLP/JSON is read too. A binary that sends no spans
14
+ * (Terraform) still gets each command timed. With `forward`, each batch also
15
+ * goes on unchanged to the product's own collector.
16
+ *
17
+ * A composed group's commands (`terraform.compose`) run once for all its
18
+ * members, so each member root gets the group's times and spans, and its
19
+ * timings name the members it ran with. The run's slowest resources count a
20
+ * group once.
21
+ *
22
+ * Lifted from terragucci's `report/spans.ts` (the decoder, `SpanReceiver`,
23
+ * `rootTimings`, `runTimings`, `duration`) and the timing half of
24
+ * `report/observe.ts` (`StageObserver.commandHook`, `addTimings`), so
25
+ * terragucci deletes its copy. No OpenTelemetry SDK and no protobuf library.
26
+ */
27
+ import { randomBytes } from "node:crypto";
28
+ import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
29
+ import { gunzipSync, inflateSync } from "node:zlib";
30
+ import type { TerraformCommand, TerraformCommandHook, TerraformCommandResult } from "./op/command-hook";
31
+
32
+ /** One resource instance's time, from its plan or apply span. */
33
+ export interface EngineResourceTiming {
34
+ address: string;
35
+ type?: string;
36
+ action?: string;
37
+ /** The provider instance it is planned with. */
38
+ provider?: string;
39
+ ms: number;
40
+ /** The part of it spent refreshing the resource. */
41
+ refresh_ms?: number;
42
+ }
43
+
44
+ /** One provider RPC's time. */
45
+ export interface EngineProviderCall {
46
+ /** The RPC method: `PlanResourceChange`, `ReadResource`, `GetProviderSchema`... */
47
+ method: string;
48
+ provider?: string;
49
+ type?: string;
50
+ /** The resource instance it was made for, when it was made for one. */
51
+ address?: string;
52
+ ms: number;
53
+ }
54
+
55
+ /** A choudoufu aggregate span: resources or calls summed past its span budget. */
56
+ export interface EngineAggregate {
57
+ /** The name of the spans it stands for, such as `Plan resource instance changes`, or `other`. */
58
+ of: string;
59
+ /** `resource_instance` or `provider_call`. */
60
+ kind?: string;
61
+ type?: string;
62
+ provider?: string;
63
+ method?: string;
64
+ count: number;
65
+ /** How many of them also have a span of their own. */
66
+ detailed: number;
67
+ /** Their total time. */
68
+ ms: number;
69
+ max_ms: number;
70
+ /** The slowest member: an address, or a resource type. */
71
+ slowest?: string;
72
+ /** For `other`: how many groups it folds. */
73
+ groups?: number;
74
+ }
75
+
76
+ /** A wait for a state lock, from the engine's `State lock wait` span. */
77
+ export interface EngineLockWait {
78
+ backend?: string;
79
+ operation?: string;
80
+ attempts?: number;
81
+ ms: number;
82
+ }
83
+
84
+ /** One root's timings. The field names are the ones terragucci's report has written since its schema's minor 3. */
85
+ export interface EngineRootTimings {
86
+ /** The root's engine commands together: init, plan and show, and on an apply the apply and output. */
87
+ seconds: number;
88
+ /** The engine's plan runs alone. Absent when the root never reached one. */
89
+ plan_seconds?: number;
90
+ /** The engine's apply runs alone. Absent when the root was not applied. */
91
+ apply_seconds?: number;
92
+ /**
93
+ * Where the times come from: `binary`, each run of the binary was timed;
94
+ * `terragrunt`, Terragrunt ran the binary and its run report gives the
95
+ * unit's times. Absent means `binary`.
96
+ */
97
+ source?: "binary" | "terragrunt";
98
+ /** How many spans the binary sent for the commands counted. */
99
+ spans: number;
100
+ /** `resources`: a span per resource instance; `aggregate`: summed by type only; `none`: nothing per resource. */
101
+ detail: "resources" | "aggregate" | "none";
102
+ /** Why the lists are empty or partial. */
103
+ note?: string;
104
+ /** The slowest resource instances, slowest first. */
105
+ resources: EngineResourceTiming[];
106
+ provider_calls: EngineProviderCall[];
107
+ /** Provider start-up, by provider. */
108
+ provider_init: { provider: string; count: number; ms: number; max_ms: number }[];
109
+ /** Waits for a state lock. */
110
+ lock_waits: EngineLockWait[];
111
+ aggregates: EngineAggregate[];
112
+ }
113
+
114
+ /** A run's slowest roots and resources. */
115
+ export interface EngineRunTimings {
116
+ /** Every timed root, slowest first. */
117
+ roots: { root: string; seconds: number; plan_seconds?: number; apply_seconds?: number; source?: EngineRootTimings["source"]; detail: EngineRootTimings["detail"] }[];
118
+ /** The slowest resource instances across the run. */
119
+ resources: { root: string; address: string; type?: string; ms: number }[];
120
+ /** Why the run has no per-root timings, when it has none. */
121
+ note?: string;
122
+ }
123
+
124
+ export type SpanValue = string | number | boolean;
125
+
126
+ /** One span as the binary sent it, with only what the report reads. */
127
+ export interface CollectedSpan {
128
+ spanId: string;
129
+ parentSpanId?: string;
130
+ name: string;
131
+ start: bigint;
132
+ end: bigint;
133
+ attributes: Record<string, SpanValue>;
134
+ error?: boolean;
135
+ }
136
+
137
+ // OTLP protobuf
138
+
139
+ interface Field {
140
+ no: number;
141
+ wire: number;
142
+ int?: bigint;
143
+ bytes?: Buffer;
144
+ }
145
+
146
+ /** The fields of one protobuf message. Throws on a truncated or malformed one. */
147
+ function* fields(buf: Buffer): Generator<Field> {
148
+ let pos = 0;
149
+ const varint = (): bigint => {
150
+ let out = 0n;
151
+ for (let shift = 0n; ; shift += 7n) {
152
+ if (pos >= buf.length) throw new Error("truncated varint");
153
+ const b = buf[pos++];
154
+ out |= BigInt(b & 0x7f) << shift;
155
+ if (b < 0x80) return out;
156
+ if (shift > 63n) throw new Error("varint too long");
157
+ }
158
+ };
159
+ const take = (n: number): Buffer => {
160
+ if (pos + n > buf.length) throw new Error("truncated field");
161
+ const b = buf.subarray(pos, pos + n);
162
+ pos += n;
163
+ return b;
164
+ };
165
+ while (pos < buf.length) {
166
+ const key = Number(varint());
167
+ const no = key >>> 3;
168
+ const wire = key & 7;
169
+ if (wire === 0) yield { no, wire, int: varint() };
170
+ else if (wire === 1) yield { no, wire, bytes: take(8) };
171
+ else if (wire === 2) yield { no, wire, bytes: take(Number(varint())) };
172
+ else if (wire === 5) yield { no, wire, bytes: take(4) };
173
+ else throw new Error(`unsupported wire type ${wire}`);
174
+ }
175
+ }
176
+
177
+ /** opentelemetry.proto.common.v1.AnyValue, scalars only. */
178
+ function anyValue(buf: Buffer): SpanValue | undefined {
179
+ for (const f of fields(buf)) {
180
+ if (f.no === 1 && f.bytes) return f.bytes.toString("utf-8");
181
+ if (f.no === 2 && f.int !== undefined) return f.int !== 0n;
182
+ if (f.no === 3 && f.int !== undefined) return Number(BigInt.asIntN(64, f.int));
183
+ if (f.no === 4 && f.bytes) return f.bytes.readDoubleLE(0);
184
+ }
185
+ return undefined;
186
+ }
187
+
188
+ function keyValue(buf: Buffer, into: Record<string, SpanValue>): void {
189
+ let key: string | undefined;
190
+ let value: SpanValue | undefined;
191
+ for (const f of fields(buf)) {
192
+ if (f.no === 1 && f.bytes) key = f.bytes.toString("utf-8");
193
+ else if (f.no === 2 && f.bytes) value = anyValue(f.bytes);
194
+ }
195
+ if (key !== undefined && value !== undefined) into[key] = value;
196
+ }
197
+
198
+ function protoSpan(buf: Buffer): CollectedSpan | undefined {
199
+ const s: Partial<CollectedSpan> & { attributes: Record<string, SpanValue> } = { attributes: {} };
200
+ for (const f of fields(buf)) {
201
+ if (!f.bytes) continue;
202
+ if (f.no === 2) s.spanId = f.bytes.toString("hex");
203
+ else if (f.no === 4 && f.bytes.length > 0) s.parentSpanId = f.bytes.toString("hex");
204
+ else if (f.no === 5) s.name = f.bytes.toString("utf-8");
205
+ else if (f.no === 7) s.start = f.bytes.readBigUInt64LE(0);
206
+ else if (f.no === 8) s.end = f.bytes.readBigUInt64LE(0);
207
+ else if (f.no === 9) keyValue(f.bytes, s.attributes);
208
+ else if (f.no === 15) {
209
+ for (const g of fields(f.bytes)) if (g.no === 3 && g.int === 2n) s.error = true;
210
+ }
211
+ }
212
+ if (!s.spanId || s.name === undefined || s.start === undefined || s.end === undefined) return undefined;
213
+ return s as CollectedSpan;
214
+ }
215
+
216
+ /** The spans of an `ExportTraceServiceRequest` in protobuf. */
217
+ export function decodeTracesProto(buf: Buffer): CollectedSpan[] {
218
+ const out: CollectedSpan[] = [];
219
+ for (const rs of fields(buf)) {
220
+ if (rs.no !== 1 || !rs.bytes) continue;
221
+ for (const ss of fields(rs.bytes)) {
222
+ if (ss.no !== 2 || !ss.bytes) continue;
223
+ for (const sp of fields(ss.bytes)) {
224
+ if (sp.no !== 2 || !sp.bytes) continue;
225
+ const span = protoSpan(sp.bytes);
226
+ if (span) out.push(span);
227
+ }
228
+ }
229
+ }
230
+ return out;
231
+ }
232
+
233
+ // OTLP JSON
234
+
235
+ type Json = Record<string, unknown>;
236
+ const isObj = (v: unknown): v is Json => typeof v === "object" && v !== null && !Array.isArray(v);
237
+ const list = (v: unknown): unknown[] => (Array.isArray(v) ? v : []);
238
+
239
+ function jsonValue(v: unknown): SpanValue | undefined {
240
+ if (!isObj(v)) return undefined;
241
+ if (typeof v.stringValue === "string") return v.stringValue;
242
+ if (typeof v.boolValue === "boolean") return v.boolValue;
243
+ if (typeof v.intValue === "string" || typeof v.intValue === "number") return Number(v.intValue);
244
+ if (typeof v.doubleValue === "number") return v.doubleValue;
245
+ return undefined;
246
+ }
247
+
248
+ const nanos = (v: unknown): bigint | undefined => {
249
+ try {
250
+ return typeof v === "string" || typeof v === "number" ? BigInt(v) : undefined;
251
+ } catch {
252
+ return undefined;
253
+ }
254
+ };
255
+
256
+ /** The spans of an `ExportTraceServiceRequest` in OTLP/JSON. */
257
+ export function decodeTracesJson(body: unknown): CollectedSpan[] {
258
+ const out: CollectedSpan[] = [];
259
+ for (const rs of list(isObj(body) ? body.resourceSpans : undefined)) {
260
+ if (!isObj(rs)) continue;
261
+ for (const ss of list(rs.scopeSpans)) {
262
+ if (!isObj(ss)) continue;
263
+ for (const s of list(ss.spans)) {
264
+ if (!isObj(s) || typeof s.spanId !== "string" || typeof s.name !== "string") continue;
265
+ const start = nanos(s.startTimeUnixNano);
266
+ const end = nanos(s.endTimeUnixNano);
267
+ if (start === undefined || end === undefined) continue;
268
+ const attributes: Record<string, SpanValue> = {};
269
+ for (const kv of list(s.attributes)) {
270
+ if (!isObj(kv) || typeof kv.key !== "string") continue;
271
+ const v = jsonValue(kv.value);
272
+ if (v !== undefined) attributes[kv.key] = v;
273
+ }
274
+ out.push({
275
+ spanId: s.spanId,
276
+ ...(typeof s.parentSpanId === "string" && s.parentSpanId ? { parentSpanId: s.parentSpanId } : {}),
277
+ name: s.name,
278
+ start,
279
+ end,
280
+ attributes,
281
+ ...(isObj(s.status) && (s.status.code === 2 || s.status.code === "STATUS_CODE_ERROR") ? { error: true } : {}),
282
+ });
283
+ }
284
+ }
285
+ }
286
+ return out;
287
+ }
288
+
289
+ // The receiver
290
+
291
+ /** The header whose token says which run of the binary a batch of spans came from. */
292
+ export const ENGINE_RUN_HEADER = "x-chant-run";
293
+
294
+ /** Where a batch is forwarded: the product's own collector. */
295
+ export interface SpanForward {
296
+ url: string;
297
+ headers?: Record<string, string>;
298
+ }
299
+
300
+ /**
301
+ * A loopback OTLP/HTTP trace endpoint for one run. It never holds the
302
+ * process open, and a request it cannot read is answered and dropped. Spans
303
+ * are kept by the key {@link SpanReceiver.exporter} was given.
304
+ */
305
+ export class SpanReceiver {
306
+ private server?: Server;
307
+ private url = "";
308
+ private readonly runs = new Map<string, string>();
309
+ private readonly spans = new Map<string, CollectedSpan[]>();
310
+ private readonly forwards: Promise<string | undefined>[] = [];
311
+ /** Batches that could not be read, with why. */
312
+ readonly unreadable: string[] = [];
313
+
314
+ /** `forward`: a collector that also gets every batch the binary sends, unchanged. */
315
+ constructor(private readonly forward?: SpanForward, private readonly fetchFn: typeof fetch = fetch) {}
316
+
317
+ /** Start listening. Undefined when it is up; the problem when it could not start. */
318
+ async listen(): Promise<string | undefined> {
319
+ const server = createServer((req, res) => this.handle(req, res));
320
+ try {
321
+ await new Promise<void>((resolve, reject) => {
322
+ server.once("error", reject);
323
+ server.listen(0, "127.0.0.1", () => resolve());
324
+ });
325
+ } catch (e) {
326
+ return (e as Error).message;
327
+ }
328
+ server.unref();
329
+ const addr = server.address();
330
+ if (!addr || typeof addr === "string") return "no port";
331
+ this.server = server;
332
+ this.url = `http://127.0.0.1:${addr.port}/v1/traces`;
333
+ return undefined;
334
+ }
335
+
336
+ get listening(): boolean {
337
+ return this.server !== undefined;
338
+ }
339
+
340
+ /** The variables one run of the binary gets so its spans come here, kept under `key`; none when the receiver is not listening. */
341
+ exporter(key: string): Record<string, string> {
342
+ if (!this.server) return {};
343
+ const token = randomBytes(12).toString("hex");
344
+ this.runs.set(token, key);
345
+ return {
346
+ OTEL_TRACES_EXPORTER: "otlp",
347
+ OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: this.url,
348
+ OTEL_EXPORTER_OTLP_TRACES_PROTOCOL: "http/protobuf",
349
+ OTEL_EXPORTER_OTLP_TRACES_HEADERS: `${ENGINE_RUN_HEADER}=${token}`,
350
+ };
351
+ }
352
+
353
+ /** The spans the runs exported under `key` sent. */
354
+ spansOf(key: string): CollectedSpan[] {
355
+ return this.spans.get(key) ?? [];
356
+ }
357
+
358
+ private handle(req: IncomingMessage, res: ServerResponse): void {
359
+ const chunks: Buffer[] = [];
360
+ req.on("data", (c: Buffer) => chunks.push(c));
361
+ req.on("end", () => {
362
+ const type = String(req.headers["content-type"] ?? "");
363
+ const proto = !type.includes("json");
364
+ const reply = (status: number) => {
365
+ res.writeHead(status, { "content-type": proto ? "application/x-protobuf" : "application/json" });
366
+ res.end(proto ? "" : "{}");
367
+ };
368
+ const key = this.runs.get(String(req.headers[ENGINE_RUN_HEADER] ?? ""));
369
+ if (req.method !== "POST" || key === undefined) return reply(req.method === "POST" ? 401 : 405);
370
+ const raw = Buffer.concat(chunks);
371
+ try {
372
+ const encoding = String(req.headers["content-encoding"] ?? "").toLowerCase();
373
+ const body = encoding === "gzip" ? gunzipSync(raw) : encoding === "deflate" ? inflateSync(raw) : raw;
374
+ const got = proto ? decodeTracesProto(body) : decodeTracesJson(JSON.parse(body.toString("utf-8")));
375
+ this.spans.set(key, [...(this.spans.get(key) ?? []), ...got]);
376
+ } catch (e) {
377
+ this.unreadable.push(`${key.replace(/\u0000/g, " ")}: ${(e as Error).message}`);
378
+ }
379
+ reply(200);
380
+ if (this.forward) this.forwards.push(this.relay(raw, req));
381
+ });
382
+ }
383
+
384
+ private async relay(raw: Buffer, req: IncomingMessage): Promise<string | undefined> {
385
+ const t = this.forward!;
386
+ const headers: Record<string, string> = { ...t.headers, "content-type": String(req.headers["content-type"] ?? "application/x-protobuf") };
387
+ if (req.headers["content-encoding"]) headers["content-encoding"] = String(req.headers["content-encoding"]);
388
+ try {
389
+ const res = await this.fetchFn(t.url, { method: "POST", headers, body: new Uint8Array(raw), signal: AbortSignal.timeout(10_000) });
390
+ return res.ok ? undefined : `${t.url} answered ${res.status}`;
391
+ } catch (e) {
392
+ return `${t.url}: ${(e as Error).message}`;
393
+ }
394
+ }
395
+
396
+ /** Stop listening, once every forwarded batch is answered. Returns the forwards that failed. */
397
+ async close(): Promise<string[]> {
398
+ const problems = (await Promise.all(this.forwards)).filter((p): p is string => p !== undefined);
399
+ const server = this.server;
400
+ this.server = undefined;
401
+ if (server) await new Promise<void>((resolve) => server.close(() => resolve()));
402
+ return problems;
403
+ }
404
+ }
405
+
406
+ // Reading the spans
407
+
408
+ /** How many of each list a root's timings keep. */
409
+ export const TOP = 10;
410
+
411
+ const RESOURCE_SPANS = new Set(["Plan resource instance changes", "Apply resource instance changes"]);
412
+ const BUILTIN_PROVIDER = "terraform.io/builtin/terraform";
413
+ const PROVIDER_CALL = /^tfplugin[56]\.Provider\/(\w+)$/;
414
+
415
+ const ms = (s: CollectedSpan): number => Math.round(Number(s.end - s.start) / 1e5) / 10;
416
+ const str = (v: SpanValue | undefined): string | undefined => (v === undefined || v === "" ? undefined : String(v));
417
+ const num = (v: SpanValue | undefined): number | undefined => (typeof v === "number" ? v : typeof v === "string" && v !== "" && !Number.isNaN(Number(v)) ? Number(v) : undefined);
418
+ const slowest = <T extends { ms: number }>(xs: T[], n = TOP): T[] => [...xs].sort((a, b) => b.ms - a.ms).slice(0, n);
419
+ const defined = <T extends object>(o: T): T => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined)) as T;
420
+
421
+ export interface RootFacts {
422
+ /** The binary's name, for the notes. */
423
+ binary: string;
424
+ /** The root's wall time, init and show included. */
425
+ seconds: number;
426
+ /** The binary's plan run. Absent when the root never reached it. */
427
+ planSeconds?: number;
428
+ /** A tf-apply wave's apply run. Absent when the root was not applied. */
429
+ applySeconds?: number;
430
+ /** `terragrunt`: Terragrunt ran the binary, so the times are its run report's; the spans are its plan's, through a `TG_TF_PATH` wrapper the product sets. */
431
+ source?: "binary" | "terragrunt";
432
+ }
433
+
434
+ /** A root's timings from the spans its plan sent. */
435
+ export function rootTimings(spans: CollectedSpan[], facts: RootFacts): EngineRootTimings {
436
+ const byId = new Map(spans.map((s) => [s.spanId, s]));
437
+ const refresh = new Map<string, number>();
438
+ for (const s of spans) if (s.name === "Refresh resource instance" && s.parentSpanId) refresh.set(s.parentSpanId, (refresh.get(s.parentSpanId) ?? 0) + ms(s));
439
+
440
+ const resources: EngineResourceTiming[] = spans.filter((s) => RESOURCE_SPANS.has(s.name)).map((s) => defined({
441
+ address: str(s.attributes["opentofu.resource_instance.address"]) ?? "(no address)",
442
+ type: str(s.attributes["opentofu.resource.type"]),
443
+ action: str(s.attributes["opentofu.resource_instance.action"]),
444
+ provider: str(s.attributes["opentofu.provider_instance.address"]),
445
+ ms: ms(s),
446
+ refresh_ms: refresh.get(s.spanId),
447
+ }));
448
+
449
+ const calls: EngineProviderCall[] = [];
450
+ for (const s of spans) {
451
+ const m = PROVIDER_CALL.exec(s.name);
452
+ if (!m) continue;
453
+ const parent = s.parentSpanId ? byId.get(s.parentSpanId) : undefined;
454
+ calls.push(defined({
455
+ method: str(s.attributes["rpc.method"]) ?? m[1],
456
+ provider: str(s.attributes["opentofu.provider.address"]),
457
+ type: str(s.attributes["opentofu.resource.type"]),
458
+ address: parent && RESOURCE_SPANS.has(parent.name) ? str(parent.attributes["opentofu.resource_instance.address"]) : undefined,
459
+ ms: ms(s),
460
+ }));
461
+ }
462
+
463
+ // choudoufu starts each provider process inside a "Start provider" span.
464
+ // OpenTofu has none: the nearest it sends is "Configure provider", which
465
+ // names the provider in opentofu.provider.source. The builtin provider runs
466
+ // in-process and is left out. A root with Start spans is read from those
467
+ // alone, so choudoufu's Configure spans are not counted a second time.
468
+ const startSpans = spans.filter((s) => s.name === "Start provider");
469
+ const initSpans = startSpans.length > 0 ? startSpans : spans.filter((s) => s.name === "Configure provider" && str(s.attributes["opentofu.provider.source"]) !== BUILTIN_PROVIDER);
470
+ const starts = new Map<string, { provider: string; count: number; ms: number; max_ms: number }>();
471
+ for (const s of initSpans) {
472
+ const provider = str(s.attributes["opentofu.provider.address"]) ?? str(s.attributes["opentofu.provider.source"]) ?? "(unnamed)";
473
+ const e = starts.get(provider) ?? { provider, count: 0, ms: 0, max_ms: 0 };
474
+ e.count++;
475
+ e.ms = Math.round((e.ms + ms(s)) * 10) / 10;
476
+ e.max_ms = Math.max(e.max_ms, ms(s));
477
+ starts.set(provider, e);
478
+ }
479
+
480
+ const lockWaits = spans.filter((s) => s.name === "State lock wait").map((s) => defined({
481
+ backend: str(s.attributes["opentofu.state.backend"]),
482
+ operation: str(s.attributes["opentofu.state.lock.operation"]),
483
+ attempts: num(s.attributes["opentofu.state.lock.attempts"]),
484
+ ms: ms(s),
485
+ }));
486
+
487
+ const aggregates: EngineAggregate[] = spans.filter((s) => s.name.startsWith("Aggregate: ")).map((s) => {
488
+ const a = s.attributes;
489
+ return defined({
490
+ of: s.name.slice("Aggregate: ".length),
491
+ kind: str(a["choudoufu.aggregate.kind"]),
492
+ type: str(a["opentofu.resource.type"]),
493
+ provider: str(a["opentofu.provider.address"]),
494
+ method: str(a["rpc.method"]),
495
+ count: num(a["choudoufu.aggregate.count"]) ?? 0,
496
+ detailed: num(a["choudoufu.aggregate.detailed_count"]) ?? 0,
497
+ ms: num(a["choudoufu.aggregate.duration_total_ms"]) ?? 0,
498
+ max_ms: num(a["choudoufu.aggregate.duration_max_ms"]) ?? 0,
499
+ slowest: str(a["choudoufu.aggregate.slowest"]),
500
+ groups: num(a["choudoufu.aggregate.groups"]),
501
+ });
502
+ });
503
+
504
+ const summed = aggregates.filter((a) => a.kind !== "provider_call").reduce((n, a) => n + Math.max(0, a.count - a.detailed), 0);
505
+ const detail: EngineRootTimings["detail"] = resources.length > 0 ? "resources" : aggregates.length > 0 ? "aggregate" : "none";
506
+ const what = facts.applySeconds !== undefined ? "plan and apply" : "plan";
507
+ let note: string | undefined;
508
+ if (facts.source === "terragrunt" && spans.length === 0) note = `Terragrunt ran the binary for this unit, so its time is from Terragrunt's run report, and ${facts.binary} sent no spans for its plan, so it has no per-resource timings`;
509
+ else if (facts.source === "terragrunt" && detail === "none") note = `Terragrunt ran the binary for this unit, so its time is from Terragrunt's run report; ${facts.binary} sent ${spans.length} span${spans.length === 1 ? "" : "s"} for its plan, none of them per resource`;
510
+ else if (facts.planSeconds === undefined) note = "the root did not reach a plan, so no spans were read";
511
+ else if (spans.length === 0) note = `${facts.binary} sent no spans for the ${what}, so this root has no per-resource timings. A binary that exports per-resource OpenTelemetry spans, such as choudoufu, gives them`;
512
+ else if (detail === "none") note = `${facts.binary} sent ${spans.length} span${spans.length === 1 ? "" : "s"} for the ${what}, none of them per resource, so this root has no per-resource timings`;
513
+ else if (detail === "aggregate") note = `${facts.binary} summed its resources by type instead of a span each, so the slowest are listed by type`;
514
+ else if (summed > 0) note = `past the span budget, ${summed} resource instance${summed === 1 ? " is" : "s are"} summed by type instead of listed`;
515
+
516
+ return {
517
+ seconds: Math.round(facts.seconds * 100) / 100,
518
+ ...(facts.planSeconds !== undefined ? { plan_seconds: Math.round(facts.planSeconds * 100) / 100 } : {}),
519
+ ...(facts.applySeconds !== undefined ? { apply_seconds: Math.round(facts.applySeconds * 100) / 100 } : {}),
520
+ ...(facts.source === "terragrunt" ? { source: "terragrunt" as const } : {}),
521
+ spans: spans.length,
522
+ detail,
523
+ ...(note ? { note } : {}),
524
+ resources: slowest(resources),
525
+ provider_calls: slowest(calls),
526
+ provider_init: slowest([...starts.values()]),
527
+ lock_waits: slowest(lockWaits),
528
+ aggregates: slowest(aggregates, 2 * TOP),
529
+ };
530
+ }
531
+
532
+ /** The run's slowest roots and resources, from each root's timings. */
533
+ export function runTimings(roots: { path: string; timings?: EngineRootTimings }[], note?: string): EngineRunTimings {
534
+ const timed = roots.filter((r): r is { path: string; timings: EngineRootTimings } => r.timings !== undefined);
535
+ return {
536
+ roots: [...timed]
537
+ .sort((a, b) => b.timings.seconds - a.timings.seconds)
538
+ .map((r) => ({
539
+ root: r.path,
540
+ seconds: r.timings.seconds,
541
+ ...(r.timings.plan_seconds !== undefined ? { plan_seconds: r.timings.plan_seconds } : {}),
542
+ ...(r.timings.apply_seconds !== undefined ? { apply_seconds: r.timings.apply_seconds } : {}),
543
+ ...(r.timings.source ? { source: r.timings.source } : {}),
544
+ detail: r.timings.detail,
545
+ })),
546
+ resources: slowest(timed.flatMap((r) => r.timings.resources.map((x) => ({ root: r.path, address: x.address, ...(x.type ? { type: x.type } : {}), ms: x.ms })))),
547
+ ...(note ? { note } : {}),
548
+ };
549
+ }
550
+
551
+ /** `850ms`, `3.2s`, `2m05s`. */
552
+ export function duration(msValue: number): string {
553
+ if (msValue < 1000) return `${Math.round(msValue)}ms`;
554
+ const s = msValue / 1000;
555
+ if (s < 59.95) return `${s.toFixed(1)}s`;
556
+ const total = Math.round(s);
557
+ return `${Math.floor(total / 60)}m${String(total % 60).padStart(2, "0")}s`;
558
+ }
559
+
560
+ // The hook
561
+
562
+ /** One engine command a root ran, as {@link EngineTimings} timed it. */
563
+ export interface EngineCommandTiming {
564
+ /** The subcommand: `init`, `plan`, `show`, `apply`, `output`, `live-plan-set`... */
565
+ command: string;
566
+ /** The step method it ran in: `plan`, `run` or `outputs`. */
567
+ method: string;
568
+ seconds: number;
569
+ code: number | null;
570
+ }
571
+
572
+ /** A root's timings with the commands they came from. */
573
+ export interface EngineRoot extends EngineRootTimings {
574
+ root: string;
575
+ /** Each engine command the root ran, in order; an upstream's reads for it are left out. */
576
+ commands: EngineCommandTiming[];
577
+ /** The engine's init runs alone. */
578
+ init_seconds?: number;
579
+ /** For a member of a composed group: every member, this one included. Its times and spans are the group's. */
580
+ composed?: string[];
581
+ }
582
+
583
+ export interface EngineTimingsOptions {
584
+ /** A collector each batch of the engine's spans is forwarded to, unchanged: the product's own, when it sends a trace. */
585
+ forward?: SpanForward;
586
+ fetch?: typeof fetch;
587
+ /**
588
+ * The product's own hook, run first for each command (its trace span, say).
589
+ * Its variables are laid under the receiver's, and its `after` runs before
590
+ * the timing is kept.
591
+ */
592
+ inner?: TerraformCommandHook;
593
+ /** The commands whose spans count. Default `plan` and `apply`. */
594
+ spanCommands?: readonly string[];
595
+ /** The binary's name, for the notes. Default the name each command ran. */
596
+ binary?: string;
597
+ /** Leave the span receiver off: commands are still timed. */
598
+ noSpans?: boolean;
599
+ }
600
+
601
+ /** The key spans are kept by: a root's, or a composed group's, and the command. */
602
+ const keyOf = (roots: readonly string[], command: string): string => `${roots.join("\u0001")}\u0000${command}`;
603
+
604
+ /**
605
+ * The engine timings of one run (chant#4887): {@link EngineTimings.onCommand}
606
+ * goes in `terraformApplyCapabilityWith({ onCommand })`, and once the wave
607
+ * ran, {@link EngineTimings.roots} gives each root's timings and
608
+ * {@link EngineTimings.run} the run's slowest roots and resources. Call
609
+ * {@link EngineTimings.close} once, after the last command.
610
+ */
611
+ export class EngineTimings {
612
+ /** Why the engine's spans are not collected, when the receiver could not listen. Commands are timed all the same. */
613
+ readonly problem?: string;
614
+ private readonly commands = new Map<string, EngineCommandTiming[]>();
615
+ private readonly groups = new Map<string, string[]>();
616
+ private readonly binaries = new Map<string, string>();
617
+ private readonly spanCommands: readonly string[];
618
+
619
+ private constructor(private readonly options: EngineTimingsOptions, private readonly receiver: SpanReceiver | undefined, problem?: string) {
620
+ this.spanCommands = options.spanCommands ?? ["plan", "apply"];
621
+ if (problem) this.problem = problem;
622
+ }
623
+
624
+ /** Start the receiver (unless `noSpans`) and answer the timings. Never throws: a receiver that cannot listen leaves `problem` set. */
625
+ static async start(options: EngineTimingsOptions = {}): Promise<EngineTimings> {
626
+ if (options.noSpans) return new EngineTimings(options, undefined);
627
+ const receiver = new SpanReceiver(options.forward, options.fetch);
628
+ const problem = await receiver.listen();
629
+ return problem ? new EngineTimings(options, undefined, problem) : new EngineTimings(options, receiver);
630
+ }
631
+
632
+ /** Batches of spans that could not be read, with why. */
633
+ get unreadable(): readonly string[] {
634
+ return this.receiver?.unreadable ?? [];
635
+ }
636
+
637
+ /** The hook to pass as `onCommand`. */
638
+ readonly onCommand: TerraformCommandHook = async (c: TerraformCommand) => {
639
+ const inner = (await this.options.inner?.(c)) ?? {};
640
+ // An upstream's reads for a root are the upstream's, not the root's: only the product's own hook sees them.
641
+ if (c.upstream !== undefined) return inner;
642
+ const roots = c.members && c.members.length > 0 ? [...c.members] : [c.root];
643
+ if (roots.length > 1) for (const r of roots) this.groups.set(r, roots);
644
+ for (const r of roots) this.binaries.set(r, (c.binary.split("/").pop() || c.binary));
645
+ const exporter = this.receiver && this.spanCommands.includes(c.name) ? this.receiver.exporter(keyOf(roots, c.name)) : {};
646
+ return {
647
+ env: { ...(inner.env ?? {}), ...exporter },
648
+ after: async (r: TerraformCommandResult) => {
649
+ try {
650
+ await inner.after?.(r);
651
+ } finally {
652
+ for (const root of roots) {
653
+ const list = this.commands.get(root) ?? [];
654
+ list.push({ command: c.name, method: c.method, seconds: r.seconds, code: r.code });
655
+ this.commands.set(root, list);
656
+ }
657
+ }
658
+ },
659
+ };
660
+ };
661
+
662
+ /** One root's timings, or undefined when it ran no command. */
663
+ root(root: string): EngineRoot | undefined {
664
+ const commands = this.commands.get(root);
665
+ if (!commands) return undefined;
666
+ const group = this.groups.get(root) ?? [root];
667
+ const sum = (name: string): number | undefined => commands.filter((x) => x.command === name).reduce<number | undefined>((n, x) => (n ?? 0) + x.seconds, undefined);
668
+ const plan = sum("plan") ?? sum("live-plan-set");
669
+ const apply = sum("apply") ?? sum("live-wave-apply");
670
+ const init = sum("init");
671
+ const spans = this.spanCommands.flatMap((name) => this.receiver?.spansOf(keyOf(group, name)) ?? []);
672
+ const timings = rootTimings(spans, {
673
+ binary: this.options.binary ?? this.binaries.get(root) ?? "the binary",
674
+ seconds: commands.reduce((n, x) => n + x.seconds, 0),
675
+ ...(plan !== undefined ? { planSeconds: plan } : {}),
676
+ ...(apply !== undefined ? { applySeconds: apply } : {}),
677
+ });
678
+ return {
679
+ root,
680
+ ...timings,
681
+ commands: commands.map((x) => ({ ...x })),
682
+ ...(init !== undefined ? { init_seconds: Math.round(init * 100) / 100 } : {}),
683
+ ...(group.length > 1 ? { composed: [...group] } : {}),
684
+ };
685
+ }
686
+
687
+ /** Every root that ran a command, by root. */
688
+ roots(): Record<string, EngineRoot> {
689
+ const out: Record<string, EngineRoot> = {};
690
+ for (const root of [...this.commands.keys()].sort()) out[root] = this.root(root)!;
691
+ return out;
692
+ }
693
+
694
+ /** The run's slowest roots and resources; a composed group's resources count once. */
695
+ run(note?: string): EngineRunTimings {
696
+ const roots = Object.values(this.roots());
697
+ const once = new Set<string>();
698
+ const forResources = roots.filter((r) => {
699
+ const k = (r.composed ?? [r.root]).join("\u0001");
700
+ if (once.has(k)) return false;
701
+ once.add(k);
702
+ return true;
703
+ });
704
+ const all = runTimings(roots.map((r) => ({ path: r.root, timings: r })), note);
705
+ const resources = runTimings(forResources.map((r) => ({ path: r.composed ? r.composed.join(", ") : r.root, timings: r }))).resources;
706
+ return { ...all, resources };
707
+ }
708
+
709
+ /** Stop the receiver, once every forwarded batch is answered. Returns the forwards that failed. */
710
+ async close(): Promise<string[]> {
711
+ return this.receiver ? this.receiver.close() : [];
712
+ }
713
+ }
714
+
715
+ /** {@link EngineTimings.start}: the engine timings of one run, whose `onCommand` goes in `terraformApplyCapabilityWith`. */
716
+ export function engineTimings(options: EngineTimingsOptions = {}): Promise<EngineTimings> {
717
+ return EngineTimings.start(options);
718
+ }