@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/dist/signals.js
ADDED
|
@@ -0,0 +1,800 @@
|
|
|
1
|
+
// Spec: 0001-telemetry FR-009
|
|
2
|
+
/**
|
|
3
|
+
* Typed signals and the pipeline they go through (commons 0001-telemetry FR-009 to FR-013). `defineSignals` declares each kind of signal
|
|
4
|
+
* once (a span, a log event, or a counter, up-down counter, gauge or histogram), with its attributes and their types, a log event's
|
|
5
|
+
* severity, a metric's unit and bounds, the attributes that are secret, and its presentation role; emitting a kind that is not declared,
|
|
6
|
+
* an attribute of the wrong type or a missing required attribute does not compile. `createTelemetry` makes the tracer, logger and meter of
|
|
7
|
+
* one resource and scope from what the caller gives (a clock, a source of random bytes, a context manager, a parent), so a span tree is
|
|
8
|
+
* the same every run; it redacts (FR-006), applies the limits (FR-007) and samples (FR-008), and hands every signal, in the order it was
|
|
9
|
+
* made, to its processors: the in-memory one, the simple one and the batch one, whose `forceFlush` and `shutdown` resolve within their
|
|
10
|
+
* time whatever an exporter does.
|
|
11
|
+
*
|
|
12
|
+
* @example
|
|
13
|
+
* ```ts
|
|
14
|
+
* import { createTelemetry, defineSignals, memoryProcessor } from "./signals.ts";
|
|
15
|
+
* import { ok } from "@intellectual-frontiers/core";
|
|
16
|
+
* const registry = defineSignals({
|
|
17
|
+
* "build.step": { signal: "span", role: "step", attributes: { target: "string", "jobs?": "int" } },
|
|
18
|
+
* "build.files": { signal: "counter", role: "none", unit: "{file}", attributes: { target: "string" } },
|
|
19
|
+
* });
|
|
20
|
+
* const memory = memoryProcessor();
|
|
21
|
+
* let t = 0n;
|
|
22
|
+
* const telemetry = createTelemetry({
|
|
23
|
+
* registry, resource: { attributes: { "service.name": "build" } }, scope: { name: "build" },
|
|
24
|
+
* clock: () => t++, random: (n) => new Uint8Array(n).fill(7), processors: [memory],
|
|
25
|
+
* });
|
|
26
|
+
* telemetry.span("build.step", { target: "site" }, () => {
|
|
27
|
+
* telemetry.add("build.files", 3, { target: "site" });
|
|
28
|
+
* return ok("built");
|
|
29
|
+
* });
|
|
30
|
+
* memory.spans[0]?.status; // { kind: "ok" }
|
|
31
|
+
* ```
|
|
32
|
+
*
|
|
33
|
+
* @module
|
|
34
|
+
*/
|
|
35
|
+
import { absurd, err, ok } from "@intellectual-frontiers/core";
|
|
36
|
+
import { toBase64 } from "@intellectual-frontiers/formats/base64";
|
|
37
|
+
import { DEFAULT_HISTOGRAM_BOUNDS, DEFAULT_LIMITS, DEFAULT_SAMPLER, formatTraceparent, formatTracestate, limitAttributes, mergeAttributes, redactAnyValue, redactAttributes, SAMPLED, severityText, shouldSample, spanIdFrom, traceIdFrom, } from "./otel.js";
|
|
38
|
+
import { countSignals } from "./otlp.js";
|
|
39
|
+
const ATTRIBUTE_TYPES = new Set([
|
|
40
|
+
"string",
|
|
41
|
+
"boolean",
|
|
42
|
+
"int",
|
|
43
|
+
"double",
|
|
44
|
+
"bytes",
|
|
45
|
+
"string[]",
|
|
46
|
+
"boolean[]",
|
|
47
|
+
"int[]",
|
|
48
|
+
"double[]",
|
|
49
|
+
]);
|
|
50
|
+
/**
|
|
51
|
+
* A registry of signal kinds (FR-009). The declarations are checked once here, and a mistake in them is a programming error that throws:
|
|
52
|
+
* an attribute type that does not exist, a secret attribute that is not declared, histogram bounds that do not increase.
|
|
53
|
+
*/
|
|
54
|
+
export function defineSignals(kinds) {
|
|
55
|
+
for (const [name, d] of Object.entries(kinds)) {
|
|
56
|
+
const declared = new Set(Object.keys(d.attributes).map((k) => k.replace(/\?$/, "")));
|
|
57
|
+
for (const [k, t] of Object.entries(d.attributes)) {
|
|
58
|
+
if (!ATTRIBUTE_TYPES.has(t))
|
|
59
|
+
throw new Error(`${name}: the attribute ${k} has the type ${t}, which does not exist`);
|
|
60
|
+
}
|
|
61
|
+
for (const s of d.secret ?? [])
|
|
62
|
+
if (!declared.has(s))
|
|
63
|
+
throw new Error(`${name}: the secret attribute ${s} is not declared`);
|
|
64
|
+
if (d.signal === "histogram" && d.bounds !== undefined) {
|
|
65
|
+
const b = d.bounds;
|
|
66
|
+
if (b.some((x, i) => !Number.isFinite(x) || (i > 0 && x <= (b[i - 1] ?? -Infinity)))) {
|
|
67
|
+
throw new Error(`${name}: the histogram bounds do not increase`);
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
return { kinds };
|
|
72
|
+
}
|
|
73
|
+
/** The presentation role of a kind, by its name (a span's name, a log record's `eventName`, a metric's name); undefined where not declared. */
|
|
74
|
+
export function roleOf(registry, name) {
|
|
75
|
+
return Object.hasOwn(registry.kinds, name) ? registry.kinds[name]?.role : undefined;
|
|
76
|
+
}
|
|
77
|
+
/** The declaration of a kind, by its name; undefined where not declared. */
|
|
78
|
+
export function declarationOf(registry, name) {
|
|
79
|
+
return Object.hasOwn(registry.kinds, name) ? registry.kinds[name] : undefined;
|
|
80
|
+
}
|
|
81
|
+
/**
|
|
82
|
+
* A context manager on a synchronous stack: correct for synchronous code and up to the first `await` of an asynchronous function. Past it,
|
|
83
|
+
* use the span handle's own `span` and `log`, which name their parent, or the runtime's `AsyncLocalStorage` manager.
|
|
84
|
+
*/
|
|
85
|
+
export function stackContextManager() {
|
|
86
|
+
let current;
|
|
87
|
+
return {
|
|
88
|
+
active: () => current,
|
|
89
|
+
with(context, fn) {
|
|
90
|
+
const previous = current;
|
|
91
|
+
current = context;
|
|
92
|
+
try {
|
|
93
|
+
return fn();
|
|
94
|
+
}
|
|
95
|
+
finally {
|
|
96
|
+
current = previous;
|
|
97
|
+
}
|
|
98
|
+
},
|
|
99
|
+
};
|
|
100
|
+
}
|
|
101
|
+
/** A processor that keeps every signal it receives (FR-012). */
|
|
102
|
+
export function memoryProcessor() {
|
|
103
|
+
const entries = [];
|
|
104
|
+
const done = () => Promise.resolve({ kind: "done" });
|
|
105
|
+
return {
|
|
106
|
+
onStart: (span, source) => void entries.push({ kind: "start", span, source }),
|
|
107
|
+
onEvent: (span, event, source) => void entries.push({ kind: "event", span, event, source }),
|
|
108
|
+
onEnd: (span, source) => void entries.push({ kind: "end", span, source }),
|
|
109
|
+
onLog: (record, source) => void entries.push({ kind: "log", record, source }),
|
|
110
|
+
onMetrics: (metrics, source) => void entries.push({ kind: "metrics", metrics, source }),
|
|
111
|
+
forceFlush: done,
|
|
112
|
+
shutdown: done,
|
|
113
|
+
get entries() {
|
|
114
|
+
return entries;
|
|
115
|
+
},
|
|
116
|
+
get spans() {
|
|
117
|
+
return entries.flatMap((e) => (e.kind === "end" ? [e.span] : []));
|
|
118
|
+
},
|
|
119
|
+
get logs() {
|
|
120
|
+
return entries.flatMap((e) => (e.kind === "log" ? [e.record] : []));
|
|
121
|
+
},
|
|
122
|
+
get metrics() {
|
|
123
|
+
return entries.flatMap((e) => (e.kind === "metrics" ? [e.metrics] : []));
|
|
124
|
+
},
|
|
125
|
+
clear: () => void entries.splice(0),
|
|
126
|
+
};
|
|
127
|
+
}
|
|
128
|
+
/** The host's timer; a scheduled export never keeps a process alive (`unref` where the host has it). */
|
|
129
|
+
export const systemTimer = {
|
|
130
|
+
set: (fn, ms) => {
|
|
131
|
+
const handle = setTimeout(fn, ms);
|
|
132
|
+
const unref = typeof handle === "object" && handle !== null ? Reflect.get(handle, "unref") : undefined;
|
|
133
|
+
if (typeof unref === "function")
|
|
134
|
+
Reflect.apply(unref, handle, []);
|
|
135
|
+
return handle;
|
|
136
|
+
},
|
|
137
|
+
// The handle is what `setTimeout` gave; its type differs between the DOM and Node.
|
|
138
|
+
clear: (handle) => clearTimeout(handle),
|
|
139
|
+
};
|
|
140
|
+
/** A promise's value, or `undefined` once `ms` have passed, whichever comes first; the timer is cleared either way. */
|
|
141
|
+
async function within(promise, ms) {
|
|
142
|
+
let handle;
|
|
143
|
+
const timeout = new Promise((resolve) => {
|
|
144
|
+
handle = setTimeout(() => resolve(undefined), Math.max(0, ms));
|
|
145
|
+
});
|
|
146
|
+
try {
|
|
147
|
+
return await Promise.race([promise.then((value) => ({ value })), timeout]);
|
|
148
|
+
}
|
|
149
|
+
finally {
|
|
150
|
+
clearTimeout(handle);
|
|
151
|
+
}
|
|
152
|
+
}
|
|
153
|
+
function describeThrown(e) {
|
|
154
|
+
return e instanceof Error ? e.message : String(e);
|
|
155
|
+
}
|
|
156
|
+
function newStats() {
|
|
157
|
+
const one = () => ({ exported: 0, failed: 0, rejected: 0, dropped: 0 });
|
|
158
|
+
return { traces: one(), logs: one(), metrics: one() };
|
|
159
|
+
}
|
|
160
|
+
function snapshot(stats) {
|
|
161
|
+
return { traces: { ...stats.traces }, logs: { ...stats.logs }, metrics: { ...stats.metrics } };
|
|
162
|
+
}
|
|
163
|
+
/** The exports of a processor: one at a time, in order, each within its timeout, never throwing, counted. */
|
|
164
|
+
function exportQueue(exportTimeoutMs) {
|
|
165
|
+
const stats = newStats();
|
|
166
|
+
let tail = Promise.resolve();
|
|
167
|
+
const send = async (signal, count, run) => {
|
|
168
|
+
const s = stats[signal];
|
|
169
|
+
let result;
|
|
170
|
+
try {
|
|
171
|
+
const r = await within(run(), exportTimeoutMs);
|
|
172
|
+
result = r === undefined ? { kind: "failure", message: `the export took more than ${exportTimeoutMs} ms` } : r.value;
|
|
173
|
+
}
|
|
174
|
+
catch (e) {
|
|
175
|
+
result = { kind: "failure", message: describeThrown(e) };
|
|
176
|
+
}
|
|
177
|
+
switch (result.kind) {
|
|
178
|
+
case "success":
|
|
179
|
+
s.exported += count;
|
|
180
|
+
return;
|
|
181
|
+
case "partial":
|
|
182
|
+
s.exported += count - result.rejected;
|
|
183
|
+
s.rejected += result.rejected;
|
|
184
|
+
s.lastError = result.message;
|
|
185
|
+
return;
|
|
186
|
+
case "failure":
|
|
187
|
+
s.failed += count;
|
|
188
|
+
s.lastError = result.message;
|
|
189
|
+
return;
|
|
190
|
+
default:
|
|
191
|
+
absurd(result);
|
|
192
|
+
}
|
|
193
|
+
};
|
|
194
|
+
return {
|
|
195
|
+
stats,
|
|
196
|
+
/** Sends one export now. */
|
|
197
|
+
send,
|
|
198
|
+
/** Queues an export after those already queued. */
|
|
199
|
+
push(signal, count, run) {
|
|
200
|
+
tail = tail.then(() => send(signal, count, run));
|
|
201
|
+
},
|
|
202
|
+
/** Settles when every export queued so far has. */
|
|
203
|
+
idle: () => tail,
|
|
204
|
+
};
|
|
205
|
+
}
|
|
206
|
+
function byTraceBatch(items) {
|
|
207
|
+
const out = new Map();
|
|
208
|
+
for (const i of items)
|
|
209
|
+
out.set(i.source, [...(out.get(i.source) ?? []), i.span]);
|
|
210
|
+
return [...out].map(([source, spans]) => ({ resource: source.resource, scope: source.scope, spans }));
|
|
211
|
+
}
|
|
212
|
+
function byLogBatch(items) {
|
|
213
|
+
const out = new Map();
|
|
214
|
+
for (const i of items)
|
|
215
|
+
out.set(i.source, [...(out.get(i.source) ?? []), i.record]);
|
|
216
|
+
return [...out].map(([source, records]) => ({ resource: source.resource, scope: source.scope, records }));
|
|
217
|
+
}
|
|
218
|
+
async function shutdownWithin(flushed, exporter, timeoutMs) {
|
|
219
|
+
const started = Date.now();
|
|
220
|
+
const first = await flushed;
|
|
221
|
+
const left = Math.max(0, timeoutMs - (Date.now() - started));
|
|
222
|
+
const stopped = await within(exporter.shutdown(left).catch(() => undefined), left);
|
|
223
|
+
return first.kind === "done" && stopped !== undefined ? first : { kind: "timeout" };
|
|
224
|
+
}
|
|
225
|
+
/** A processor that exports each signal as it comes, one export at a time (FR-012). */
|
|
226
|
+
export function simpleProcessor(exporter, options = {}) {
|
|
227
|
+
const queue = exportQueue(options.exportTimeoutMs ?? 30000);
|
|
228
|
+
let stopped = false;
|
|
229
|
+
const flush = async (timeoutMs) => (await within(queue.idle(), timeoutMs)) === undefined ? { kind: "timeout" } : { kind: "done" };
|
|
230
|
+
return {
|
|
231
|
+
onEnd: (span, source) => {
|
|
232
|
+
if (stopped)
|
|
233
|
+
return void queue.stats.traces.dropped++;
|
|
234
|
+
queue.push("traces", 1, () => exporter.exportTraces([{ resource: source.resource, scope: source.scope, spans: [span] }]));
|
|
235
|
+
},
|
|
236
|
+
onLog: (record, source) => {
|
|
237
|
+
if (stopped)
|
|
238
|
+
return void queue.stats.logs.dropped++;
|
|
239
|
+
queue.push("logs", 1, () => exporter.exportLogs([{ resource: source.resource, scope: source.scope, records: [record] }]));
|
|
240
|
+
},
|
|
241
|
+
onMetrics: (metrics, source) => {
|
|
242
|
+
const batches = [{ resource: source.resource, scope: source.scope, metrics }];
|
|
243
|
+
if (stopped)
|
|
244
|
+
return void (queue.stats.metrics.dropped += countSignals(batches));
|
|
245
|
+
queue.push("metrics", countSignals(batches), () => exporter.exportMetrics(batches));
|
|
246
|
+
},
|
|
247
|
+
forceFlush: flush,
|
|
248
|
+
shutdown: (timeoutMs) => {
|
|
249
|
+
stopped = true;
|
|
250
|
+
return shutdownWithin(flush(timeoutMs), exporter, timeoutMs);
|
|
251
|
+
},
|
|
252
|
+
stats: () => snapshot(queue.stats),
|
|
253
|
+
};
|
|
254
|
+
}
|
|
255
|
+
/**
|
|
256
|
+
* A processor that queues spans and log records (each at most `maxQueueSize`; what does not fit is dropped and counted, never blocking
|
|
257
|
+
* the caller) and exports them in batches of at most `maxExportBatchSize`: as soon as a full batch is waiting, else `scheduleDelayMs` after
|
|
258
|
+
* the first one queued. Metric collections are exported as they come. Exports run one at a time, each within `exportTimeoutMs`, and a
|
|
259
|
+
* batch leaves its queue only when it is sent (FR-012).
|
|
260
|
+
*/
|
|
261
|
+
export function batchProcessor(exporter, options = {}) {
|
|
262
|
+
const maxQueueSize = Math.max(1, options.maxQueueSize ?? 2048);
|
|
263
|
+
const maxBatch = Math.max(1, Math.min(options.maxExportBatchSize ?? 512, maxQueueSize));
|
|
264
|
+
const delay = options.scheduleDelayMs ?? 5000;
|
|
265
|
+
const timer = options.timer ?? systemTimer;
|
|
266
|
+
const queue = exportQueue(options.exportTimeoutMs ?? 30000);
|
|
267
|
+
const spans = [];
|
|
268
|
+
const logs = [];
|
|
269
|
+
const metrics = [];
|
|
270
|
+
let scheduled;
|
|
271
|
+
let pumping;
|
|
272
|
+
let all = false;
|
|
273
|
+
let stopped = false;
|
|
274
|
+
// The one worker: it takes a batch from a queue only when it is about to send it, so that a slow exporter fills the queues (and what
|
|
275
|
+
// does not fit is dropped) rather than memory.
|
|
276
|
+
const work = async () => {
|
|
277
|
+
// First let `pump` keep this promise, so that the end below, which runs with no pause after the last check, clears it.
|
|
278
|
+
await Promise.resolve();
|
|
279
|
+
for (;;) {
|
|
280
|
+
if (spans.length > 0 && (all || spans.length >= maxBatch)) {
|
|
281
|
+
const items = spans.splice(0, maxBatch);
|
|
282
|
+
await queue.send("traces", items.length, () => exporter.exportTraces(byTraceBatch(items)));
|
|
283
|
+
}
|
|
284
|
+
else if (logs.length > 0 && (all || logs.length >= maxBatch)) {
|
|
285
|
+
const items = logs.splice(0, maxBatch);
|
|
286
|
+
await queue.send("logs", items.length, () => exporter.exportLogs(byLogBatch(items)));
|
|
287
|
+
}
|
|
288
|
+
else {
|
|
289
|
+
const batches = metrics.shift();
|
|
290
|
+
if (batches === undefined)
|
|
291
|
+
break;
|
|
292
|
+
await queue.send("metrics", countSignals(batches), () => exporter.exportMetrics(batches));
|
|
293
|
+
}
|
|
294
|
+
}
|
|
295
|
+
all = false;
|
|
296
|
+
pumping = undefined;
|
|
297
|
+
if (spans.length > 0 || logs.length > 0)
|
|
298
|
+
arm();
|
|
299
|
+
};
|
|
300
|
+
const pump = () => {
|
|
301
|
+
pumping ??= work();
|
|
302
|
+
return pumping;
|
|
303
|
+
};
|
|
304
|
+
const arm = () => {
|
|
305
|
+
if (scheduled !== undefined || stopped)
|
|
306
|
+
return;
|
|
307
|
+
scheduled = {
|
|
308
|
+
handle: timer.set(() => {
|
|
309
|
+
scheduled = undefined;
|
|
310
|
+
all = true;
|
|
311
|
+
void pump();
|
|
312
|
+
}, delay),
|
|
313
|
+
};
|
|
314
|
+
};
|
|
315
|
+
const disarm = () => {
|
|
316
|
+
if (scheduled !== undefined)
|
|
317
|
+
timer.clear(scheduled.handle);
|
|
318
|
+
scheduled = undefined;
|
|
319
|
+
};
|
|
320
|
+
const enqueue = (items, item, stats) => {
|
|
321
|
+
if (stopped || items.length >= maxQueueSize) {
|
|
322
|
+
stats.dropped++;
|
|
323
|
+
return;
|
|
324
|
+
}
|
|
325
|
+
items.push(item);
|
|
326
|
+
if (items.length >= maxBatch)
|
|
327
|
+
void pump();
|
|
328
|
+
else
|
|
329
|
+
arm();
|
|
330
|
+
};
|
|
331
|
+
const flush = async (timeoutMs) => {
|
|
332
|
+
disarm();
|
|
333
|
+
all = true;
|
|
334
|
+
const r = await within(pump(), timeoutMs);
|
|
335
|
+
return r === undefined ? { kind: "timeout" } : { kind: "done" };
|
|
336
|
+
};
|
|
337
|
+
return {
|
|
338
|
+
onEnd: (span, source) => enqueue(spans, { span, source }, queue.stats.traces),
|
|
339
|
+
onLog: (record, source) => enqueue(logs, { record, source }, queue.stats.logs),
|
|
340
|
+
onMetrics: (collected, source) => {
|
|
341
|
+
const batches = [{ resource: source.resource, scope: source.scope, metrics: collected }];
|
|
342
|
+
if (stopped || metrics.length >= maxQueueSize)
|
|
343
|
+
return void (queue.stats.metrics.dropped += countSignals(batches));
|
|
344
|
+
metrics.push(batches);
|
|
345
|
+
void pump();
|
|
346
|
+
},
|
|
347
|
+
forceFlush: flush,
|
|
348
|
+
shutdown: (timeoutMs) => {
|
|
349
|
+
const flushed = flush(timeoutMs);
|
|
350
|
+
stopped = true;
|
|
351
|
+
disarm();
|
|
352
|
+
return shutdownWithin(flushed, exporter, timeoutMs);
|
|
353
|
+
},
|
|
354
|
+
stats: () => snapshot(queue.stats),
|
|
355
|
+
};
|
|
356
|
+
}
|
|
357
|
+
/** The description of an error for a span's status: a string as it is, an `Error`'s message, an object's `message`, else its JSON. */
|
|
358
|
+
export function describeError(error) {
|
|
359
|
+
if (typeof error === "string")
|
|
360
|
+
return error;
|
|
361
|
+
if (error instanceof Error)
|
|
362
|
+
return error.message;
|
|
363
|
+
if (typeof error === "object" && error !== null) {
|
|
364
|
+
if ("message" in error && typeof error.message === "string")
|
|
365
|
+
return error.message;
|
|
366
|
+
try {
|
|
367
|
+
return JSON.stringify(error, (_k, v) => (typeof v === "bigint" ? v.toString() : v));
|
|
368
|
+
}
|
|
369
|
+
catch {
|
|
370
|
+
return "an object that cannot be written as JSON";
|
|
371
|
+
}
|
|
372
|
+
}
|
|
373
|
+
return String(error);
|
|
374
|
+
}
|
|
375
|
+
function isThenable(value) {
|
|
376
|
+
return ((typeof value === "object" || typeof value === "function") && value !== null && "then" in value && typeof value.then === "function");
|
|
377
|
+
}
|
|
378
|
+
function statusOf(value) {
|
|
379
|
+
if (typeof value !== "object" || value === null || !("kind" in value))
|
|
380
|
+
return { kind: "unset" };
|
|
381
|
+
if (value.kind === "ok" && "value" in value)
|
|
382
|
+
return { kind: "ok" };
|
|
383
|
+
if (value.kind === "err" && "error" in value)
|
|
384
|
+
return { kind: "error", message: describeError(value.error) };
|
|
385
|
+
return { kind: "unset" };
|
|
386
|
+
}
|
|
387
|
+
function toInt(v) {
|
|
388
|
+
if (typeof v === "bigint")
|
|
389
|
+
return v;
|
|
390
|
+
return Number.isFinite(v) ? BigInt(Math.trunc(v)) : undefined;
|
|
391
|
+
}
|
|
392
|
+
/** Typed attributes as OpenTelemetry attributes, by the schema: an `int` as a `bigint`; an undeclared or absent attribute left out. */
|
|
393
|
+
export function toAttributes(schema, attributes) {
|
|
394
|
+
const out = {};
|
|
395
|
+
const given = { ...attributes };
|
|
396
|
+
for (const [declared, type] of Object.entries(schema)) {
|
|
397
|
+
const name = declared.replace(/\?$/, "");
|
|
398
|
+
const v = given[name];
|
|
399
|
+
if (v === undefined)
|
|
400
|
+
continue;
|
|
401
|
+
if (type === "int" && (typeof v === "number" || typeof v === "bigint")) {
|
|
402
|
+
const i = toInt(v);
|
|
403
|
+
if (i !== undefined)
|
|
404
|
+
out[name] = i;
|
|
405
|
+
}
|
|
406
|
+
else if (type === "int[]" && Array.isArray(v)) {
|
|
407
|
+
out[name] = v.flatMap((e) => {
|
|
408
|
+
const i = typeof e === "number" || typeof e === "bigint" ? toInt(e) : undefined;
|
|
409
|
+
return i === undefined ? [] : [i];
|
|
410
|
+
});
|
|
411
|
+
}
|
|
412
|
+
else if (isAttributeValue(v))
|
|
413
|
+
out[name] = v;
|
|
414
|
+
}
|
|
415
|
+
return out;
|
|
416
|
+
}
|
|
417
|
+
function isAttributeValue(v) {
|
|
418
|
+
if (typeof v === "string" || typeof v === "boolean" || typeof v === "bigint" || typeof v === "number" || v instanceof Uint8Array)
|
|
419
|
+
return true;
|
|
420
|
+
if (!Array.isArray(v))
|
|
421
|
+
return false;
|
|
422
|
+
const values = v;
|
|
423
|
+
const first = values[0];
|
|
424
|
+
return values.every((e) => typeof e === typeof first && ["string", "boolean", "bigint", "number"].includes(typeof e));
|
|
425
|
+
}
|
|
426
|
+
/** A canonical key of attributes, the same for equal sets in any order: one metric series for each (FR-013). */
|
|
427
|
+
export function attributesKey(attributes) {
|
|
428
|
+
const enc = (v) => {
|
|
429
|
+
if (typeof v === "bigint")
|
|
430
|
+
return `${v}n`;
|
|
431
|
+
if (v instanceof Uint8Array)
|
|
432
|
+
return `b64:${toBase64(v)}`;
|
|
433
|
+
if (Array.isArray(v))
|
|
434
|
+
return v.map((e) => (typeof e === "bigint" ? `${e}n` : e));
|
|
435
|
+
return typeof v === "string" ? `s:${v}` : v;
|
|
436
|
+
};
|
|
437
|
+
return JSON.stringify(Object.keys(attributes)
|
|
438
|
+
.sort()
|
|
439
|
+
.map((k) => [k, enc(attributes[k] ?? "")]));
|
|
440
|
+
}
|
|
441
|
+
/**
|
|
442
|
+
* The tracer, logger and meter of one resource and scope (FR-010 to FR-013). Every signal is redacted (the kind's secret attributes left
|
|
443
|
+
* out, credentials replaced), limited and handed to each processor in the order it was made. Ids come from `random`, times from `clock`.
|
|
444
|
+
*/
|
|
445
|
+
export function createTelemetry(options) {
|
|
446
|
+
const { registry, clock, random, processors } = options;
|
|
447
|
+
const source = { resource: options.resource, scope: options.scope };
|
|
448
|
+
const context = options.context ?? stackContextManager();
|
|
449
|
+
const sampler = options.sampler ?? DEFAULT_SAMPLER;
|
|
450
|
+
const limits = options.limits ?? DEFAULT_LIMITS;
|
|
451
|
+
const open = new Set();
|
|
452
|
+
const series = new Map();
|
|
453
|
+
let stopped = false;
|
|
454
|
+
const each = (f) => {
|
|
455
|
+
for (const p of processors) {
|
|
456
|
+
try {
|
|
457
|
+
f(p);
|
|
458
|
+
}
|
|
459
|
+
catch (e) {
|
|
460
|
+
options.onError?.(e);
|
|
461
|
+
}
|
|
462
|
+
}
|
|
463
|
+
};
|
|
464
|
+
const declaration = (kind) => {
|
|
465
|
+
const d = declarationOf(registry, kind);
|
|
466
|
+
if (d === undefined)
|
|
467
|
+
throw new Error(`the signal kind ${kind} is not declared`);
|
|
468
|
+
return d;
|
|
469
|
+
};
|
|
470
|
+
const newTraceId = () => {
|
|
471
|
+
const bytes = random(16);
|
|
472
|
+
const r = traceIdFrom(bytes);
|
|
473
|
+
if (r.kind === "ok")
|
|
474
|
+
return r.value;
|
|
475
|
+
const fixed = Uint8Array.from({ length: 16 }, (_, i) => bytes[i] ?? 0);
|
|
476
|
+
fixed[15] = 1;
|
|
477
|
+
const again = traceIdFrom(fixed);
|
|
478
|
+
if (again.kind === "err")
|
|
479
|
+
throw new Error(again.error);
|
|
480
|
+
return again.value;
|
|
481
|
+
};
|
|
482
|
+
const newSpanId = () => {
|
|
483
|
+
const bytes = random(8);
|
|
484
|
+
const r = spanIdFrom(bytes);
|
|
485
|
+
if (r.kind === "ok")
|
|
486
|
+
return r.value;
|
|
487
|
+
const fixed = Uint8Array.from({ length: 8 }, (_, i) => bytes[i] ?? 0);
|
|
488
|
+
fixed[7] = 1;
|
|
489
|
+
const again = spanIdFrom(fixed);
|
|
490
|
+
if (again.kind === "err")
|
|
491
|
+
throw new Error(again.error);
|
|
492
|
+
return again.value;
|
|
493
|
+
};
|
|
494
|
+
const clean = (attributes, secret) => limitAttributes(redactAttributes(attributes, secret), limits);
|
|
495
|
+
const addEvent = (o, name, attributes) => {
|
|
496
|
+
if (o.ended || !o.recording)
|
|
497
|
+
return;
|
|
498
|
+
if (o.events.length >= limits.eventCount) {
|
|
499
|
+
o.droppedEvents++;
|
|
500
|
+
return;
|
|
501
|
+
}
|
|
502
|
+
const a = clean(attributes, []);
|
|
503
|
+
const event = { name, time: clock(), attributes: a.attributes, droppedAttributesCount: a.dropped };
|
|
504
|
+
o.events.push(event);
|
|
505
|
+
each((p) => p.onEvent?.(o.start, event, source));
|
|
506
|
+
};
|
|
507
|
+
const end = (o, status) => {
|
|
508
|
+
if (o.ended)
|
|
509
|
+
return;
|
|
510
|
+
o.ended = true;
|
|
511
|
+
open.delete(o);
|
|
512
|
+
if (!o.recording)
|
|
513
|
+
return;
|
|
514
|
+
const s = o.start;
|
|
515
|
+
const data = {
|
|
516
|
+
name: s.name,
|
|
517
|
+
context: s.context,
|
|
518
|
+
...(s.parentSpanId === undefined ? {} : { parentSpanId: s.parentSpanId }),
|
|
519
|
+
kind: s.kind,
|
|
520
|
+
startTime: s.startTime,
|
|
521
|
+
endTime: clock(),
|
|
522
|
+
attributes: o.attributes,
|
|
523
|
+
events: [...o.events],
|
|
524
|
+
links: o.links,
|
|
525
|
+
status,
|
|
526
|
+
droppedAttributesCount: o.droppedAttributes,
|
|
527
|
+
droppedEventsCount: o.droppedEvents,
|
|
528
|
+
droppedLinksCount: o.droppedLinks,
|
|
529
|
+
};
|
|
530
|
+
each((p) => p.onEnd?.(data, source));
|
|
531
|
+
};
|
|
532
|
+
const fail = (o, thrown) => {
|
|
533
|
+
const message = describeError(thrown);
|
|
534
|
+
const type = thrown instanceof Error ? thrown.name : typeof thrown;
|
|
535
|
+
const stack = thrown instanceof Error && thrown.stack !== undefined ? { "exception.stacktrace": thrown.stack } : {};
|
|
536
|
+
addEvent(o, "exception", { "exception.type": type, "exception.message": message, ...stack });
|
|
537
|
+
end(o, { kind: "error", message });
|
|
538
|
+
};
|
|
539
|
+
const startSpan = (kind, attributes, explicitParent, links) => {
|
|
540
|
+
const d = declaration(kind);
|
|
541
|
+
if (d.signal !== "span")
|
|
542
|
+
throw new Error(`the signal kind ${kind} is not a span`);
|
|
543
|
+
const parent = explicitParent === null ? undefined : (explicitParent ?? context.active() ?? options.parent);
|
|
544
|
+
const traceId = parent?.traceId ?? newTraceId();
|
|
545
|
+
const sampled = !stopped && shouldSample(sampler, traceId, parent);
|
|
546
|
+
const flags = ((parent?.traceFlags ?? 0) & ~SAMPLED) | (sampled ? SAMPLED : 0);
|
|
547
|
+
const spanContext = {
|
|
548
|
+
traceId,
|
|
549
|
+
spanId: newSpanId(),
|
|
550
|
+
traceFlags: flags,
|
|
551
|
+
traceState: parent?.traceState ?? [],
|
|
552
|
+
isRemote: false,
|
|
553
|
+
};
|
|
554
|
+
const secret = d.secret ?? [];
|
|
555
|
+
const a = clean(toAttributes(d.attributes, attributes), secret);
|
|
556
|
+
const kept = links.slice(0, limits.linkCount).map((l) => {
|
|
557
|
+
const la = clean(l.attributes ?? {}, []);
|
|
558
|
+
return { ...l, attributes: la.attributes, droppedAttributesCount: la.dropped };
|
|
559
|
+
});
|
|
560
|
+
const start = {
|
|
561
|
+
name: kind,
|
|
562
|
+
context: spanContext,
|
|
563
|
+
...(parent === undefined ? {} : { parentSpanId: parent.spanId }),
|
|
564
|
+
kind: d.spanKind ?? "internal",
|
|
565
|
+
startTime: clock(),
|
|
566
|
+
attributes: a.attributes,
|
|
567
|
+
};
|
|
568
|
+
const o = {
|
|
569
|
+
start,
|
|
570
|
+
recording: sampled,
|
|
571
|
+
links: kept,
|
|
572
|
+
droppedLinks: Math.max(0, links.length - limits.linkCount),
|
|
573
|
+
secret,
|
|
574
|
+
attributes: a.attributes,
|
|
575
|
+
droppedAttributes: a.dropped,
|
|
576
|
+
events: [],
|
|
577
|
+
droppedEvents: 0,
|
|
578
|
+
ended: false,
|
|
579
|
+
};
|
|
580
|
+
open.add(o);
|
|
581
|
+
if (sampled)
|
|
582
|
+
each((p) => p.onStart?.(start, source));
|
|
583
|
+
return o;
|
|
584
|
+
};
|
|
585
|
+
const runSpan = (kind, attributes, fn, spanOptions, parent) => {
|
|
586
|
+
const o = startSpan(kind, attributes, spanOptions?.parent === undefined ? parent : spanOptions.parent, spanOptions?.links ?? []);
|
|
587
|
+
const handle = makeHandle(o);
|
|
588
|
+
let out;
|
|
589
|
+
try {
|
|
590
|
+
out = context.with(o.start.context, () => fn(handle));
|
|
591
|
+
}
|
|
592
|
+
catch (e) {
|
|
593
|
+
fail(o, e);
|
|
594
|
+
throw e;
|
|
595
|
+
}
|
|
596
|
+
if (isThenable(out)) {
|
|
597
|
+
const pending = out;
|
|
598
|
+
const settled = (async () => {
|
|
599
|
+
try {
|
|
600
|
+
const value = await pending;
|
|
601
|
+
end(o, statusOf(value));
|
|
602
|
+
return value;
|
|
603
|
+
}
|
|
604
|
+
catch (e) {
|
|
605
|
+
fail(o, e);
|
|
606
|
+
throw e;
|
|
607
|
+
}
|
|
608
|
+
})();
|
|
609
|
+
// `out` is a promise of T's value, and `settled` settles to that same value: it is the same type.
|
|
610
|
+
return settled;
|
|
611
|
+
}
|
|
612
|
+
end(o, statusOf(out));
|
|
613
|
+
return out;
|
|
614
|
+
};
|
|
615
|
+
const emitLog = (kind, attributes, body, active, logOptions) => {
|
|
616
|
+
const d = declaration(kind);
|
|
617
|
+
if (d.signal !== "log")
|
|
618
|
+
throw new Error(`the signal kind ${kind} is not a log event`);
|
|
619
|
+
if (stopped)
|
|
620
|
+
return;
|
|
621
|
+
const a = clean(toAttributes(d.attributes, attributes), d.secret ?? []);
|
|
622
|
+
const severity = logOptions?.severity ?? d.severity;
|
|
623
|
+
const time = clock();
|
|
624
|
+
const record = {
|
|
625
|
+
time,
|
|
626
|
+
observedTime: time,
|
|
627
|
+
severityNumber: severity,
|
|
628
|
+
severityText: severityText(severity),
|
|
629
|
+
...(body === undefined ? {} : { body: redactAnyValue(body) }),
|
|
630
|
+
attributes: a.attributes,
|
|
631
|
+
droppedAttributesCount: a.dropped,
|
|
632
|
+
eventName: kind,
|
|
633
|
+
...(active === undefined ? {} : { traceId: active.traceId, spanId: active.spanId, traceFlags: active.traceFlags }),
|
|
634
|
+
};
|
|
635
|
+
each((p) => p.onLog?.(record, source));
|
|
636
|
+
};
|
|
637
|
+
const makeHandle = (o) => {
|
|
638
|
+
const d = declaration(o.start.name);
|
|
639
|
+
return {
|
|
640
|
+
context: o.start.context,
|
|
641
|
+
recording: o.recording,
|
|
642
|
+
traceparent: formatTraceparent(o.start.context),
|
|
643
|
+
tracestate: formatTracestate(o.start.context.traceState),
|
|
644
|
+
set: (attributes) => {
|
|
645
|
+
if (o.ended || !o.recording)
|
|
646
|
+
return;
|
|
647
|
+
const added = redactAttributes(toAttributes(d.attributes, attributes), o.secret);
|
|
648
|
+
const merged = mergeAttributes(o.attributes, added, limits);
|
|
649
|
+
o.attributes = merged.attributes;
|
|
650
|
+
o.droppedAttributes += merged.dropped;
|
|
651
|
+
},
|
|
652
|
+
event: (name, attributes = {}) => addEvent(o, name, attributes),
|
|
653
|
+
progress: (done, total) => addEvent(o, "progress", total === undefined ? { "progress.done": done } : { "progress.done": done, "progress.total": total }),
|
|
654
|
+
span: (kind, attributes, fn, spanOptions) => runSpan(kind, attributes, fn, spanOptions, o.start.context),
|
|
655
|
+
log: (kind, attributes, body, logOptions) => emitLog(kind, attributes, body, o.start.context, logOptions),
|
|
656
|
+
};
|
|
657
|
+
};
|
|
658
|
+
const measure = (kind, allowed, value, attributes) => {
|
|
659
|
+
const d = declaration(kind);
|
|
660
|
+
if (!allowed.includes(d.signal))
|
|
661
|
+
return err(`the signal kind ${kind} is a ${d.signal}`);
|
|
662
|
+
if (!Number.isFinite(value))
|
|
663
|
+
return err(`${kind}: ${value} is not a finite number`);
|
|
664
|
+
if (d.signal === "counter" && value < 0)
|
|
665
|
+
return err(`${kind}: a counter does not take a negative increment (${value})`);
|
|
666
|
+
if (stopped)
|
|
667
|
+
return ok(undefined);
|
|
668
|
+
const a = clean(toAttributes(d.attributes, attributes), d.secret ?? []).attributes;
|
|
669
|
+
const key = attributesKey(a);
|
|
670
|
+
let byKey = series.get(kind);
|
|
671
|
+
if (byKey === undefined) {
|
|
672
|
+
byKey = new Map();
|
|
673
|
+
series.set(kind, byKey);
|
|
674
|
+
}
|
|
675
|
+
const time = clock();
|
|
676
|
+
let s = byKey.get(key);
|
|
677
|
+
if (s === undefined) {
|
|
678
|
+
const bounds = d.signal === "histogram" ? (d.bounds ?? DEFAULT_HISTOGRAM_BOUNDS) : [];
|
|
679
|
+
s = {
|
|
680
|
+
attributes: a,
|
|
681
|
+
startTime: time,
|
|
682
|
+
time,
|
|
683
|
+
value: 0,
|
|
684
|
+
count: 0,
|
|
685
|
+
sum: 0,
|
|
686
|
+
min: Infinity,
|
|
687
|
+
max: -Infinity,
|
|
688
|
+
buckets: bounds.map(() => 0).concat(0),
|
|
689
|
+
};
|
|
690
|
+
byKey.set(key, s);
|
|
691
|
+
}
|
|
692
|
+
s.time = time;
|
|
693
|
+
switch (d.signal) {
|
|
694
|
+
case "counter":
|
|
695
|
+
case "updown":
|
|
696
|
+
s.value += value;
|
|
697
|
+
break;
|
|
698
|
+
case "gauge":
|
|
699
|
+
s.value = value;
|
|
700
|
+
break;
|
|
701
|
+
case "histogram": {
|
|
702
|
+
const bounds = d.bounds ?? DEFAULT_HISTOGRAM_BOUNDS;
|
|
703
|
+
const i = bounds.findIndex((b) => value <= b);
|
|
704
|
+
const at = i < 0 ? bounds.length : i;
|
|
705
|
+
s.buckets[at] = (s.buckets[at] ?? 0) + 1;
|
|
706
|
+
s.count++;
|
|
707
|
+
s.sum += value;
|
|
708
|
+
s.min = Math.min(s.min, value);
|
|
709
|
+
s.max = Math.max(s.max, value);
|
|
710
|
+
break;
|
|
711
|
+
}
|
|
712
|
+
case "span":
|
|
713
|
+
case "log":
|
|
714
|
+
break;
|
|
715
|
+
default:
|
|
716
|
+
absurd(d);
|
|
717
|
+
}
|
|
718
|
+
return ok(undefined);
|
|
719
|
+
};
|
|
720
|
+
const collect = () => {
|
|
721
|
+
const time = clock();
|
|
722
|
+
const metrics = [];
|
|
723
|
+
for (const [kind, byKey] of series) {
|
|
724
|
+
const d = declaration(kind);
|
|
725
|
+
const all = [...byKey.values()];
|
|
726
|
+
const description = d.description ?? "";
|
|
727
|
+
const numberPoints = () => all.map((s) => ({ attributes: s.attributes, startTime: s.startTime, time, value: s.value }));
|
|
728
|
+
switch (d.signal) {
|
|
729
|
+
case "counter":
|
|
730
|
+
case "updown":
|
|
731
|
+
metrics.push({
|
|
732
|
+
name: kind,
|
|
733
|
+
description,
|
|
734
|
+
unit: d.unit,
|
|
735
|
+
data: { kind: "sum", temporality: "cumulative", monotonic: d.signal === "counter", points: numberPoints() },
|
|
736
|
+
});
|
|
737
|
+
break;
|
|
738
|
+
case "gauge":
|
|
739
|
+
metrics.push({ name: kind, description, unit: d.unit, data: { kind: "gauge", points: numberPoints() } });
|
|
740
|
+
break;
|
|
741
|
+
case "histogram": {
|
|
742
|
+
const bounds = d.bounds ?? DEFAULT_HISTOGRAM_BOUNDS;
|
|
743
|
+
const points = all.map((s) => ({
|
|
744
|
+
attributes: s.attributes,
|
|
745
|
+
startTime: s.startTime,
|
|
746
|
+
time,
|
|
747
|
+
count: s.count,
|
|
748
|
+
sum: s.sum,
|
|
749
|
+
...(s.count > 0 ? { min: s.min, max: s.max } : {}),
|
|
750
|
+
bounds,
|
|
751
|
+
bucketCounts: [...s.buckets],
|
|
752
|
+
}));
|
|
753
|
+
metrics.push({ name: kind, description, unit: d.unit, data: { kind: "histogram", temporality: "cumulative", points } });
|
|
754
|
+
break;
|
|
755
|
+
}
|
|
756
|
+
case "span":
|
|
757
|
+
case "log":
|
|
758
|
+
break;
|
|
759
|
+
default:
|
|
760
|
+
absurd(d);
|
|
761
|
+
}
|
|
762
|
+
}
|
|
763
|
+
if (metrics.length > 0)
|
|
764
|
+
each((p) => p.onMetrics?.(metrics, source));
|
|
765
|
+
return metrics;
|
|
766
|
+
};
|
|
767
|
+
const all = async (run, timeoutMs) => {
|
|
768
|
+
const settled = processors.map((p) => run(p).catch((e) => {
|
|
769
|
+
options.onError?.(e);
|
|
770
|
+
return { kind: "done" };
|
|
771
|
+
}));
|
|
772
|
+
const r = await within(Promise.all(settled), timeoutMs);
|
|
773
|
+
return r !== undefined && r.value.every((x) => x.kind === "done") ? { kind: "done" } : { kind: "timeout" };
|
|
774
|
+
};
|
|
775
|
+
return {
|
|
776
|
+
registry,
|
|
777
|
+
source,
|
|
778
|
+
active: () => context.active() ?? options.parent,
|
|
779
|
+
span: (kind, attributes, fn, spanOptions) => runSpan(kind, attributes, fn, spanOptions, undefined),
|
|
780
|
+
log: (kind, attributes, body, logOptions) => emitLog(kind, attributes, body, context.active() ?? options.parent, logOptions),
|
|
781
|
+
add: (kind, value, attributes) => measure(kind, ["counter", "updown"], value, attributes),
|
|
782
|
+
set: (kind, value, attributes) => measure(kind, ["gauge"], value, attributes),
|
|
783
|
+
record: (kind, value, attributes) => measure(kind, ["histogram"], value, attributes),
|
|
784
|
+
collect,
|
|
785
|
+
forceFlush: (timeoutMs) => {
|
|
786
|
+
if (!stopped)
|
|
787
|
+
collect();
|
|
788
|
+
return all((p) => p.forceFlush(timeoutMs), timeoutMs);
|
|
789
|
+
},
|
|
790
|
+
shutdown: (timeoutMs) => {
|
|
791
|
+
if (!stopped) {
|
|
792
|
+
for (const o of [...open])
|
|
793
|
+
end(o, { kind: "error", message: "the span was still open at shutdown" });
|
|
794
|
+
collect();
|
|
795
|
+
stopped = true;
|
|
796
|
+
}
|
|
797
|
+
return all((p) => p.shutdown(timeoutMs), timeoutMs);
|
|
798
|
+
},
|
|
799
|
+
};
|
|
800
|
+
}
|