@lesto/observability 0.1.0

package/src/traceparent.ts

@@ -0,0 +1,111 @@
+/**
+ * W3C Trace Context `traceparent` — the propagation header, verbatim.
+ *
+ * One header carries a trace across a process boundary: an inbound request
+ * adopts the upstream's trace id so the server span joins the same trace, and an
+ * outbound call (a webhook, an edge sub-request) emits its own so the next hop
+ * continues it. We implement the W3C format EXACTLY — never an invented one —
+ * because that is the wire every collector, vendor, and sibling service already
+ * speaks (the NIH boundary line operability-dx draws):
+ *
+ *   version "-" trace-id "-" parent-id "-" trace-flags
+ *   00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
+ *
+ *   - version    : 2 hex, the format version. We read only "00"; any other
+ *                  version we DROP (a future format we cannot trust to parse).
+ *   - trace-id   : 32 hex, the trace. All-zero is invalid (the spec's sentinel).
+ *   - parent-id  : 16 hex, the caller's span — our span's PARENT. All-zero is
+ *                  invalid.
+ *   - trace-flags: 2 hex; bit 0 is "sampled". We carry it through unread (we
+ *                  always export) but format it honestly.
+ *
+ * Lesto's own ids are 32-hex traceIds and 32-hex spanIds; OTLP already truncates
+ * a spanId to 16 hex on export (see `otlp.ts`), and traceparent's parent-id is
+ * the same 16-hex span field — so {@link formatTraceparent} truncates a 32-hex
+ * spanId to its first 16 hex, matching what the collector sees.
+ */
+
+/** The only `version` field we parse — a future version is dropped, not guessed. */
+const SUPPORTED_VERSION = "00";
+
+/** Default `trace-flags`: `01` = sampled. We always export, so we always set it. */
+const SAMPLED_FLAGS = "01";
+
+/** A 32-hex trace id (lowercase). */
+const TRACE_ID = /^[0-9a-f]{32}$/;
+
+/** A 16-hex parent (span) id (lowercase). */
+const PARENT_ID = /^[0-9a-f]{16}$/;
+
+/** A 2-hex flags byte (lowercase). */
+const FLAGS = /^[0-9a-f]{2}$/;
+
+/** The all-zero sentinel both id fields treat as invalid, per the spec. */
+const isAllZero = (hex: string): boolean => /^0+$/.test(hex);
+
+/** The parsed pieces of a valid `traceparent` an inbound request carried. */
+export interface Traceparent {
+  /** The 32-hex trace id this request belongs to — our root span adopts it. */
+  readonly traceId: string;
+
+  /** The 16-hex caller span id — the PARENT of the span we are about to mint. */
+  readonly parentId: string;
+
+  /** The 2-hex trace-flags byte, carried through verbatim (bit 0 = sampled). */
+  readonly flags: string;
+}
+
+/**
+ * Parse a `traceparent` header value, or `undefined` if it is absent/malformed.
+ *
+ * We are STRICT on inbound (the spec's posture for a received header): a header
+ * we cannot fully trust is treated as no header at all, and the request roots a
+ * fresh trace instead of joining a forged or garbled one. Rejected: an absent
+ * value, the wrong field count, a non-"00" version, a non-hex or wrong-width id,
+ * an all-zero (sentinel) trace or parent id, or a malformed flags byte. Lowercase
+ * is required — the spec mandates lowercase hex, so an uppercase value is not a
+ * valid traceparent.
+ *
+ * Pure and total so every reject branch is unit-testable without a socket.
+ */
+export function parseTraceparent(header: string | undefined): Traceparent | undefined {
+  if (header === undefined) return undefined;
+
+  const parts = header.split("-");
+
+  // Exactly four fields: version, trace-id, parent-id, flags.
+  if (parts.length !== 4) return undefined;
+
+  const [version, traceId, parentId, flags] = parts as [string, string, string, string];
+
+  // Only the version we know how to read; a future format we cannot trust.
+  if (version !== SUPPORTED_VERSION) return undefined;
+
+  if (!TRACE_ID.test(traceId) || isAllZero(traceId)) return undefined;
+
+  if (!PARENT_ID.test(parentId) || isAllZero(parentId)) return undefined;
+
+  if (!FLAGS.test(flags)) return undefined;
+
+  return { traceId, parentId, flags };
+}
+
+/**
+ * Format a `traceparent` header for an outbound hop from a trace + span id.
+ *
+ * `spanId` is the CURRENT span — it becomes the next hop's parent-id. A Lesto
+ * spanId is 32 hex; the traceparent parent-id field is 16 hex (the same field
+ * OTLP truncates a spanId to), so we take its first 16 hex to match what the
+ * collector records. `flags` defaults to `01` (sampled) — we always export. The
+ * output is a spec-valid `00-…` header verbatim.
+ *
+ * The caller guarantees `traceId`/`spanId` are hex of at least the needed width
+ * (they come from the tracer's id generator); we slice to the field widths the
+ * format demands.
+ */
+export function formatTraceparent(traceId: string, spanId: string, flags = SAMPLED_FLAGS): string {
+  return `${SUPPORTED_VERSION}-${traceId.slice(0, 32)}-${spanId.slice(0, 16)}-${flags}`;
+}
+
+/** The canonical header name, lowercase (the form node/fetch deliver and want). */
+export const TRACEPARENT_HEADER = "traceparent";

package/src/tracer.ts

