@intellectual-frontiers/telemetry 0.0.0-stage → 0.1.0

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.
@@ -0,0 +1,848 @@
1
+ // Spec: 0001-telemetry FR-014
2
+ /**
3
+ * OpenTelemetry on the host (commons 0001-telemetry FR-014 to FR-019): the OTLP/HTTP JSON exporter over `fetch` (headers, timeout, retries on
4
+ * 429, 502, 503 and 504 after `Retry-After` or a growing wait, partial success counted, never throwing, a failure said once), the probe of
5
+ * `http://localhost:4318` where no endpoint is configured, the journal (every export request also one line of OTLP JSON in a rotated
6
+ * file), the current span carried across `await` by `AsyncLocalStorage` and the parent read from `TRACEPARENT` and `TRACESTATE`, the
7
+ * pipeline a process installs (`startTelemetry`), the runtime's own signals (`process`, `http.client`, `http.server`) that `proc`, the HTTP
8
+ * client and `serve` make through the hooks below (no-ops while nothing is installed), and an OTLP/HTTP JSON receiver over `serve`.
9
+ *
10
+ * This module imports only `node:` builtins and the kernel, so that `proc.ts`, `http-client.ts` and `serve.ts` can import its hooks.
11
+ *
12
+ * @example
13
+ * ```ts
14
+ * import { defineSignals } from "../signals.ts";
15
+ * import { ok } from "@intellectual-frontiers/core";
16
+ * import { startTelemetry } from "./otel.ts";
17
+ * const registry = defineSignals({ "build.step": { signal: "span", role: "step", attributes: { target: "string" } } });
18
+ * const run = startTelemetry({ registry, service: "build" }); // OTEL_* from the environment; installed for proc, the client and serve
19
+ * await run.telemetry.span("build.step", { target: "site" }, async () => ok(undefined));
20
+ * await run.pipeline.shutdown(); // at most one second
21
+ * const warning = run.pipeline.warning(); // what to say, once and dimmed, at the end of the run (FR-024)
22
+ * ```
23
+ *
24
+ * @module
25
+ */
26
+ import { AsyncLocalStorage } from "node:async_hooks";
27
+ import * as nfs from "node:fs";
28
+ import { dirname } from "node:path";
29
+ import process from "node:process";
30
+ import { absurd, formatDecodeError, err, ok } from "@intellectual-frontiers/core";
31
+ import { retryAfterMs } from "@intellectual-frontiers/formats/http";
32
+ import { commandShape, DEFAULT_OTLP_ENDPOINT, extractContext, redactText, redactUrl, resolveConfig, SEVERITY, signalEndpoint, } from "../otel.js";
33
+ import { decodeLogs, decodeMetrics, decodeResponse, decodeTraces, encodeLogs, encodeMetrics, encodeResponse, encodeTraces, } from "../otlp.js";
34
+ import { batchProcessor, createTelemetry, defineSignals, } from "../signals.js";
35
+ import { setProcessTracer } from "@intellectual-frontiers/system/proc";
36
+ /** The longest a probe of the default endpoint waits for an answer (FR-015). */
37
+ export const PROBE_TIMEOUT_MS = 150;
38
+ /** The longest the runtime waits at exit for what is left to be sent (FR-015). */
39
+ export const EXIT_WAIT_MS = 1000;
40
+ /** The statuses an export is retried on (FR-014). */
41
+ export const RETRYABLE_STATUSES = new Set([429, 502, 503, 504]);
42
+ // ---------------------------------------------------------------------------------------------------------------------------------
43
+ // Time, randomness, context (FR-011, FR-017)
44
+ // ---------------------------------------------------------------------------------------------------------------------------------
45
+ /** A clock of nanoseconds since the Unix epoch, from `performance.timeOrigin` and `performance.now()`: monotonic within the process. */
46
+ export function systemClock() {
47
+ const origin = BigInt(Math.round(performance.timeOrigin * 1000)) * 1000n;
48
+ return () => origin + BigInt(Math.round(performance.now() * 1e6));
49
+ }
50
+ /** `n` random bytes from Web Crypto. */
51
+ export function systemRandom(n) {
52
+ return globalThis.crypto.getRandomValues(new Uint8Array(n));
53
+ }
54
+ /** A context manager on `AsyncLocalStorage` (FR-017): the current span is carried across `await`, timers and callbacks. */
55
+ export function asyncContextManager() {
56
+ const storage = new AsyncLocalStorage();
57
+ return {
58
+ active: () => storage.getStore(),
59
+ with(context, fn) {
60
+ return storage.run(context, fn);
61
+ },
62
+ };
63
+ }
64
+ /** The parent a process takes from its environment's `TRACEPARENT` and `TRACESTATE` (FR-017); undefined where there is no valid one. */
65
+ export function environmentParent(env = process.env) {
66
+ return extractContext(env["TRACEPARENT"], env["TRACESTATE"]);
67
+ }
68
+ function runtimeName() {
69
+ const v = process.versions;
70
+ return v["bun"] !== undefined ? "bun" : "node";
71
+ }
72
+ const OS_TYPES = { win32: "windows", sunos: "solaris" };
73
+ const HOST_ARCHES = { x64: "amd64", ia32: "x86", arm: "arm32", ppc64: "ppc64", s390x: "s390x" };
74
+ /**
75
+ * The attributes of the process that describe where it runs, by the semantic conventions: `process.runtime.name` and `.version`,
76
+ * `os.type` and `host.arch`. Never a host's or a person's name.
77
+ */
78
+ export function processAttributes() {
79
+ const name = runtimeName();
80
+ const v = process.versions;
81
+ return {
82
+ "process.runtime.name": name,
83
+ "process.runtime.version": v[name] ?? process.version.replace(/^v/, ""),
84
+ "os.type": OS_TYPES[process.platform] ?? process.platform,
85
+ "host.arch": HOST_ARCHES[process.arch] ?? process.arch,
86
+ };
87
+ }
88
+ function abortableSleep(ms, signal) {
89
+ return new Promise((resolve, reject) => {
90
+ if (signal.aborted) {
91
+ reject(new Error("the exporter is shut down"));
92
+ return;
93
+ }
94
+ const onAbort = () => {
95
+ clearTimeout(t);
96
+ reject(new Error("the exporter is shut down"));
97
+ };
98
+ const t = setTimeout(() => {
99
+ signal.removeEventListener("abort", onAbort);
100
+ resolve();
101
+ }, ms);
102
+ signal.addEventListener("abort", onAbort, { once: true });
103
+ });
104
+ }
105
+ function describeThrown(e) {
106
+ if (!(e instanceof Error))
107
+ return String(e);
108
+ const cause = e.cause instanceof Error ? `: ${e.cause.message}` : "";
109
+ return redactText(`${e.message}${cause}`);
110
+ }
111
+ /**
112
+ * The OTLP/HTTP JSON exporter over `fetch` (FR-014): each export is a `POST` of the request as JSON to the signal's endpoint, with
113
+ * `content-type: application/json` and the configured headers, within the signal's timeout; 429, 502, 503 and 504 are retried after the
114
+ * server's `Retry-After` or a doubling wait, as long as the wait ends within the timeout; a partial success is read and returned. An
115
+ * export never throws. Where a signal has no endpoint configured, the default is probed for at most 150 ms before the first export, and
116
+ * nothing is sent where nothing answers (FR-015). The first failure is told to `onWarning`, once. `shutdown` waits for the exports in
117
+ * flight within its time, then aborts them, so nothing keeps the process alive.
118
+ */
119
+ export function otlpExporter(exporters, options = {}) {
120
+ const fetcher = options.fetch ?? fetch;
121
+ const base = options.defaultEndpoint ?? DEFAULT_OTLP_ENDPOINT;
122
+ const probeTimeout = options.probeTimeoutMs ?? PROBE_TIMEOUT_MS;
123
+ const retryBase = options.retryBaseMs ?? 100;
124
+ const sleep = options.sleep ?? abortableSleep;
125
+ const stop = new AbortController();
126
+ const inflight = new Set();
127
+ let warned;
128
+ let probed;
129
+ const warn = (message) => {
130
+ if (warned !== undefined)
131
+ return;
132
+ warned = message;
133
+ try {
134
+ options.onWarning?.(message);
135
+ }
136
+ catch {
137
+ /* a listener never breaks an export */
138
+ }
139
+ };
140
+ const failure = (message) => {
141
+ warn(`OpenTelemetry signals were not exported: ${message}`);
142
+ return { kind: "failure", message };
143
+ };
144
+ // Any HTTP answer counts: an OTLP receiver answers an empty export request with 200, anything else with some status.
145
+ const probe = () => {
146
+ probed ??= (async () => {
147
+ try {
148
+ const res = await fetcher(signalEndpoint(base, "traces"), {
149
+ method: "POST",
150
+ headers: { "content-type": "application/json" },
151
+ body: "{}",
152
+ signal: AbortSignal.any([AbortSignal.timeout(probeTimeout), stop.signal]),
153
+ });
154
+ await res.body?.cancel().catch(() => undefined);
155
+ return true;
156
+ }
157
+ catch {
158
+ return false;
159
+ }
160
+ })();
161
+ return probed;
162
+ };
163
+ const endpointOf = async (signal) => {
164
+ const configured = exporters[signal].endpoint;
165
+ if (configured !== undefined)
166
+ return ok(configured);
167
+ if (await probe())
168
+ return ok(signalEndpoint(base, signal));
169
+ return err(`no OpenTelemetry collector answered at ${redactUrl(base)} within ${probeTimeout} ms`);
170
+ };
171
+ const post = async (signal, body) => {
172
+ const config = exporters[signal];
173
+ if (!config.enabled)
174
+ return { kind: "success" };
175
+ if (stop.signal.aborted)
176
+ return failure("the exporter is shut down");
177
+ const endpoint = await endpointOf(signal);
178
+ if (endpoint.kind === "err") {
179
+ warn(`${endpoint.error}; signals were not exported`);
180
+ return { kind: "failure", message: endpoint.error };
181
+ }
182
+ const url = endpoint.value;
183
+ const shown = redactUrl(url);
184
+ const deadline = Date.now() + config.timeoutMs;
185
+ for (let attempt = 0;; attempt++) {
186
+ const left = deadline - Date.now();
187
+ if (left <= 0)
188
+ return failure(`${shown} did not answer within ${config.timeoutMs} ms`);
189
+ let res;
190
+ try {
191
+ res = await fetcher(url, {
192
+ method: "POST",
193
+ headers: { ...config.headers, "content-type": "application/json" },
194
+ body,
195
+ signal: AbortSignal.any([AbortSignal.timeout(left), stop.signal]),
196
+ });
197
+ }
198
+ catch (e) {
199
+ if (stop.signal.aborted)
200
+ return failure(`the export to ${shown} was given up at exit`);
201
+ return failure(`${shown}: ${describeThrown(e)}`);
202
+ }
203
+ if (res.ok) {
204
+ const text = await res.text().catch(() => "");
205
+ if (text.trim() === "")
206
+ return { kind: "success" };
207
+ let parsed;
208
+ try {
209
+ parsed = JSON.parse(text);
210
+ }
211
+ catch {
212
+ return { kind: "success" };
213
+ }
214
+ const decoded = decodeResponse(signal, parsed);
215
+ if (decoded.kind === "err" || decoded.value.rejected === 0)
216
+ return { kind: "success" };
217
+ return { kind: "partial", rejected: decoded.value.rejected, message: decoded.value.errorMessage };
218
+ }
219
+ await res.body?.cancel().catch(() => undefined);
220
+ if (!RETRYABLE_STATUSES.has(res.status))
221
+ return failure(`${shown}: HTTP ${res.status}`);
222
+ const wait = retryAfterMs(res.headers.get("retry-after"), Date.now()) ?? retryBase * 2 ** attempt;
223
+ if (Date.now() + wait >= deadline)
224
+ return failure(`${shown}: HTTP ${res.status}, and no time is left to retry`);
225
+ try {
226
+ await sleep(wait, stop.signal);
227
+ }
228
+ catch {
229
+ return failure(`the export to ${shown} was given up at exit`);
230
+ }
231
+ }
232
+ };
233
+ const send = (signal, body) => {
234
+ const p = (async () => {
235
+ try {
236
+ return await post(signal, body());
237
+ }
238
+ catch (e) {
239
+ return failure(describeThrown(e));
240
+ }
241
+ })();
242
+ inflight.add(p);
243
+ void p.finally(() => inflight.delete(p));
244
+ return p;
245
+ };
246
+ return {
247
+ exportTraces: (batches) => send("traces", () => JSON.stringify(encodeTraces(batches))),
248
+ exportLogs: (batches) => send("logs", () => JSON.stringify(encodeLogs(batches))),
249
+ exportMetrics: (batches) => send("metrics", () => JSON.stringify(encodeMetrics(batches))),
250
+ async shutdown(timeoutMs) {
251
+ if (inflight.size > 0) {
252
+ let handle;
253
+ await Promise.race([
254
+ Promise.allSettled([...inflight]),
255
+ new Promise((resolve) => {
256
+ handle = setTimeout(resolve, Math.max(0, timeoutMs));
257
+ }),
258
+ ]);
259
+ clearTimeout(handle);
260
+ }
261
+ stop.abort();
262
+ },
263
+ warning: () => warned,
264
+ };
265
+ }
266
+ function sizeOf(path) {
267
+ try {
268
+ return nfs.statSync(path).size;
269
+ }
270
+ catch {
271
+ return 0;
272
+ }
273
+ }
274
+ const DAY_MS = 24 * 60 * 60 * 1000;
275
+ /** Each journal file (the current one and `<path>.1` to `<path>.<keep>`) last written before `oldest` removed. */
276
+ function removeAged(path, keep, oldest) {
277
+ for (const file of [path, ...Array.from({ length: keep }, (_, i) => `${path}.${i + 1}`)]) {
278
+ try {
279
+ if (nfs.statSync(file).mtimeMs < oldest)
280
+ nfs.rmSync(file, { force: true });
281
+ }
282
+ catch {
283
+ // not there: nothing to remove
284
+ }
285
+ }
286
+ }
287
+ function rotate(path, keep) {
288
+ if (keep <= 0) {
289
+ nfs.rmSync(path, { force: true });
290
+ return;
291
+ }
292
+ nfs.rmSync(`${path}.${keep}`, { force: true });
293
+ for (let i = keep - 1; i >= 1; i--)
294
+ if (nfs.existsSync(`${path}.${i}`))
295
+ nfs.renameSync(`${path}.${i}`, `${path}.${i + 1}`);
296
+ nfs.renameSync(path, `${path}.1`);
297
+ }
298
+ /**
299
+ * An exporter that writes each export request as one line of OTLP JSON to a file (FR-016), appended synchronously so that what a run made
300
+ * is kept even where it ends abruptly. Before a line is written to a file that already holds `maxBytes` or more, the file is rotated:
301
+ * `<path>.<keep>` removed, each `<path>.<i>` renamed `<path>.<i+1>`, and the file renamed `<path>.1`. Where `maxAgeDays` is given, a
302
+ * journal file last written longer ago than that is removed before the first line and after each rotation. A write that fails is a
303
+ * failure result, never a throw.
304
+ */
305
+ export function journalExporter(options) {
306
+ const maxBytes = options.maxBytes ?? 10 * 1024 * 1024;
307
+ const keep = Math.max(0, Math.floor(options.keep ?? 3));
308
+ let stopped = false;
309
+ let ready = false;
310
+ const write = (line) => {
311
+ if (stopped)
312
+ return Promise.resolve({ kind: "failure", message: "the journal is closed" });
313
+ try {
314
+ const age = () => {
315
+ if (options.maxAgeDays !== undefined)
316
+ removeAged(options.path, keep, (options.now ?? Date.now)() - options.maxAgeDays * DAY_MS);
317
+ };
318
+ if (!ready) {
319
+ nfs.mkdirSync(dirname(options.path), { recursive: true });
320
+ age();
321
+ ready = true;
322
+ }
323
+ if (sizeOf(options.path) >= maxBytes) {
324
+ rotate(options.path, keep);
325
+ age();
326
+ }
327
+ nfs.appendFileSync(options.path, `${line()}\n`);
328
+ return Promise.resolve({ kind: "success" });
329
+ }
330
+ catch (e) {
331
+ return Promise.resolve({ kind: "failure", message: `the journal ${options.path} could not be written: ${describeThrown(e)}` });
332
+ }
333
+ };
334
+ return {
335
+ exportTraces: (batches) => write(() => JSON.stringify(encodeTraces(batches))),
336
+ exportLogs: (batches) => write(() => JSON.stringify(encodeLogs(batches))),
337
+ exportMetrics: (batches) => write(() => JSON.stringify(encodeMetrics(batches))),
338
+ shutdown: () => {
339
+ stopped = true;
340
+ return Promise.resolve();
341
+ },
342
+ };
343
+ }
344
+ /** A batch processor that keeps a journal (FR-016): spans and log records batched as `options` says, metric collections as they come. */
345
+ export function journalProcessor(options) {
346
+ return batchProcessor(journalExporter(options), options);
347
+ }
348
+ /** A processor that hands on only the signals named: the others never reach `processor`. */
349
+ export function onlySignals(processor, signals) {
350
+ const s = new Set(signals);
351
+ return {
352
+ ...(s.has("traces") ? { onEnd: (span, source) => processor.onEnd?.(span, source) } : {}),
353
+ ...(s.has("logs") ? { onLog: (record, source) => processor.onLog?.(record, source) } : {}),
354
+ ...(s.has("metrics") ? { onMetrics: (metrics, source) => processor.onMetrics?.(metrics, source) } : {}),
355
+ forceFlush: (timeoutMs) => processor.forceFlush(timeoutMs),
356
+ shutdown: (timeoutMs) => processor.shutdown(timeoutMs),
357
+ stats: () => processor.stats(),
358
+ };
359
+ }
360
+ /**
361
+ * An exporter shared by `users` processors: its `shutdown` stops the exporter only when the last of them shuts it down, so that one
362
+ * processor's shutdown never aborts another's exports in flight.
363
+ */
364
+ export function shareExporter(exporter, users) {
365
+ let left = Math.max(1, users);
366
+ return {
367
+ exportTraces: (batches) => exporter.exportTraces(batches),
368
+ exportLogs: (batches) => exporter.exportLogs(batches),
369
+ exportMetrics: (batches) => exporter.exportMetrics(batches),
370
+ shutdown: (timeoutMs) => (--left <= 0 ? exporter.shutdown(timeoutMs) : Promise.resolve()),
371
+ };
372
+ }
373
+ // ---------------------------------------------------------------------------------------------------------------------------------
374
+ // The pipeline a process installs
375
+ // ---------------------------------------------------------------------------------------------------------------------------------
376
+ /** The signals the runtime itself makes (FR-018), and the warning that signals were not sent (FR-014). */
377
+ export const RUNTIME_SIGNALS = defineSignals({
378
+ process: {
379
+ signal: "span",
380
+ spanKind: "client",
381
+ role: "detail",
382
+ description: "A program run by proc: its name and option names alone (FR-006), and its exit status.",
383
+ attributes: { "process.executable.name": "string", "process.command_args": "string[]", "process.exit.code?": "int" },
384
+ },
385
+ "http.client": {
386
+ signal: "span",
387
+ spanKind: "client",
388
+ role: "detail",
389
+ description: "A request made by the HTTP client; the URL redacted (FR-006).",
390
+ attributes: {
391
+ "http.request.method": "string",
392
+ "url.full": "string",
393
+ "server.address": "string",
394
+ "server.port?": "int",
395
+ "http.response.status_code?": "int",
396
+ "error.type?": "string",
397
+ },
398
+ },
399
+ "http.server": {
400
+ signal: "span",
401
+ spanKind: "server",
402
+ role: "detail",
403
+ description: "A request answered by serve; its parent is the request's traceparent.",
404
+ attributes: {
405
+ "http.request.method": "string",
406
+ "url.path": "string",
407
+ "url.scheme": "string",
408
+ "server.address?": "string",
409
+ "server.port?": "int",
410
+ "http.response.status_code?": "int",
411
+ },
412
+ },
413
+ "otel.warning": {
414
+ signal: "log",
415
+ severity: SEVERITY.WARN,
416
+ // The console says this once, at the end of the run (FR-024), from `Pipeline.warning()`, not as it happens.
417
+ role: "none",
418
+ description: "Signals were not sent: an export failed, no collector answered, or the wait at exit ran out.",
419
+ attributes: {},
420
+ },
421
+ });
422
+ /** The scope of the runtime's own signals. */
423
+ export const RUNTIME_SCOPE = { name: "ifc-ts/runtime" };
424
+ async function within(promise, ms) {
425
+ let handle;
426
+ try {
427
+ return await Promise.race([
428
+ promise.then((value) => ({ value })),
429
+ new Promise((resolve) => {
430
+ handle = setTimeout(() => resolve(undefined), Math.max(0, ms));
431
+ }),
432
+ ]);
433
+ }
434
+ finally {
435
+ clearTimeout(handle);
436
+ }
437
+ }
438
+ function hasStats(p) {
439
+ return "stats" in p && typeof p.stats === "function";
440
+ }
441
+ function sumStats(all) {
442
+ const sum = (s) => {
443
+ let exported = 0;
444
+ let failed = 0;
445
+ let rejected = 0;
446
+ let dropped = 0;
447
+ let lastError;
448
+ for (const p of all) {
449
+ exported += p[s].exported;
450
+ failed += p[s].failed;
451
+ rejected += p[s].rejected;
452
+ dropped += p[s].dropped;
453
+ lastError = p[s].lastError ?? lastError;
454
+ }
455
+ return { exported, failed, rejected, dropped, ...(lastError === undefined ? {} : { lastError }) };
456
+ };
457
+ return { traces: sum("traces"), logs: sum("logs"), metrics: sum("metrics") };
458
+ }
459
+ /** The pipeline installed for this process, and the runtime's telemetry on it. */
460
+ let current;
461
+ /**
462
+ * A pipeline (FR-012, FR-017): the processors every signal goes to, one `AsyncLocalStorage` context, one clock and source of random
463
+ * bytes, and the telemetries made on it. It is not installed; `install` makes it the process's.
464
+ */
465
+ export function createPipeline(options) {
466
+ const processors = [...(options.processors ?? [])];
467
+ const context = options.context ?? asyncContextManager();
468
+ const clock = options.clock ?? systemClock();
469
+ const random = options.random ?? systemRandom;
470
+ const telemetries = [];
471
+ const listeners = new Set();
472
+ let warned;
473
+ let runtime;
474
+ let stopped = false;
475
+ // Every telemetry hands its signals to this one processor, which hands them to the pipeline's processors as they are now; flushing
476
+ // and shutting down are the pipeline's, once for every telemetry.
477
+ const fanout = {
478
+ onStart: (span, source) => processors.forEach((p) => p.onStart?.(span, source)),
479
+ onEvent: (span, event, source) => processors.forEach((p) => p.onEvent?.(span, event, source)),
480
+ onEnd: (span, source) => processors.forEach((p) => p.onEnd?.(span, source)),
481
+ onLog: (record, source) => processors.forEach((p) => p.onLog?.(record, source)),
482
+ onMetrics: (metrics, source) => processors.forEach((p) => p.onMetrics?.(metrics, source)),
483
+ forceFlush: () => Promise.resolve({ kind: "done" }),
484
+ shutdown: () => Promise.resolve({ kind: "done" }),
485
+ };
486
+ const interval = options.metricIntervalMs !== undefined && options.metricIntervalMs > 0
487
+ ? setInterval(() => {
488
+ for (const t of telemetries)
489
+ void t.forceFlush(0);
490
+ }, options.metricIntervalMs)
491
+ : undefined;
492
+ if (interval !== undefined && typeof interval === "object" && "unref" in interval)
493
+ interval.unref();
494
+ const settle = async (run, timeoutMs) => {
495
+ const settled = processors.map((p) => run(p).catch((e) => {
496
+ options.onError?.(e);
497
+ return { kind: "done" };
498
+ }));
499
+ const r = await within(Promise.all(settled), timeoutMs);
500
+ return r !== undefined && r.value.every((x) => x.kind === "done") ? { kind: "done" } : { kind: "timeout" };
501
+ };
502
+ const pipeline = {
503
+ resource: options.resource,
504
+ context,
505
+ parent: options.parent,
506
+ telemetry(registry, scope) {
507
+ const t = createTelemetry({
508
+ registry,
509
+ resource: options.resource,
510
+ scope,
511
+ clock,
512
+ random,
513
+ processors: [fanout],
514
+ context,
515
+ ...(options.parent === undefined ? {} : { parent: options.parent }),
516
+ ...(options.sampler === undefined ? {} : { sampler: options.sampler }),
517
+ ...(options.limits === undefined ? {} : { limits: options.limits }),
518
+ ...(options.onError === undefined ? {} : { onError: options.onError }),
519
+ });
520
+ telemetries.push(t);
521
+ return t;
522
+ },
523
+ addProcessor(processor) {
524
+ processors.push(processor);
525
+ return () => {
526
+ const i = processors.indexOf(processor);
527
+ if (i >= 0)
528
+ processors.splice(i, 1);
529
+ };
530
+ },
531
+ emit(item, source) {
532
+ if (stopped)
533
+ return;
534
+ for (const p of [...processors]) {
535
+ try {
536
+ switch (item.kind) {
537
+ case "span":
538
+ p.onEnd?.(item.span, source);
539
+ break;
540
+ case "log":
541
+ p.onLog?.(item.record, source);
542
+ break;
543
+ default:
544
+ absurd(item);
545
+ }
546
+ }
547
+ catch (e) {
548
+ options.onError?.(e);
549
+ }
550
+ }
551
+ },
552
+ warn(message) {
553
+ if (warned !== undefined)
554
+ return;
555
+ warned = message;
556
+ for (const l of [...listeners, ...(options.onWarning === undefined ? [] : [options.onWarning])]) {
557
+ try {
558
+ l(message);
559
+ }
560
+ catch (e) {
561
+ options.onError?.(e);
562
+ }
563
+ }
564
+ if (!stopped) {
565
+ runtime ??= pipeline.telemetry(RUNTIME_SIGNALS, RUNTIME_SCOPE);
566
+ runtime.log("otel.warning", {}, message);
567
+ }
568
+ },
569
+ warning: () => warned,
570
+ onWarning(listener) {
571
+ if (warned !== undefined)
572
+ listener(warned);
573
+ else
574
+ listeners.add(listener);
575
+ return () => void listeners.delete(listener);
576
+ },
577
+ stats: () => sumStats(processors.filter(hasStats).map((p) => p.stats())),
578
+ async forceFlush(timeoutMs = EXIT_WAIT_MS) {
579
+ const started = Date.now();
580
+ await Promise.all(telemetries.map((t) => t.forceFlush(0)));
581
+ return settle((p) => p.forceFlush(Math.max(0, timeoutMs - (Date.now() - started))), Math.max(0, timeoutMs - (Date.now() - started)));
582
+ },
583
+ async shutdown(timeoutMs = EXIT_WAIT_MS) {
584
+ if (current?.pipeline === pipeline)
585
+ current = undefined;
586
+ if (interval !== undefined)
587
+ clearInterval(interval);
588
+ const started = Date.now();
589
+ // Every telemetry ends its open spans and hands on its last metrics; its processor is the fan-out, which settles at once.
590
+ await Promise.all(telemetries.map((t) => t.shutdown(0)));
591
+ stopped = true;
592
+ const left = () => Math.max(0, timeoutMs - (Date.now() - started));
593
+ const r = await settle((p) => p.shutdown(left()), left());
594
+ if (r.kind === "timeout")
595
+ pipeline.warn(`not every signal was sent within ${timeoutMs} ms at exit; the rest were given up`);
596
+ return r;
597
+ },
598
+ };
599
+ return pipeline;
600
+ }
601
+ /** Makes `pipeline` the process's: the runtime's own signals (FR-018) go to it from now on. It replaces any installed before. */
602
+ export function install(pipeline) {
603
+ current = { pipeline, runtime: pipeline.telemetry(RUNTIME_SIGNALS, RUNTIME_SCOPE) };
604
+ }
605
+ /** Uninstalls the process's pipeline, if any; the runtime's hooks are no-ops again. */
606
+ export function uninstall() {
607
+ current = undefined;
608
+ }
609
+ /** The pipeline installed for this process, if any. */
610
+ export function installed() {
611
+ return current?.pipeline;
612
+ }
613
+ /**
614
+ * The telemetry of a process, from its environment (FR-005, FR-014 to FR-017): the configuration resolved from the `OTEL_*` variables, a
615
+ * resource (`service.name`, `process.runtime.*`, `os.type`, `host.arch`; never a host's or a person's name), `AsyncLocalStorage` for the
616
+ * current span with the parent from `TRACEPARENT` and `TRACESTATE`, a batch processor exporting spans and one exporting log records and
617
+ * metrics over OTLP/HTTP JSON (none where the SDK is disabled or no signal is exported), a journal where asked, the processors given, and
618
+ * the metrics collected every `OTEL_METRIC_EXPORT_INTERVAL`. Installed as the process's pipeline unless `install` is false.
619
+ */
620
+ export function startTelemetry(options) {
621
+ const env = options.env ?? process.env;
622
+ const { config, warnings } = resolveConfig(env);
623
+ const resource = {
624
+ attributes: {
625
+ "service.name": options.service ?? `unknown_service:${runtimeName()}`,
626
+ "telemetry.sdk.name": "ifc-ts",
627
+ ...processAttributes(),
628
+ ...config.resource,
629
+ },
630
+ };
631
+ const signals = ["traces", "logs", "metrics"].filter((s) => config.exporters[s].enabled);
632
+ const parent = environmentParent(env);
633
+ const pipeline = createPipeline({
634
+ resource,
635
+ processors: options.processors ?? [],
636
+ ...(parent === undefined ? {} : { parent }),
637
+ ...(options.clock === undefined ? {} : { clock: options.clock }),
638
+ ...(options.random === undefined ? {} : { random: options.random }),
639
+ sampler: config.sampler,
640
+ limits: config.limits,
641
+ // Metrics are collected on a schedule only where something exports them; otherwise at a flush and at exit.
642
+ ...(signals.includes("metrics") || options.journal !== undefined ? { metricIntervalMs: config.metricExportIntervalMs } : {}),
643
+ ...(options.onWarning === undefined ? {} : { onWarning: options.onWarning }),
644
+ });
645
+ if (signals.length > 0) {
646
+ const rest = signals.filter((s) => s !== "traces");
647
+ const users = (signals.includes("traces") ? 1 : 0) + (rest.length > 0 ? 1 : 0);
648
+ const exporter = shareExporter(otlpExporter(config.exporters, { ...options.exporter, onWarning: (m) => pipeline.warn(m) }), users);
649
+ if (signals.includes("traces"))
650
+ pipeline.addProcessor(onlySignals(batchProcessor(exporter, config.spanBatch), ["traces"]));
651
+ if (rest.length > 0)
652
+ pipeline.addProcessor(onlySignals(batchProcessor(exporter, config.logBatch), rest));
653
+ }
654
+ if (options.journal !== undefined)
655
+ pipeline.addProcessor(journalProcessor({ ...options.journal, ...config.logBatch }));
656
+ const telemetry = pipeline.telemetry(options.registry, {
657
+ name: options.service ?? "ifc-ts",
658
+ ...(options.version === undefined ? {} : { version: options.version }),
659
+ });
660
+ if (options.install !== false)
661
+ install(pipeline);
662
+ return { pipeline, telemetry, config, configWarnings: warnings };
663
+ }
664
+ function carried(r) {
665
+ return r.kind === "ok" ? r.value : r.error.value;
666
+ }
667
+ /**
668
+ * Runs a program in a `process` client span (FR-018): `process.executable.name` and `process.command_args` as `commandShape` gives them
669
+ * (the program and its option names, never a value, FR-006), `process.exit.code`, `error` where it is not 0. `run` is given the
670
+ * `TRACEPARENT` and `TRACESTATE` to add to the program's environment. With no pipeline installed, `run({})` and nothing else.
671
+ */
672
+ export function traceProcess(argv, run) {
673
+ const c = current;
674
+ if (c === undefined)
675
+ return run({});
676
+ const shape = commandShape(argv);
677
+ return c.runtime
678
+ .span("process", { "process.executable.name": shape[0] ?? "", "process.command_args": shape }, async (span) => {
679
+ const env = { TRACEPARENT: span.traceparent };
680
+ if (span.tracestate !== "")
681
+ env["TRACESTATE"] = span.tracestate;
682
+ const r = await run(env);
683
+ span.set({ "process.exit.code": r.code });
684
+ return r.code === 0 ? ok(r) : err({ value: r, message: `${shape[0] ?? "the program"} exited with ${r.code}` });
685
+ })
686
+ .then(carried);
687
+ }
688
+ // The system's process runner traces its programs through this module's pipeline once the module is loaded (commons 0032-lifting-libraries: the system does not import the telemetry).
689
+ setProcessTracer(traceProcess);
690
+ function portOf(url) {
691
+ if (url.port !== "")
692
+ return Number(url.port);
693
+ return url.protocol === "https:" ? 443 : url.protocol === "http:" ? 80 : undefined;
694
+ }
695
+ /**
696
+ * Sends a request in an `http.client` span (FR-018): `http.request.method`, `url.full` redacted (FR-006), `server.address`, `server.port`,
697
+ * `http.response.status_code` (`status` of what `send` gives; undefined where no answer came), `error` from 400 up or with no answer.
698
+ * `send` is given the `traceparent` (and `tracestate`) headers to add. With no pipeline installed, `send({})` and nothing else.
699
+ */
700
+ export function traceHttpClient(method, url, send, status) {
701
+ const c = current;
702
+ if (c === undefined)
703
+ return send({});
704
+ let parsed;
705
+ try {
706
+ parsed = new URL(url);
707
+ }
708
+ catch {
709
+ parsed = undefined;
710
+ }
711
+ const port = parsed === undefined ? undefined : portOf(parsed);
712
+ return c.runtime
713
+ .span("http.client", {
714
+ "http.request.method": method,
715
+ "url.full": redactUrl(url),
716
+ "server.address": parsed?.hostname ?? "",
717
+ ...(port === undefined ? {} : { "server.port": port }),
718
+ }, async (span) => {
719
+ const headers = { traceparent: span.traceparent };
720
+ if (span.tracestate !== "")
721
+ headers["tracestate"] = span.tracestate;
722
+ const value = await send(headers);
723
+ const code = status(value);
724
+ if (code === undefined) {
725
+ span.set({ "error.type": "network" });
726
+ return err({ value, message: "no answer" });
727
+ }
728
+ span.set({ "http.response.status_code": code, ...(code >= 400 ? { "error.type": String(code) } : {}) });
729
+ return code >= 400 ? err({ value, message: `HTTP ${code}` }) : ok(value);
730
+ })
731
+ .then(carried);
732
+ }
733
+ const UNTRACED = new WeakSet();
734
+ /** A serve handler (or any function) marked so that `traceServer` makes no span for it: the OTLP receiver, so it never traces itself. */
735
+ export function untraced(handler) {
736
+ UNTRACED.add(handler);
737
+ return handler;
738
+ }
739
+ /**
740
+ * Answers a request in an `http.server` span (FR-018) whose parent is the request's `traceparent` and `tracestate` (the process's own
741
+ * parent where it has none): `http.request.method`, `url.path`, `url.scheme`, `server.address`, `server.port`,
742
+ * `http.response.status_code`, `error` from 500 up. With no pipeline installed, or a handler marked `untraced`, `handle()` and nothing else.
743
+ */
744
+ export function traceServer(request, handle, handler) {
745
+ const c = current;
746
+ if (c === undefined || (handler !== undefined && UNTRACED.has(handler)))
747
+ return handle();
748
+ const url = new URL(request.url);
749
+ const port = portOf(url);
750
+ const remote = extractContext(request.headers.get("traceparent") ?? undefined, request.headers.get("tracestate") ?? undefined);
751
+ const parent = remote ?? c.pipeline.parent;
752
+ return c.runtime
753
+ .span("http.server", {
754
+ "http.request.method": request.method,
755
+ "url.path": url.pathname,
756
+ "url.scheme": url.protocol.replace(/:$/, ""),
757
+ "server.address": url.hostname,
758
+ ...(port === undefined ? {} : { "server.port": port }),
759
+ }, async (span) => {
760
+ const response = await handle();
761
+ span.set({ "http.response.status_code": response.status });
762
+ return response.status >= 500 ? err({ value: response, message: `HTTP ${response.status}` }) : ok(response);
763
+ }, { parent: parent ?? null })
764
+ .then(carried);
765
+ }
766
+ const RECEIVER_PATHS = { "/v1/traces": "traces", "/v1/logs": "logs", "/v1/metrics": "metrics" };
767
+ function statusResponse(status, code, message) {
768
+ return new Response(JSON.stringify({ code, message }), { status, headers: { "content-type": "application/json" } });
769
+ }
770
+ async function bodyText(request) {
771
+ const encoding = (request.headers.get("content-encoding") ?? "identity").trim().toLowerCase();
772
+ if (encoding === "identity" || encoding === "")
773
+ return ok(await request.text());
774
+ if (encoding !== "gzip")
775
+ return err(statusResponse(415, 3, `the content encoding ${encoding} is not supported (gzip is)`));
776
+ if (request.body === null)
777
+ return ok("");
778
+ try {
779
+ return ok(await new Response(request.body.pipeThrough(new DecompressionStream("gzip"))).text());
780
+ }
781
+ catch {
782
+ return err(statusResponse(400, 3, "the body is not valid gzip"));
783
+ }
784
+ }
785
+ /**
786
+ * An OTLP/HTTP JSON receiver, as a handler for `serve` (FR-019): `POST /v1/traces`, `/v1/logs` and `/v1/metrics` with a JSON body
787
+ * (gzip-encoded or not) decoded by the kernel (FR-004) and handed to the sink; 415 for any content type but `application/json` (protobuf
788
+ * among them), 400 with the path where the body does not decode, 404 for another path, 405 for another method, and OTLP's success body
789
+ * (`{}`, or `partialSuccess` where the sink rejected some) otherwise. Errors are `google.rpc.Status` JSON. The handler is `untraced`.
790
+ */
791
+ export function otlpReceiver(sinks) {
792
+ return untraced(async (request) => {
793
+ const path = new URL(request.url).pathname;
794
+ const signal = Object.hasOwn(RECEIVER_PATHS, path) ? RECEIVER_PATHS[path] : undefined;
795
+ if (signal === undefined)
796
+ return statusResponse(404, 5, `${path} is not an OTLP path (/v1/traces, /v1/logs, /v1/metrics)`);
797
+ if (request.method !== "POST")
798
+ return statusResponse(405, 12, `${request.method} is not allowed; OTLP/HTTP is POST`);
799
+ const type = (request.headers.get("content-type") ?? "").split(";")[0]?.trim().toLowerCase() ?? "";
800
+ if (type !== "application/json") {
801
+ await request.body?.cancel().catch(() => undefined);
802
+ return statusResponse(415, 3, `the content type ${type === "" ? "(none)" : type} is not supported; send application/json`);
803
+ }
804
+ const text = await bodyText(request);
805
+ if (text.kind === "err")
806
+ return text.error;
807
+ let parsed;
808
+ try {
809
+ parsed = JSON.parse(text.value);
810
+ }
811
+ catch (e) {
812
+ return statusResponse(400, 3, `the body is not JSON: ${e instanceof Error ? e.message : String(e)}`);
813
+ }
814
+ let answer;
815
+ try {
816
+ switch (signal) {
817
+ case "traces": {
818
+ const d = decodeTraces(parsed);
819
+ if (d.kind === "err")
820
+ return statusResponse(400, 3, formatDecodeError(d.error));
821
+ answer = await sinks.onTraces?.(d.value);
822
+ break;
823
+ }
824
+ case "logs": {
825
+ const d = decodeLogs(parsed);
826
+ if (d.kind === "err")
827
+ return statusResponse(400, 3, formatDecodeError(d.error));
828
+ answer = await sinks.onLogs?.(d.value);
829
+ break;
830
+ }
831
+ case "metrics": {
832
+ const d = decodeMetrics(parsed);
833
+ if (d.kind === "err")
834
+ return statusResponse(400, 3, formatDecodeError(d.error));
835
+ answer = await sinks.onMetrics?.(d.value);
836
+ break;
837
+ }
838
+ default:
839
+ absurd(signal);
840
+ }
841
+ }
842
+ catch (e) {
843
+ return statusResponse(500, 13, `the receiver failed: ${describeThrown(e)}`);
844
+ }
845
+ const body = encodeResponse(signal, answer ?? { rejected: 0, errorMessage: "" });
846
+ return new Response(JSON.stringify(body), { status: 200, headers: { "content-type": "application/json" } });
847
+ });
848
+ }