@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.
- package/LICENSE +21 -0
- package/README.md +8 -2
- package/dist/host/console.d.ts +80 -0
- package/dist/host/console.js +188 -0
- package/dist/host/mod.d.ts +15 -0
- package/dist/host/mod.js +16 -0
- package/dist/host/otel.d.ts +280 -0
- package/dist/host/otel.js +848 -0
- package/dist/mod.d.ts +17 -0
- package/dist/mod.js +18 -0
- package/dist/otel.d.ts +365 -0
- package/dist/otel.js +686 -0
- package/dist/otlp.d.ts +83 -0
- package/dist/otlp.js +634 -0
- package/dist/render.d.ts +111 -0
- package/dist/render.js +368 -0
- package/dist/signals.d.ts +371 -0
- package/dist/signals.js +800 -0
- package/package.json +76 -4
- package/src/host/console.ts +253 -0
- package/src/host/mod.ts +16 -0
- package/src/host/otel.ts +1068 -0
- package/src/mod.ts +18 -0
- package/src/otel.ts +919 -0
- package/src/otlp.ts +721 -0
- package/src/render.ts +489 -0
- package/src/signals.ts +1175 -0
package/package.json
CHANGED
|
@@ -1,6 +1,78 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@intellectual-frontiers/telemetry",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "OpenTelemetry-native signals for TypeScript, written from the specification itself with no OpenTelemetry package: the data model, W3C Trace Context, OTLP/HTTP JSON, typed signals, a pure renderer of the console, and a host that exports, journals and shows them; the same code on Bun and Node 26.",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"engines": {
|
|
8
|
+
"node": ">=26"
|
|
9
|
+
},
|
|
10
|
+
"sideEffects": false,
|
|
11
|
+
"types": "./dist/mod.d.ts",
|
|
12
|
+
"exports": {
|
|
13
|
+
".": {
|
|
14
|
+
"types": "./dist/mod.d.ts",
|
|
15
|
+
"bun": "./src/mod.ts",
|
|
16
|
+
"default": "./dist/mod.js"
|
|
17
|
+
},
|
|
18
|
+
"./otel": {
|
|
19
|
+
"types": "./dist/otel.d.ts",
|
|
20
|
+
"bun": "./src/otel.ts",
|
|
21
|
+
"default": "./dist/otel.js"
|
|
22
|
+
},
|
|
23
|
+
"./otlp": {
|
|
24
|
+
"types": "./dist/otlp.d.ts",
|
|
25
|
+
"bun": "./src/otlp.ts",
|
|
26
|
+
"default": "./dist/otlp.js"
|
|
27
|
+
},
|
|
28
|
+
"./signals": {
|
|
29
|
+
"types": "./dist/signals.d.ts",
|
|
30
|
+
"bun": "./src/signals.ts",
|
|
31
|
+
"default": "./dist/signals.js"
|
|
32
|
+
},
|
|
33
|
+
"./render": {
|
|
34
|
+
"types": "./dist/render.d.ts",
|
|
35
|
+
"bun": "./src/render.ts",
|
|
36
|
+
"default": "./dist/render.js"
|
|
37
|
+
},
|
|
38
|
+
"./host": {
|
|
39
|
+
"types": "./dist/host/mod.d.ts",
|
|
40
|
+
"bun": "./src/host/mod.ts",
|
|
41
|
+
"default": "./dist/host/mod.js"
|
|
42
|
+
},
|
|
43
|
+
"./host/otel": {
|
|
44
|
+
"types": "./dist/host/otel.d.ts",
|
|
45
|
+
"bun": "./src/host/otel.ts",
|
|
46
|
+
"default": "./dist/host/otel.js"
|
|
47
|
+
},
|
|
48
|
+
"./host/console": {
|
|
49
|
+
"types": "./dist/host/console.d.ts",
|
|
50
|
+
"bun": "./src/host/console.ts",
|
|
51
|
+
"default": "./dist/host/console.js"
|
|
52
|
+
}
|
|
53
|
+
},
|
|
54
|
+
"dependencies": {
|
|
55
|
+
"@intellectual-frontiers/core": "0.1.1",
|
|
56
|
+
"@intellectual-frontiers/formats": "0.1.1",
|
|
57
|
+
"@intellectual-frontiers/system": "0.1.0",
|
|
58
|
+
"@intellectual-frontiers/terminal": "0.1.1"
|
|
59
|
+
},
|
|
60
|
+
"files": [
|
|
61
|
+
"dist",
|
|
62
|
+
"src",
|
|
63
|
+
"README.md",
|
|
64
|
+
"LICENSE"
|
|
65
|
+
],
|
|
66
|
+
"repository": {
|
|
67
|
+
"type": "git",
|
|
68
|
+
"url": "git+https://github.com/intellectual-frontiers/.github.git",
|
|
69
|
+
"directory": "commons/telemetry"
|
|
70
|
+
},
|
|
71
|
+
"homepage": "https://github.com/intellectual-frontiers/.github/tree/main/commons/telemetry",
|
|
72
|
+
"bugs": {
|
|
73
|
+
"url": "https://github.com/intellectual-frontiers/.github/issues"
|
|
74
|
+
},
|
|
75
|
+
"publishConfig": {
|
|
76
|
+
"access": "public"
|
|
77
|
+
}
|
|
78
|
+
}
|
|
@@ -0,0 +1,253 @@
|
|
|
1
|
+
// Spec: 0001-telemetry FR-024
|
|
2
|
+
/**
|
|
3
|
+
* The console: the one code of IFC TypeScript that writes for a person to standard output or standard error (commons 0001-telemetry FR-024).
|
|
4
|
+
* It is a processor of the signal pipeline (`src/signals.ts`'s `Processor`): every span that starts, records progress or ends and every
|
|
5
|
+
* log record goes through the kernel's pure renderer (`src/render.ts`), and the frames it returns are written. The mode is the one asked
|
|
6
|
+
* for (the option, else `IFC_CONSOLE=attended|plain|quiet|silent|json`), else `attended` at a terminal and `plain` elsewhere
|
|
7
|
+
* (`system/tty`'s look decides what a terminal is, and whether colour and emoji may be used). In `attended` mode a timer, which never
|
|
8
|
+
* keeps the process alive, redraws the live region so elapsed times move. At shutdown it asks the exporting processors it watches to
|
|
9
|
+
* flush, says once, dimmed, where signals were not sent (FR-024), ends the live region and waits, a bounded time, for the writes to drain.
|
|
10
|
+
*
|
|
11
|
+
* `installUncaught` makes an uncaught exception or an unhandled rejection an error log record (`exception.type`, `exception.message`,
|
|
12
|
+
* `exception.stacktrace`) emitted through the telemetry, so it is rendered and exported like any other signal; the telemetry is then shut
|
|
13
|
+
* down (bounded) and the process exits with status 1. Its kind, `exception`, is declared in `uncaughtSignals`, to spread into a registry.
|
|
14
|
+
*
|
|
15
|
+
* It depends only on the kernel's interfaces, so it plugs into any telemetry.
|
|
16
|
+
*
|
|
17
|
+
* @example
|
|
18
|
+
* ```ts
|
|
19
|
+
* import { createTelemetry, defineSignals } from "../signals.ts";
|
|
20
|
+
* import { consoleProcessor, installUncaught, uncaughtSignals } from "./console.ts";
|
|
21
|
+
* const registry = defineSignals({ ...uncaughtSignals, "build.step": { signal: "span", role: "step", attributes: { target: "string" } } });
|
|
22
|
+
* const telemetry = createTelemetry({ registry, processors: [consoleProcessor({ registry })], ...rest });
|
|
23
|
+
* installUncaught(telemetry);
|
|
24
|
+
* ```
|
|
25
|
+
*
|
|
26
|
+
* @module
|
|
27
|
+
*/
|
|
28
|
+
import process from "node:process";
|
|
29
|
+
import { clearInterval, clearTimeout, setInterval, setTimeout } from "node:timers";
|
|
30
|
+
import type { AnyValue, Attributes } from "../otel.ts";
|
|
31
|
+
import { SEVERITY } from "../otel.ts";
|
|
32
|
+
import { chooseMode, initial, type Input, type Mode, parseMode, render, type State } from "../render.ts";
|
|
33
|
+
import { type Declarations, describeError, type FlushResult, type Processor, type ProcessorStats, type Registry } from "../signals.ts";
|
|
34
|
+
import { env, exit } from "@intellectual-frontiers/system/proc";
|
|
35
|
+
import { currentLook, type Look } from "@intellectual-frontiers/system/tty";
|
|
36
|
+
|
|
37
|
+
/** A processor whose exports the console watches, to say at the end where signals were not sent (an `ExportingProcessor`). */
|
|
38
|
+
export type Watched = { stats(): ProcessorStats; forceFlush(timeoutMs: number): Promise<FlushResult> };
|
|
39
|
+
|
|
40
|
+
/** How a console is made; everything but the registry has a default. */
|
|
41
|
+
export type ConsoleOptions = {
|
|
42
|
+
/** The registry that gives each kind its presentation role. */
|
|
43
|
+
readonly registry: Registry<Declarations>;
|
|
44
|
+
/** The mode; by default the one `IFC_CONSOLE` names, else `attended` at a terminal and `plain` elsewhere. */
|
|
45
|
+
readonly mode?: Mode;
|
|
46
|
+
/** The stream written to: standard error by default, standard output in `json` mode. */
|
|
47
|
+
readonly stream?: "stdout" | "stderr";
|
|
48
|
+
/** What the terminal shows; by default `currentLook` of the stream. */
|
|
49
|
+
readonly look?: Look;
|
|
50
|
+
/** The environment the mode is read from; this process's by default. */
|
|
51
|
+
readonly env?: Readonly<Record<string, string | undefined>>;
|
|
52
|
+
/** The exporting processors to ask, at shutdown, whether everything was sent. */
|
|
53
|
+
readonly exporters?: readonly Watched[];
|
|
54
|
+
/** How often the live region is redrawn, in milliseconds (200 by default). */
|
|
55
|
+
readonly tickMs?: number;
|
|
56
|
+
/** The time now, in nanoseconds since the Unix epoch, for elapsed times; the system's clock by default. */
|
|
57
|
+
readonly now?: () => bigint;
|
|
58
|
+
/** A signal's text from its kind and attributes (`render.ts`'s `defaultText` by default). */
|
|
59
|
+
readonly text?: (name: string, attributes: Attributes) => string;
|
|
60
|
+
};
|
|
61
|
+
|
|
62
|
+
/** The console: a processor, with its mode, and a way to add an export warning said at the end. */
|
|
63
|
+
export type ConsoleProcessor = Processor & {
|
|
64
|
+
/** The mode it writes in. */
|
|
65
|
+
readonly mode: Mode;
|
|
66
|
+
/** Keeps a warning about an export, said once, dimmed, at the end of the run (FR-024). */
|
|
67
|
+
warn(message: string): void;
|
|
68
|
+
};
|
|
69
|
+
|
|
70
|
+
const systemNow = (): bigint => BigInt(Date.now()) * 1_000_000n;
|
|
71
|
+
|
|
72
|
+
/** A promise that settles with `promise`, or with `fallback` once `ms` have passed; the timer never keeps the process alive. */
|
|
73
|
+
function within<T>(promise: Promise<T>, ms: number, fallback: T): Promise<T> {
|
|
74
|
+
return new Promise<T>((resolve) => {
|
|
75
|
+
const timer = setTimeout(() => resolve(fallback), Math.max(0, ms));
|
|
76
|
+
timer.unref();
|
|
77
|
+
void promise.then(
|
|
78
|
+
(v) => {
|
|
79
|
+
clearTimeout(timer);
|
|
80
|
+
resolve(v);
|
|
81
|
+
},
|
|
82
|
+
() => {
|
|
83
|
+
clearTimeout(timer);
|
|
84
|
+
resolve(fallback);
|
|
85
|
+
},
|
|
86
|
+
);
|
|
87
|
+
});
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
function unsent(stats: ProcessorStats): { readonly count: number; readonly lastError: string | undefined } {
|
|
91
|
+
let count = 0;
|
|
92
|
+
let lastError: string | undefined;
|
|
93
|
+
for (const s of [stats.traces, stats.logs, stats.metrics]) {
|
|
94
|
+
count += s.failed + s.dropped + s.rejected;
|
|
95
|
+
lastError = s.lastError ?? lastError;
|
|
96
|
+
}
|
|
97
|
+
return { count, lastError };
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/** A console processor: renders every signal it is handed and writes the frames for a person (FR-026). */
|
|
101
|
+
export function consoleProcessor(options: ConsoleOptions): ConsoleProcessor {
|
|
102
|
+
const vars = options.env ?? env.toObject();
|
|
103
|
+
const requested = options.mode ?? vars["IFC_CONSOLE"];
|
|
104
|
+
const asked = requested === undefined ? undefined : parseMode(requested);
|
|
105
|
+
const streamName = options.stream ?? (asked === "json" ? "stdout" : "stderr");
|
|
106
|
+
const look = options.look ?? currentLook(streamName);
|
|
107
|
+
const mode = options.mode ?? chooseMode({ requested, tty: look.tty });
|
|
108
|
+
const stream = streamName === "stdout" ? process.stdout : process.stderr;
|
|
109
|
+
const now = options.now ?? systemNow;
|
|
110
|
+
let state: State = initial({
|
|
111
|
+
mode,
|
|
112
|
+
look,
|
|
113
|
+
registry: options.registry,
|
|
114
|
+
...(options.text === undefined ? {} : { text: options.text }),
|
|
115
|
+
});
|
|
116
|
+
let timer: ReturnType<typeof setInterval> | undefined;
|
|
117
|
+
|
|
118
|
+
const write = (frames: string): void => {
|
|
119
|
+
if (frames === "") return;
|
|
120
|
+
try {
|
|
121
|
+
stream.write(frames);
|
|
122
|
+
} catch {
|
|
123
|
+
// A closed stream: nothing more can be shown, and the program goes on.
|
|
124
|
+
}
|
|
125
|
+
};
|
|
126
|
+
const feed = (input: Input): void => {
|
|
127
|
+
const step = render(state, input, now());
|
|
128
|
+
state = step.state;
|
|
129
|
+
write(step.frames);
|
|
130
|
+
if (mode === "attended" && timer === undefined && state.live.length > 0 && !state.finished) {
|
|
131
|
+
timer = setInterval(() => feed({ kind: "tick" }), Math.max(20, options.tickMs ?? 200));
|
|
132
|
+
timer.unref();
|
|
133
|
+
}
|
|
134
|
+
};
|
|
135
|
+
const stopTimer = (): void => {
|
|
136
|
+
if (timer !== undefined) clearInterval(timer);
|
|
137
|
+
timer = undefined;
|
|
138
|
+
};
|
|
139
|
+
const drained = (): Promise<void> =>
|
|
140
|
+
new Promise<void>((resolve) => {
|
|
141
|
+
try {
|
|
142
|
+
stream.write("", () => resolve());
|
|
143
|
+
} catch {
|
|
144
|
+
resolve();
|
|
145
|
+
}
|
|
146
|
+
});
|
|
147
|
+
|
|
148
|
+
return {
|
|
149
|
+
mode,
|
|
150
|
+
warn: (message) => feed({ kind: "export-warning", message }),
|
|
151
|
+
onStart: (span, source) => feed({ kind: "span-start", span, source }),
|
|
152
|
+
onEvent: (span, event, source) => feed({ kind: "span-event", span, event, source }),
|
|
153
|
+
onEnd: (span, source) => feed({ kind: "span-end", span, source }),
|
|
154
|
+
onLog: (record, source) => feed({ kind: "log", record, source }),
|
|
155
|
+
forceFlush: async (timeoutMs) => {
|
|
156
|
+
await within(drained(), timeoutMs, undefined);
|
|
157
|
+
return { kind: "done" };
|
|
158
|
+
},
|
|
159
|
+
shutdown: async (timeoutMs) => {
|
|
160
|
+
const started = Date.now();
|
|
161
|
+
const watched = options.exporters ?? [];
|
|
162
|
+
if (watched.length > 0) {
|
|
163
|
+
const flushed = await within(
|
|
164
|
+
Promise.all(watched.map((w) => w.forceFlush(timeoutMs))),
|
|
165
|
+
timeoutMs,
|
|
166
|
+
watched.map((): FlushResult => ({ kind: "timeout" })),
|
|
167
|
+
);
|
|
168
|
+
if (flushed.some((f) => f.kind === "timeout"))
|
|
169
|
+
feed({ kind: "export-warning", message: "the signals were not all sent: no collector answered in time" });
|
|
170
|
+
for (const w of watched) {
|
|
171
|
+
const u = unsent(w.stats());
|
|
172
|
+
if (u.count > 0) {
|
|
173
|
+
feed({
|
|
174
|
+
kind: "export-warning",
|
|
175
|
+
message: `${u.count} signals were not sent${u.lastError === undefined ? "" : `: ${u.lastError}`}`,
|
|
176
|
+
});
|
|
177
|
+
}
|
|
178
|
+
}
|
|
179
|
+
}
|
|
180
|
+
stopTimer();
|
|
181
|
+
feed({ kind: "finish" });
|
|
182
|
+
await within(drained(), Math.max(0, timeoutMs - (Date.now() - started)), undefined);
|
|
183
|
+
return { kind: "done" };
|
|
184
|
+
},
|
|
185
|
+
};
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
/** The kind of log record an uncaught exception or an unhandled rejection becomes, to spread into a registry. */
|
|
189
|
+
export const uncaughtSignals = {
|
|
190
|
+
exception: {
|
|
191
|
+
signal: "log",
|
|
192
|
+
role: "error",
|
|
193
|
+
severity: SEVERITY.FATAL,
|
|
194
|
+
description: "An uncaught exception or an unhandled rejection, after which the process exits with status 1.",
|
|
195
|
+
attributes: { "exception.type": "string", "exception.message": "string", "exception.stacktrace?": "string" },
|
|
196
|
+
},
|
|
197
|
+
} as const satisfies Declarations;
|
|
198
|
+
|
|
199
|
+
/** The attributes of an `exception` log record. */
|
|
200
|
+
export type ExceptionAttributes = {
|
|
201
|
+
readonly "exception.type": string;
|
|
202
|
+
readonly "exception.message": string;
|
|
203
|
+
readonly "exception.stacktrace"?: string;
|
|
204
|
+
};
|
|
205
|
+
|
|
206
|
+
/** What `installUncaught` needs of a telemetry: a `Telemetry` whose registry declares `uncaughtSignals` is one. */
|
|
207
|
+
export type UncaughtTarget = {
|
|
208
|
+
log(kind: "exception", attributes: ExceptionAttributes, body?: AnyValue): void;
|
|
209
|
+
shutdown(timeoutMs: number): Promise<FlushResult>;
|
|
210
|
+
};
|
|
211
|
+
|
|
212
|
+
/** How `installUncaught` ends the process: the most time the telemetry has to shut down, and the exit (`proc.exit` by default). */
|
|
213
|
+
export type UncaughtOptions = { readonly timeoutMs?: number; readonly exit?: (code: number) => void };
|
|
214
|
+
|
|
215
|
+
/** The attributes and the text of the error log record for a thrown value. */
|
|
216
|
+
export function exceptionOf(thrown: unknown): { readonly attributes: ExceptionAttributes; readonly text: string } {
|
|
217
|
+
const type = thrown instanceof Error ? thrown.name : typeof thrown;
|
|
218
|
+
const message = describeError(thrown);
|
|
219
|
+
const stack = thrown instanceof Error && thrown.stack !== undefined ? { "exception.stacktrace": thrown.stack } : {};
|
|
220
|
+
return { attributes: { "exception.type": type, "exception.message": message, ...stack }, text: `${type}: ${message}` };
|
|
221
|
+
}
|
|
222
|
+
|
|
223
|
+
/**
|
|
224
|
+
* On an uncaught exception or an unhandled rejection: an `exception` log record through the telemetry (so the console renders it), the
|
|
225
|
+
* telemetry shut down within `timeoutMs` (1000 by default), and exit status 1 (FR-026). A second one while this happens exits at once.
|
|
226
|
+
* Returns what removes the handlers.
|
|
227
|
+
*/
|
|
228
|
+
export function installUncaught(telemetry: UncaughtTarget, options: UncaughtOptions = {}): () => void {
|
|
229
|
+
const timeoutMs = options.timeoutMs ?? 1000;
|
|
230
|
+
const end = options.exit ?? ((code: number): void => exit(code));
|
|
231
|
+
let handling = false;
|
|
232
|
+
const handle = (thrown: unknown): void => {
|
|
233
|
+
if (handling) return end(1);
|
|
234
|
+
handling = true;
|
|
235
|
+
const e = exceptionOf(thrown);
|
|
236
|
+
try {
|
|
237
|
+
telemetry.log("exception", e.attributes, e.text);
|
|
238
|
+
} catch {
|
|
239
|
+
// A telemetry already shut down: the exit status still says it.
|
|
240
|
+
}
|
|
241
|
+
void within(
|
|
242
|
+
telemetry.shutdown(timeoutMs).then(() => undefined),
|
|
243
|
+
timeoutMs + 100,
|
|
244
|
+
undefined,
|
|
245
|
+
).then(() => end(1));
|
|
246
|
+
};
|
|
247
|
+
process.on("uncaughtException", handle);
|
|
248
|
+
process.on("unhandledRejection", handle);
|
|
249
|
+
return () => {
|
|
250
|
+
process.off("uncaughtException", handle);
|
|
251
|
+
process.off("unhandledRejection", handle);
|
|
252
|
+
};
|
|
253
|
+
}
|
package/src/host/mod.ts
ADDED
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
// Spec: 0001-telemetry FR-026
|
|
2
|
+
/**
|
|
3
|
+
* The host of Telemetry (its specification 0001-telemetry): the exporter over OTLP/HTTP JSON with its journal, its probe and the pipeline a process installs (as `otel`, with `startTelemetry`), and the console that
|
|
4
|
+
* renders signals for a person and is the one writer to standard output and standard error for that (as `console`). It names `node:` builtins and no vendor's global, and depends on the library `system` for
|
|
5
|
+
* the process, the terminal and the files.
|
|
6
|
+
*
|
|
7
|
+
* @example
|
|
8
|
+
* ```ts
|
|
9
|
+
* import { otel } from "@intellectual-frontiers/telemetry/host";
|
|
10
|
+
* const run = otel.startTelemetry({ registry, service: "build" });
|
|
11
|
+
* ```
|
|
12
|
+
*
|
|
13
|
+
* @module
|
|
14
|
+
*/
|
|
15
|
+
export * as console from "./console.ts";
|
|
16
|
+
export * as otel from "./otel.ts";
|