@@ -0,0 +1,171 @@
+import { randomHexId } from "./ids";
+import { systemClock } from "./time";
+
+import type { Clock, Span, SpanData, SpanExporter, SpanStatus } from "./types";
+
+/** What a Tracer needs from the outside world. Everything that varies is injected. */
+export interface TracerOptions {
+  readonly exporter: SpanExporter;
+
+  /** Defaults to the system wall clock (epoch ms). */
+  readonly clock?: Clock;
+
+  /** Defaults to a random hex id. */
+  readonly idGenerator?: () => string;
+}
+
+/**
+ * An inbound trace adopted from a W3C `traceparent` — the cross-process join.
+ *
+ * Unlike {@link StartSpanOptions.parent} (a live `Span` we hold), this carries
+ * ONLY the ids another system sent: the `traceId` to continue and the `parentId`
+ * (the caller's 16-hex span) to point back at. The runtime parses an inbound
+ * `traceparent` into this shape so the request's root span joins the upstream
+ * trace instead of starting a fresh one.
+ */
+export interface InboundTrace {
+  readonly traceId: string;
+
+  readonly parentId: string;
+}
+
+/** Where a new span sits in the tree, and what it starts knowing. */
+export interface StartSpanOptions {
+  /** Given a parent, the new span joins its trace as a child; absent, it roots a fresh trace. */
+  readonly parent?: Span;
+
+  /**
+   * Given an inbound trace (parsed from a W3C `traceparent`), the new span
+   * continues THAT trace: it adopts the inbound `traceId` and points back at the
+   * inbound `parentId`. Used for the cross-process join — a request's root span
+   * joining the caller's trace. Ignored when {@link parent} is also set (a live
+   * parent wins, since it carries a real span we own).
+   */
+  readonly inbound?: InboundTrace;
+
+  readonly attributes?: Record<string, unknown>;
+}
+
+/**
+ * A live span. The fluent setters return `this`, so attributes and status read
+ * as a chain; `end()` stamps the end time from the clock and hands the data to
+ * the exporter — exactly once per span.
+ */
+class LiveSpan implements Span {
+  readonly data: SpanData;
+
+  /** A span ends exactly once; a second `end()` is a no-op, never a re-export. */
+  private ended = false;
+
+  constructor(
+    data: SpanData,
+    private readonly clock: Clock,
+    private readonly exporter: SpanExporter,
+  ) {
+    this.data = data;
+  }
+
+  setAttribute(key: string, value: unknown): this {
+    this.data.attributes[key] = value;
+
+    return this;
+  }
+
+  setStatus(status: SpanStatus): this {
+    this.data.status = status;
+
+    return this;
+  }
+
+  end(): void {
+    // Idempotent: the first call stamps the end time and exports; any later call
+    // returns silently so a span is never double-counted (e.g. an explicit
+    // `end()` inside a `withSpan` body plus the `finally`'s `end()`).
+    if (this.ended) return;
+
+    this.ended = true;
+
+    this.data.endedAt = this.clock();
+
+    this.exporter.export(this.data);
+  }
+}
+
+/**
+ * The Tracer mints spans and wires them to the exporter.
+ *
+ * A root span gets a fresh traceId and no parent; a child inherits its parent's
+ * traceId and points back at the parent spanId. Every span — root or child —
+ * gets its own fresh spanId.
+ */
+export class Tracer {
+  private readonly exporter: SpanExporter;
+
+  private readonly clock: Clock;
+
+  private readonly idGenerator: () => string;
+
+  constructor(options: TracerOptions) {
+    this.exporter = options.exporter;
+    this.clock = options.clock ?? systemClock;
+    this.idGenerator = options.idGenerator ?? randomHexId;
+  }
+
+  startSpan(name: string, options: StartSpanOptions = {}): Span {
+    const parent = options.parent;
+    const inbound = options.inbound;
+
+    // The trace this span belongs to, and the span it points back at, in order of
+    // precedence: a live parent we own (its trace, its span) > an inbound trace
+    // adopted from a `traceparent` (its trace id, the caller's span) > a fresh
+    // root (a new trace, no parent).
+    const traceId =
+      parent !== undefined
+        ? parent.data.traceId
+        : inbound !== undefined
+          ? inbound.traceId
+          : this.idGenerator();
+
+    const parentSpanId =
+      parent !== undefined
+        ? parent.data.spanId
+        : inbound !== undefined
+          ? inbound.parentId
+          : undefined;
+
+    const data: SpanData = {
+      traceId,
+      spanId: this.idGenerator(),
+      ...(parentSpanId === undefined ? {} : { parentSpanId }),
+      name,
+      startedAt: this.clock(),
+      attributes: { ...options.attributes },
+      status: "unset",
+    };
+
+    return new LiveSpan(data, this.clock, this.exporter);
+  }
+
+  /**
+   * Run `fn` inside a span: start it, await the result, end the span, return the
+   * value. If `fn` throws, mark the span "error", end it, and rethrow — the
+   * caller's failure is recorded but never swallowed.
+   */
+  async withSpan<T>(
+    name: string,
+    fn: (span: Span) => T | Promise<T>,
+    options: StartSpanOptions = {},
+  ): Promise<T> {
+    const span = this.startSpan(name, options);
+
+    try {
+      return await fn(span);
+    } catch (error) {
+      span.setStatus("error");
+
+      throw error;
+    } finally {
+      span.end();
+    }
+  }
+}