Skip to content
Source
Sign inSign up
pingdotgg/t3code
Open History to see the last commit

observability.ts

874 lines26.9 KB

1import * as Cause from "effect/Cause";
2import * as Context from "effect/Context";
3import * as Effect from "effect/Effect";
4import type * as Exit from "effect/Exit";
5import * as ExitRuntime from "effect/Exit";
6import * as Option from "effect/Option";
7import * as Queue from "effect/Queue";
8import * as Result from "effect/Result";
9import * as Semaphore from "effect/Semaphore";
10import * as Schema from "effect/Schema";
11import * as SchemaIssue from "effect/SchemaIssue";
12import * as SchemaTransformation from "effect/SchemaTransformation";
13import * as Tracer from "effect/Tracer";
14import { OtlpResource, OtlpTracer, OtlpSerialization } from "effect/observability";
15​
16import { makeAsyncRotatingFileSink } from "./logging.ts";
17​
18export const OtlpProtocol = Schema.Literals(["http/json", "http/protobuf"]);
19export type OtlpProtocol = typeof OtlpProtocol.Type;
20export const layerOtlpSerialization = (protocol: OtlpProtocol) =>
21 protocol === "http/protobuf" ? OtlpSerialization.layerProtobuf : OtlpSerialization.layerJson;
22​
23export interface SignalExport {
24 readonly protocol: OtlpProtocol;
25 readonly headers: Readonly<Record<string, string>> | undefined;
26 readonly exportIntervalMs: number;
28​
29/**
30 * `process.runtime.*` resource attributes for a Node process, matching the
31 * OpenTelemetry Node process detector. Electron embeds Node, so an Electron
32 * process reports Node and names Electron in the description.
33 */
34export const nodeProcessRuntimeAttributes = (): Record<string, string> => ({
35 "process.runtime.name": "nodejs",
36 "process.runtime.version": process.versions.node,
37 "process.runtime.description": process.versions.electron
38 ? `Electron ${process.versions.electron}`
39 : "Node.js",
40});
41let generatedServiceInstanceId: string | undefined;
42​
43/**
44 * `service.instance.id` shared by every resource this process exports. Effect lets code
45 * attributes beat `OTEL_RESOURCE_ATTRIBUTES`, so callers pass the operator's in to keep it winning.
46 */
47export const processServiceInstanceId = (
48 operatorAttributes: Readonly<Record<string, string>> = {},
49): string => {
50 if (operatorAttributes["service.instance.id"]) return operatorAttributes["service.instance.id"];
51 // @effect-diagnostics-next-line cryptoRandomUUID:off -- Resources are built synchronously, outside any Effect.
52 generatedServiceInstanceId ??= crypto.randomUUID();
53 return generatedServiceInstanceId;
54};
55​
56export const DEFAULT_SIGNAL_EXPORT: SignalExport = {
57 protocol: "http/json",
58 headers: undefined,
59 exportIntervalMs: 10_000,
60};
61​
62const FLUSH_BUFFER_THRESHOLD = 256;
63​
64export type TraceAttributes = Readonly<Record<string, unknown>>;
65​
66export interface TraceRecordEvent {
67 readonly name: string;
68 readonly timeUnixNano: string;
69 readonly attributes: Readonly<Record<string, unknown>>;
71​
72export interface TraceRecordLink {
73 readonly traceId: string;
74 readonly spanId: string;
75 readonly attributes: Readonly<Record<string, unknown>>;
77​
78interface BaseTraceRecord {
79 readonly name: string;
80 readonly kind: string;
81 readonly traceId: string;
82 readonly spanId: string;
83 readonly parentSpanId?: string;
84 readonly sampled: boolean;
85 readonly startTimeUnixNano: string;
86 readonly endTimeUnixNano: string;
87 readonly durationMs: number;
88 readonly attributes: Readonly<Record<string, unknown>>;
89 readonly events: ReadonlyArray<TraceRecordEvent>;
90 readonly links: ReadonlyArray<TraceRecordLink>;
92​
93export interface EffectTraceRecord extends BaseTraceRecord {
94 readonly type: "effect-span";
95 readonly exit:
96 | {
97 readonly _tag: "Success";
98 }
99 | {
100 readonly _tag: "Interrupted";
101 readonly cause: string;
102 }
103 | {
104 readonly _tag: "Failure";
105 readonly cause: string;
106 };
108​
109export interface OtlpTraceRecord extends BaseTraceRecord {
110 readonly type: "otlp-span";
111 readonly resourceAttributes: Readonly<Record<string, unknown>>;
112 readonly scope: Readonly<{
113 readonly name?: string;
114 readonly version?: string;
115 readonly attributes: Readonly<Record<string, unknown>>;
116 }>;
117 readonly status?:
118 | {
119 readonly code?: string;
120 readonly message?: string;
121 }
122 | undefined;
124​
125export type TraceRecord = EffectTraceRecord | OtlpTraceRecord;
126​
127function isStructuralTag(value: unknown): value is string {
128 return (
129 typeof value === "string" &&
130 value.length > 0 &&
131 value.length <= 128 &&
132 /^[A-Za-z][A-Za-z0-9._:/-]*$/.test(value)
133 );
135​
136export function errorTag(error: unknown): string {
137 try {
138 if (typeof error === "object" && error !== null && "_tag" in error) {
139 return isStructuralTag(error._tag) ? error._tag : "TaggedError";
140 }
141 if (error instanceof Error) {
142 return isStructuralTag(error.name) ? error.name : "Error";
143 }
144 } catch {
145 return "UnknownError";
146 }
147 return typeof error;
149​
150export function causeErrorTag(cause: Cause.Cause<unknown>): string {
151 const failure = Cause.findErrorOption(cause);
152 if (Option.isSome(failure)) {
153 return errorTag(failure.value);
154 }
155 return cause.reasons[0]?._tag ?? "Empty";
157​
158export interface TraceSinkOptions {
159 readonly filePath: string;
160 readonly maxBytes: number;
161 readonly maxFiles: number;
162 readonly batchWindowMs: number;
163 readonly onFlush?: (stats: TraceSinkFlushStats) => Effect.Effect<void>;
165​
166export interface TraceSinkFlushStats {
167 readonly logicalWriteBytes: number;
168 readonly count: number;
169 readonly durationMs: number;
171​
172export interface TraceSink {
173 readonly filePath: string;
174 push: (record: TraceRecord) => void;
175 flush: Effect.Effect<void>;
176 close: () => Effect.Effect<void>;
178​
179export interface LocalFileTracerOptions extends TraceSinkOptions {
180 readonly delegate?: Tracer.Tracer;
181 readonly sink?: TraceSink;
183​
184type OtlpSpan = OtlpTracer.ScopeSpan["spans"][number];
185type OtlpSpanEvent = OtlpSpan["events"][number];
186type OtlpSpanLink = OtlpSpan["links"][number];
187type OtlpSpanStatus = OtlpSpan["status"];
188type OtlpScope = OtlpTracer.ScopeSpan["scope"];
189​
190interface SerializableSpan {
191 readonly name: string;
192 readonly traceId: string;
193 readonly spanId: string;
194 readonly parent: Option.Option<Tracer.AnySpan>;
195 readonly status: Tracer.SpanStatus;
196 readonly sampled: boolean;
197 readonly kind: Tracer.SpanKind;
198 readonly attributes: ReadonlyMap<string, unknown>;
199 readonly links: ReadonlyArray<Tracer.SpanLink>;
200 readonly events: ReadonlyArray<
201 readonly [name: string, startTime: bigint, attributes: Record<string, unknown>]
202 >;
204​
205function isPlainObject(value: unknown): value is Record<string, unknown> {
206 return typeof value === "object" && value !== null && !Array.isArray(value);
208​
209// Repeated references expand once per path, so a small shared graph can grow exponentially.
210const TRACE_ATTRIBUTE_MAX_NODES = 10_000;
211​
212interface NormalizeState {
213 // Only the current ancestors, so a value repeated under two keys is not a cycle.
214 readonly seen: WeakSet<object>;
215 remainingNodes: number;
217​
218function enterNode(value: object, state: NormalizeState): string | undefined {
219 if (state.seen.has(value)) {
220 return "[Circular]";
221 }
222 if (state.remainingNodes <= 0) {
223 return "[Truncated]";
224 }
225 state.remainingNodes--;
226 state.seen.add(value);
227 return undefined;
229​
230function normalizeJsonValue(value: unknown, state: NormalizeState): unknown {
231 if (
232 value === null ||
233 value === undefined ||
234 typeof value === "string" ||
235 typeof value === "number" ||
236 typeof value === "boolean"
237 ) {
238 return value ?? null;
239 }
240 if (typeof value === "bigint") {
241 return value.toString();
242 }
243 if (value instanceof Date) {
244 return Number.isNaN(value.getTime()) ? "Invalid Date" : value.toISOString();
245 }
246 if (value instanceof Error) {
247 return {
248 name: value.name,
249 message: value.message,
250 ...(value.stack ? { stack: value.stack } : {}),
251 };
252 }
253 if (Array.isArray(value)) {
254 const marker = enterNode(value, state);
255 if (marker) {
256 return marker;
257 }
258 const normalized = value.map((entry) => normalizeJsonValue(entry, state));
259 state.seen.delete(value);
260 return normalized;
261 }
262 if (value instanceof Map) {
263 const marker = enterNode(value, state);
264 if (marker) {
265 return marker;
266 }
267 const normalized = Object.fromEntries(
268 Array.from(value.entries(), ([key, entryValue]) => [
269 String(key),
270 normalizeJsonValue(entryValue, state),
271 ]),
272 );
273 state.seen.delete(value);
274 return normalized;
275 }
276 if (value instanceof Set) {
277 const marker = enterNode(value, state);
278 if (marker) {
279 return marker;
280 }
281 const normalized = Array.from(value.values(), (entry) => normalizeJsonValue(entry, state));
282 state.seen.delete(value);
283 return normalized;
284 }
285 if (!isPlainObject(value)) {
286 return String(value);
287 }
288 const marker = enterNode(value, state);
289 if (marker) {
290 return marker;
291 }
292 const normalized = Object.fromEntries(
293 Object.entries(value).map(([key, entryValue]) => [key, normalizeJsonValue(entryValue, state)]),
294 );
295 state.seen.delete(value);
296 return normalized;
298​
299export function compactTraceAttributes(
300 attributes: Readonly<Record<string, unknown>>,
301): TraceAttributes {
302 const state: NormalizeState = { seen: new WeakSet(), remainingNodes: TRACE_ATTRIBUTE_MAX_NODES };
303 const entries: Array<[string, unknown]> = [];
304 for (const [key, value] of Object.entries(attributes)) {
305 if (value !== undefined) {
306 entries.push([key, normalizeJsonValue(value, state)]);
307 }
308 }
309 return Object.fromEntries(entries);
311​
312function formatTraceExit(exit: Exit.Exit<unknown, unknown>): EffectTraceRecord["exit"] {
313 if (ExitRuntime.isSuccess(exit)) {
314 return { _tag: "Success" };
315 }
316 if (Cause.hasInterruptsOnly(exit.cause)) {
317 return {
318 _tag: "Interrupted",
319 cause: Cause.pretty(exit.cause),
320 };
321 }
322 return {
323 _tag: "Failure",
324 cause: Cause.pretty(exit.cause),
325 };
327​
328const TRACE_ATTRIBUTE_MAX_LENGTH = 500;
329const TRACE_ATTRIBUTE_TRUNCATED_LENGTH = 200;
330const TRACE_ATTRIBUTE_TRUNCATION_SUFFIX = "…[truncated]";
331const ALWAYS_TRUNCATED_TRACE_ATTRIBUTES: ReadonlySet<string> = new Set(["db.query.text"]);
332​
333function truncateNestedValue(value: unknown): unknown {
334 if (typeof value === "string") {
335 return value.length <= TRACE_ATTRIBUTE_MAX_LENGTH
336 ? value
337 : `${value.slice(0, TRACE_ATTRIBUTE_MAX_LENGTH)}${TRACE_ATTRIBUTE_TRUNCATION_SUFFIX}`;
338 }
339 if (Array.isArray(value)) {
340 const truncated = value.map(truncateNestedValue);
341 return truncated.some((entry, index) => entry !== value[index]) ? truncated : value;
342 }
343 if (isPlainObject(value)) {
344 let truncated: Record<string, unknown> | undefined;
345 for (const [key, entry] of Object.entries(value)) {
346 const next = truncateNestedValue(entry);
347 if (next === entry) continue;
348 truncated ??= { ...value };
349 truncated[key] = next;
350 }
351 return truncated ?? value;
352 }
353 return value;
355​
356/** Clones only when clamping; never mutates attributes shared with other tracers. */
357export function truncateTraceAttributes(attributes: TraceAttributes): TraceAttributes {
358 let truncated: Record<string, unknown> | undefined;
359 for (const [key, value] of Object.entries(attributes)) {
360 if (typeof value === "string" && ALWAYS_TRUNCATED_TRACE_ATTRIBUTES.has(key)) {
361 if (value.length <= TRACE_ATTRIBUTE_TRUNCATED_LENGTH) continue;
362 truncated ??= { ...attributes };
363 truncated[key] =
364 `${value.slice(0, TRACE_ATTRIBUTE_TRUNCATED_LENGTH)}${TRACE_ATTRIBUTE_TRUNCATION_SUFFIX}`;
365 continue;
366 }
367 const next = truncateNestedValue(value);
368 if (next === value) continue;
369 truncated ??= { ...attributes };
370 truncated[key] = next;
371 }
372 return truncated ?? attributes;
374​
375function spanToTraceRecord(span: SerializableSpan): EffectTraceRecord {
376 const status = span.status as Extract<Tracer.SpanStatus, { _tag: "Ended" }>;
377 const parentSpanId = Option.getOrUndefined(span.parent)?.spanId;
378​
379 return {
380 type: "effect-span",
381 name: span.name,
382 traceId: span.traceId,
383 spanId: span.spanId,
384 ...(parentSpanId ? { parentSpanId } : {}),
385 sampled: span.sampled,
386 kind: span.kind,
387 startTimeUnixNano: String(status.startTime),
388 endTimeUnixNano: String(status.endTime),
389 durationMs: Number(status.endTime - status.startTime) / 1_000_000,
390 attributes: truncateTraceAttributes(
391 compactTraceAttributes(Object.fromEntries(span.attributes)),
392 ),
393 events: span.events.map(([name, startTime, attributes]) => ({
394 name,
395 timeUnixNano: String(startTime),
396 attributes: truncateTraceAttributes(compactTraceAttributes(attributes)),
397 })),
398 links: span.links.map((link) => ({
399 traceId: link.span.traceId,
400 spanId: link.span.spanId,
401 attributes: truncateTraceAttributes(compactTraceAttributes(link.attributes)),
402 })),
403 exit: formatTraceExit(status.exit),
404 };
406​
407// WebSocket tickets and their DPoP proofs ride in URL queries and stay valid after the request.
408const URL_CREDENTIAL_PARAMS = /(^|[?&"\s])(wsTicket|dpop)=[^&#"\\\s]*/g;
409​
410const redactUrlCredentials = (text: string) =>
411 text.replace(URL_CREDENTIAL_PARAMS, "$1$2=<redacted>");
412​
413export const makeTraceSink = Effect.fn("makeTraceSink")(function* (options: TraceSinkOptions) {
414 const sink = yield* makeAsyncRotatingFileSink({
415 filePath: options.filePath,
416 maxBytes: options.maxBytes,
417 maxFiles: options.maxFiles,
418 }).pipe(Effect.orDie);
419​
420 let buffer: Array<{ readonly text: string; readonly bytes: number }> = [];
421 let bufferBytes = 0;
422 const maxBufferBytes = Math.max(options.maxBytes, 4 * 1024 * 1024);
423 const flushRequests = yield* Queue.sliding<void>(1);
424 const flushSemaphore = yield* Semaphore.make(1);
425 let writeFailing = false;
426 let droppedCount = 0;
427 let failureReported = false;
428 let pendingFlushStats: TraceSinkFlushStats = {
429 logicalWriteBytes: 0,
430 count: 0,
431 durationMs: 0,
432 };
433​
434 const flushBuffered = Effect.gen(function* () {
435 if (buffer.length === 0) {
436 return;
437 }
438​
439 const records = buffer;
440 buffer = [];
441 bufferBytes = 0;
442 let persistedCount = 0;
443​
444 while (persistedCount < records.length) {
445 const firstRecordBytes = records[persistedCount]!.bytes;
446 let nextIndex = persistedCount + 1;
447 let chunkBytes = firstRecordBytes;
448 while (nextIndex < records.length) {
449 const nextRecordBytes = records[nextIndex]!.bytes;
450 if (chunkBytes + nextRecordBytes > options.maxBytes) break;
451 chunkBytes += nextRecordBytes;
452 nextIndex += 1;
453 }
454​
455 const chunk = records
456 .slice(persistedCount, nextIndex)
457 .map((record) => record.text)
458 .join("");
459 const startedAt = performance.now();
460 const written = yield* sink.write(chunk).pipe(Effect.result);
461 if (Result.isFailure(written)) {
462 // Drop the batch after disk failure to avoid an ever-growing retry backlog.
463 writeFailing = true;
464 droppedCount += records.length - persistedCount;
465 return;
466 }
467 writeFailing = false;
468 pendingFlushStats = {
469 logicalWriteBytes: pendingFlushStats.logicalWriteBytes + chunkBytes,
470 count: pendingFlushStats.count + nextIndex - persistedCount,
471 durationMs: pendingFlushStats.durationMs + Math.max(0, performance.now() - startedAt),
472 };
473 persistedCount = nextIndex;
474 }
475 });
476​
477 const flush = flushSemaphore
478 .withPermits(1)(
479 Effect.gen(function* () {
480 const droppedAtStart = droppedCount;
481 yield* flushBuffered;
482 const stats = pendingFlushStats;
483 pendingFlushStats = {
484 logicalWriteBytes: 0,
485 count: 0,
486 durationMs: 0,
487 };
488 if (stats.count > 0 && options.onFlush) {
489 yield* options.onFlush(stats).pipe(Effect.ignore);
490 }
491 if (droppedCount > 0 && !failureReported) {
492 failureReported = true;
493 yield* Effect.logWarning(
494 "Trace writer could not keep up, dropping records until it recovers",
495 {
496 filePath: options.filePath,
497 },
498 );
499 } else if (failureReported && !writeFailing && droppedCount === droppedAtStart) {
500 yield* Effect.logInfo("Trace writes recovered", {
501 filePath: options.filePath,
502 droppedCount,
503 });
504 failureReported = false;
505 droppedCount = 0;
506 }
507 }),
508 )
509 .pipe(
510 // Cancelled OS writes still finish; await completion before rotation or finalizer drain.
511 Effect.uninterruptible,
512 Effect.withTracerEnabled(false),
513 // Drop the ended makeTraceSink parent span so timed-fiber logs cannot accumulate on it.
514 Effect.updateContext(Context.omit(Tracer.ParentSpan)<never>),
515 );
516​
517 yield* Effect.addFinalizer(() => flush.pipe(Effect.ignore));
518 yield* Effect.forkScoped(
519 Queue.take(flushRequests).pipe(
520 Effect.timeoutOption(`${options.batchWindowMs} millis`),
521 Effect.andThen(flush),
522 Effect.forever,
523 ),
524 );
525​
526 return {
527 filePath: options.filePath,
528 push(record) {
529 try {
530 const text = `${redactUrlCredentials(JSON.stringify(record))}\n`;
531 const bytes = Buffer.byteLength(text);
532 if (bytes > options.maxBytes) return;
533 if (bufferBytes + bytes > maxBufferBytes) {
534 droppedCount++;
535 return;
536 }
537 buffer.push({ text, bytes });
538 bufferBytes += bytes;
539 if (buffer.length >= FLUSH_BUFFER_THRESHOLD) {
540 Queue.offerUnsafe(flushRequests, undefined);
541 }
542 } catch {
543 return;
544 }
545 },
546 flush,
547 close: () => flush,
548 } satisfies TraceSink;
549});
550​
551// Effect's HTTP errors, including failed upgrades, put the request URL in their message.
552export function redactCauseCredentials(cause: Cause.Cause<unknown>): Cause.Cause<unknown> {
553 if (cause.reasons.length === 0 || Cause.hasInterruptsOnly(cause)) {
554 return cause;
555 }
556 const pretty = Cause.pretty(cause);
557 const redacted = redactUrlCredentials(pretty);
558 return redacted === pretty ? cause : Cause.die(new Error(redacted));
560​
561function redactExitCredentials(exit: Exit.Exit<unknown, unknown>): Exit.Exit<unknown, unknown> {
562 if (ExitRuntime.isSuccess(exit)) {
563 return exit;
564 }
565 const cause = redactCauseCredentials(exit.cause);
566 return cause === exit.cause ? exit : ExitRuntime.failCause(cause);
568​
569class LocalFileSpan implements Tracer.Span {
570 readonly _tag = "Span";
571 readonly name: string;
572 readonly spanId: string;
573 readonly traceId: string;
574 readonly parent: Option.Option<Tracer.AnySpan>;
575 readonly annotations: Tracer.Span["annotations"];
576 readonly links: Array<Tracer.SpanLink>;
577 readonly sampled: boolean;
578 readonly kind: Tracer.SpanKind;
579​
580 status: Tracer.SpanStatus;
581 attributes: Map<string, unknown>;
582 events: Array<[name: string, startTime: bigint, attributes: Record<string, unknown>]>;
583 private readonly delegate: Tracer.Span;
584 private readonly push: (record: EffectTraceRecord) => void;
585​
586 constructor(
587 options: Parameters<Tracer.Tracer["span"]>[0],
588 delegate: Tracer.Span,
589 push: (record: EffectTraceRecord) => void,
590 ) {
591 this.delegate = delegate;
592 this.push = push;
593 this.name = delegate.name;
594 this.spanId = delegate.spanId;
595 this.traceId = delegate.traceId;
596 this.parent = options.parent;
597 this.annotations = options.annotations;
598 this.links = [...options.links];
599 this.sampled = delegate.sampled;
600 this.kind = delegate.kind;
601 this.status = {
602 _tag: "Started",
603 startTime: options.startTime,
604 };
605 this.attributes = new Map();
606 this.events = [];
607 }
608​
609 end(endTime: bigint, exit: Exit.Exit<unknown, unknown>): void {
610 // Cached lookup fibers retain parent spans. Traces need success status, not result payloads.
611 const traceExit = ExitRuntime.isSuccess(exit) ? ExitRuntime.void : exit;
612 this.status = {
613 _tag: "Ended",
614 startTime: this.status.startTime,
615 endTime,
616 exit: traceExit,
617 };
618 this.delegate.end(endTime, redactExitCredentials(traceExit));
619​
620 if (this.sampled) {
621 this.push(spanToTraceRecord(this));
622 }
623 }
624​
625 attribute(key: string, value: unknown): void {
626 const recorded =
627 (key === "url.full" || key === "url.query") && typeof value === "string"
628 ? redactUrlCredentials(value)
629 : value;
630 this.attributes.set(key, recorded);
631 this.delegate.attribute(key, recorded);
632 }
633​
634 event(name: string, startTime: bigint, attributes?: Record<string, unknown>): void {
635 const cause = attributes?.["effect.cause"];
636 const nextAttributes =
637 typeof cause === "string"
638 ? { ...attributes, "effect.cause": redactUrlCredentials(cause) }
639 : (attributes ?? {});
640 this.events.push([name, startTime, nextAttributes]);
641 this.delegate.event(name, startTime, nextAttributes);
642 }
643​
644 addLinks(links: ReadonlyArray<Tracer.SpanLink>): void {
645 this.links.push(...links);
646 this.delegate.addLinks(links);
647 }
649​
650export const makeLocalFileTracer = Effect.fn("makeLocalFileTracer")(function* (
651 options: LocalFileTracerOptions,
652) {
653 const sink =
654 options.sink ??
655 (yield* makeTraceSink({
656 filePath: options.filePath,
657 maxBytes: options.maxBytes,
658 maxFiles: options.maxFiles,
659 batchWindowMs: options.batchWindowMs,
660 ...(options.onFlush ? { onFlush: options.onFlush } : {}),
661 }));
662​
663 const delegate =
664 options.delegate ??
665 Tracer.make({
666 span: (spanOptions) => new Tracer.NativeSpan(spanOptions),
667 });
668​
669 return Tracer.make({
670 span(spanOptions) {
671 return new LocalFileSpan(spanOptions, delegate.span(spanOptions), sink.push);
672 },
673 ...(delegate.context ? { context: delegate.context } : {}),
674 });
675});
676​
677const SPAN_KIND_MAP: Record<number, OtlpTraceRecord["kind"]> = {
678 1: "internal",
679 2: "server",
680 3: "client",
681 4: "producer",
682 5: "consumer",
683};
684​
685export function decodeOtlpTraceRecords(
686 payload: OtlpTracer.TraceData,
687): ReadonlyArray<OtlpTraceRecord> {
688 const records: Array<OtlpTraceRecord> = [];
689​
690 // OTLP/JSON follows protobuf JSON, which omits unset and empty fields, so a
691 // valid batch can leave out any field read here.
692 for (const resourceSpan of payload.resourceSpans ?? []) {
693 const resourceAttributes = decodeAttributes(resourceSpan.resource?.attributes);
694​
695 for (const scopeSpan of resourceSpan.scopeSpans ?? []) {
696 const scope: Partial<OtlpScope> = scopeSpan.scope ?? {};
697 for (const span of scopeSpan.spans ?? []) {
698 records.push(
699 otlpSpanToTraceRecord({
700 resourceAttributes,
701 scopeAttributes: decodeAttributes(
702 "attributes" in scope && Array.isArray(scope.attributes) ? scope.attributes : [],
703 ),
704 scopeName: scope.name,
705 scopeVersion: typeof scope.version === "string" ? scope.version : undefined,
706 span,
707 }),
708 );
709 }
710 }
711 }
712​
713 return records;
715​
716function otlpSpanToTraceRecord(input: {
717 readonly resourceAttributes: Readonly<Record<string, unknown>>;
718 readonly scopeAttributes: Readonly<Record<string, unknown>>;
719 readonly scopeName: string | undefined;
720 readonly scopeVersion: string | undefined;
721 readonly span: OtlpSpan;
722}): OtlpTraceRecord {
723 return {
724 type: "otlp-span",
725 name: input.span.name,
726 traceId: input.span.traceId,
727 spanId: input.span.spanId,
728 ...(input.span.parentSpanId ? { parentSpanId: input.span.parentSpanId } : {}),
729 sampled: true,
730 kind: normalizeSpanKind(input.span.kind),
731 startTimeUnixNano: input.span.startTimeUnixNano,
732 endTimeUnixNano: input.span.endTimeUnixNano,
733 durationMs:
734 Number(parseBigInt(input.span.endTimeUnixNano) - parseBigInt(input.span.startTimeUnixNano)) /
735 1_000_000,
736 attributes: decodeAttributes(input.span.attributes),
737 resourceAttributes: input.resourceAttributes,
738 scope: {
739 ...(input.scopeName ? { name: input.scopeName } : {}),
740 ...(input.scopeVersion ? { version: input.scopeVersion } : {}),
741 attributes: input.scopeAttributes,
742 },
743 events: decodeEvents(input.span.events),
744 links: decodeLinks(input.span.links),
745 status: decodeStatus(input.span.status),
746 };
748​
749function decodeStatus(input: OtlpSpanStatus | undefined): OtlpTraceRecord["status"] {
750 const code = String(input?.code ?? 0);
751 const message = input?.message;
752​
753 return {
754 code,
755 ...(message ? { message } : {}),
756 };
758​
759function decodeEvents(
760 input: ReadonlyArray<OtlpSpanEvent> | undefined,
761): ReadonlyArray<TraceRecordEvent> {
762 return (input ?? []).map((current) => ({
763 name: current.name,
764 timeUnixNano: current.timeUnixNano,
765 attributes: decodeAttributes(current.attributes),
766 }));
768​
769function decodeLinks(
770 input: ReadonlyArray<OtlpSpanLink> | undefined,
771): ReadonlyArray<TraceRecordLink> {
772 return (input ?? []).flatMap((current) => {
773 const traceId = current.traceId;
774 const spanId = current.spanId;
775 return {
776 traceId,
777 spanId,
778 attributes: decodeAttributes(current.attributes),
779 };
780 });
782​
783function decodeAttributes(
784 input: ReadonlyArray<OtlpResource.KeyValue> | undefined,
785): Readonly<Record<string, unknown>> {
786 const entries: Record<string, unknown> = {};
787​
788 for (const attribute of input ?? []) {
789 entries[attribute.key] = decodeValue(attribute.value);
790 }
791​
792 return truncateTraceAttributes(compactTraceAttributes(entries));
794​
795function decodeValue(input: OtlpResource.AnyValue | null | undefined): unknown {
796 if (input == null) {
797 return null;
798 }
799 if ("stringValue" in input) {
800 return input.stringValue;
801 }
802 if ("boolValue" in input) {
803 return input.boolValue;
804 }
805 if ("intValue" in input) {
806 return input.intValue;
807 }
808 if ("doubleValue" in input) {
809 return input.doubleValue;
810 }
811 if ("bytesValue" in input) {
812 return input.bytesValue;
813 }
814 if (input.arrayValue) {
815 return (input.arrayValue.values ?? []).map((entry) => decodeValue(entry));
816 }
817 if (input.kvlistValue) {
818 return decodeAttributes(input.kvlistValue.values);
819 }
820 return null;
822​
823function normalizeSpanKind(input: number): OtlpTraceRecord["kind"] {
824 return SPAN_KIND_MAP[input] || "internal";
826​
827function parseBigInt(input: string): bigint {
828 try {
829 return BigInt(input);
830 } catch {
831 return 0n;
832 }
834​
835export const OtlpHeadersFromString = Schema.String.pipe(
836 Schema.decodeTo(
837 Schema.Record(Schema.String, Schema.String),
838 SchemaTransformation.transformEffect({
839 decode: (input) => {
840 const headers: Record<string, string> = {};
841 for (const pair of input.split(",")) {
842 if (pair.trim() === "") {
843 continue;
844 }
845 const separator = pair.indexOf("=");
846 const key = separator === -1 ? "" : pair.slice(0, separator).trim();
847 if (key === "") {
848 return Effect.fail(
849 new SchemaIssue.InvalidValue({
850 message: `Expected key=value but received ${JSON.stringify(pair.trim())}.`,
851 }),
852 );
853 }
854 try {
855 headers[key] = decodeURIComponent(pair.slice(separator + 1).trim());
856 } catch {
857 return Effect.fail(
858 new SchemaIssue.InvalidValue({
859 message: `Header ${JSON.stringify(key)} has a malformed percent-encoded value.`,
860 }),
861 );
862 }
863 }
864 return Effect.succeed(headers);
865 },
866 encode: (headers) =>
867 Effect.succeed(
868 Object.entries(headers)
869 .map(([key, value]) => `${key}=${encodeURIComponent(value)}`)
870 .join(","),
871 ),
872 }),
873 ),
874);