@lesto/observability 0.1.0

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@lesto/observability",
+  "version": "0.1.0",
+  "license": "MIT",
+  "description": "Lesto's in-house distributed-tracing core — OpenTelemetry-shaped, with no OpenTelemetry dependency.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./rum": {
+      "types": "./src/rum.ts",
+      "import": "./src/rum.ts"
+    }
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:cov": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint src test",
+    "format": "oxfmt src test",
+    "format:check": "oxfmt --check src test"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lesto-run/lesto.git",
+    "directory": "packages/observability"
+  },
+  "homepage": "https://lesto.run",
+  "bugs": {
+    "url": "https://github.com/lesto-run/lesto/issues"
+  }
+}

package/src/exporter.ts

@@ -0,0 +1,13 @@
+import type { SpanData, SpanExporter } from "./types";
+
+/**
+ * The canonical test double: an exporter that simply keeps every span it is
+ * handed, in the order they ended. Assert against `spans` after the fact.
+ */
+export class InMemoryExporter implements SpanExporter {
+  readonly spans: SpanData[] = [];
+
+  export(span: SpanData): void {
+    this.spans.push(span);
+  }
+}

package/src/ids.ts

@@ -0,0 +1,11 @@
+import { randomBytes } from "node:crypto";
+
+/**
+ * Identity, made injectable.
+ *
+ * The default generator draws 16 random bytes and renders them as hex — wide
+ * enough to make collisions a non-event. Tests inject a counting generator
+ * instead, so trace and span ids are predictable.
+ */
+
+export const randomHexId = (): string => randomBytes(16).toString("hex");

package/src/index.ts

@@ -0,0 +1,107 @@
+/**
+ * @lesto/observability — an in-house distributed-tracing core.
+ *
+ *   const exporter = new InMemoryExporter();
+ *   const tracer = new Tracer({ exporter });
+ *
+ *   const root = tracer.startSpan("handle_request");
+ *   const child = tracer.startSpan("query_db", { parent: root });
+ *   child.setAttribute("rows", 12).setStatus("ok").end();
+ *   root.end();
+ *
+ *   await tracer.withSpan("charge_card", async (span) => {
+ *     span.setAttribute("amount_cents", 4200);
+ *     return charge();
+ *   });
+ *
+ * The shape is OpenTelemetry-flavored, and the OTLP adapter is here: wire an
+ * `OtlpHttpExporter` instead of the in-memory one and `flush()` ships every
+ * finished span to a real collector over OTLP/HTTP JSON.
+ *
+ * The WIRING facade (`tracesFromEnv` / `createTraces`) is the env-driven entry
+ * point an app constructs once — it reads the two-env-var setup, builds the
+ * exporter + tracer, drives the flush lifecycle, and hands back the per-domain
+ * seam hooks (`db.onQuery`, `identity.onEvent`, …) every battery terminates in:
+ *
+ *   // The two-env-var setup (LESTO_OTLP_URL is the on switch):
+ *   //   LESTO_OTLP_URL=http://localhost:4318/v1/traces
+ *   //   LESTO_OTLP_SERVICE=my-app            (service.name; default "lesto")
+ *   //   LESTO_OTLP_HEADERS=authorization=Bearer t   (optional, comma-separated)
+ *   const traces = tracesFromEnv(process.env, { currentSpan });
+ *   const db = createDb(sql, { onQuery: traces?.seams.onQuery });
+ *   const stop = traces?.startInterval(5_000);   // flush cadence; stop on drain
+ *
+ * `traceparent` (parse/format) is the W3C propagation primitive — verbatim, never
+ * an invented format — that joins a trace across a process boundary.
+ *
+ * ── The v1 observability cut: TRACES ONLY (said out loud) ───────────────────
+ *
+ * This package is distributed TRACING and nothing else. v1 ships NO metrics
+ * pipeline (no counters, no latency histograms) and NO logs pipeline (no log
+ * aggregation/shipping) from here. That is a deliberate scope line, not an
+ * oversight: the operability plan defers metrics and logs post-1.0
+ * (`docs/plans/operability-dx.md`), and the launch story is spans + the runtime's
+ * structured access log. If you reach for a counter or a histogram here, it does
+ * not exist on purpose — the seam to add one is a future increment, not a gap to
+ * patch around.
+ *
+ * ── The `lesto.request_id` → trace join ──────────────────────────────────────
+ *
+ * Traces and the access log are two records of ONE request, joined by a shared
+ * id. The runtime mints a per-request id, puts it on every access-log entry as
+ * `requestId`, sets it on the request span as the `lesto.request_id` attribute,
+ * and echoes it back on the `X-Request-Id` response header. So a span found in
+ * the collector and an access-log line are correlated by an exact-match query on
+ * that one value — the trace tells you the shape (parent/child spans, timings),
+ * the access log tells you the outcome (method, path, status, ms), and
+ * `lesto.request_id` is the key that lines them up. No metrics layer is needed to
+ * bridge the two; the id is the join.
+ *
+ * ── The NIH boundary line: W3C `traceparent`, verbatim ──────────────────────
+ *
+ * Cross-process propagation is W3C Trace Context `traceparent` EXACTLY (see
+ * `traceparent.ts`) — never a Lesto-invented header or format. That is a settled
+ * decision: the W3C wire is what every collector, vendor, and sibling service
+ * already speaks, so adopting it verbatim is the difference between joining the
+ * world's traces and stranding ours. We do not extend it, we do not abbreviate
+ * it, and we do not ship an alternative — if a hop needs propagation, it carries
+ * `traceparent`.
+ */
+
+export { InMemoryExporter } from "./exporter";
+
+export { DEFAULT_MAX_BUFFERED_SPANS, OtlpHttpExporter, otlpTraceRequest } from "./otlp";
+export type { OtlpHttpExporterOptions } from "./otlp";
+
+export { randomHexId } from "./ids";
+
+export { systemClock } from "./time";
+
+export { Tracer } from "./tracer";
+export type { InboundTrace, StartSpanOptions, TracerOptions } from "./tracer";
+
+export { formatTraceparent, parseTraceparent, TRACEPARENT_HEADER } from "./traceparent";
+export type { Traceparent } from "./traceparent";
+
+export { browserSpanToData, createTraces, parseOtlpHeaders, tracesFromEnv } from "./traces";
+export type { CurrentSpan, Traces, TracesEnv, TracesOptions, TraceSeams } from "./traces";
+
+// Browser RUM — the browser half of the UI→API→DB trace (ARCHITECTURE.md §7).
+// `startBrowserRum` observes the page's performance and POSTs spans under the
+// SSR-injected server trace id; `wrapFetch` carries an outbound `traceparent` on
+// same-origin fetches so the server handler joins the same trace.
+export {
+  BROWSER_SPANS_PATH,
+  BrowserTracer,
+  browserRumEnvironment,
+  DEFAULT_RUM_SAMPLE_RATE,
+  defaultSendBrowserSpans,
+  readTraceparentMeta,
+  shouldSampleRum,
+  startBrowserRum,
+  TRACEPARENT_META_NAME,
+  wrapFetch,
+} from "./rum";
+export type { BrowserSpan, BrowserSpansPayload, RumEnvironment, RumOptions } from "./rum";
+
+export type { Clock, Span, SpanData, SpanExporter, SpanStatus } from "./types";

package/src/otlp.ts

@@ -0,0 +1,209 @@
+/**
+ * The OTLP/HTTP exporter — finished spans, shipped to a real collector.
+ *
+ * This is the adapter the rest of the package was shaped for: `SpanData`
+ * mirrors OpenTelemetry on purpose, so exporting is a mapping, not a redesign.
+ * `OtlpHttpExporter` buffers what `Tracer` hands it and `flush()` POSTs the
+ * batch as OTLP/HTTP JSON (`/v1/traces`) — the wire format every OTel
+ * collector, and the vendors behind one, accept.
+ *
+ * Telemetry must never take the app down: a failed flush (non-2xx, network
+ * throw) is routed to `onError` and the batch is dropped — the deliberate
+ * trade for a demo-grade exporter (no retry queue, no backpressure). The
+ * mapping itself is exported pure ({@link otlpTraceRequest}) so tests pin the
+ * exact bytes a collector would receive.
+ */
+
+import type { SpanData, SpanExporter } from "./types";
+
+/** One OTLP attribute value, in the tagged-union shape the protocol wants. */
+interface OtlpValue {
+  stringValue?: string;
+  boolValue?: boolean;
+  intValue?: string;
+  doubleValue?: number;
+}
+
+/** Map a span attribute to OTLP's tagged value union. Unknown shapes stringify. */
+function otlpValue(value: unknown): OtlpValue {
+  if (typeof value === "boolean") return { boolValue: value };
+
+  if (typeof value === "number") {
+    // OTLP carries 64-bit ints as strings; anything fractional is a double.
+    return Number.isInteger(value) ? { intValue: String(value) } : { doubleValue: value };
+  }
+
+  if (typeof value === "string") return { stringValue: value };
+
+  return { stringValue: String(value) };
+}
+
+/** Epoch milliseconds → the unix-nano string OTLP timestamps are. */
+function unixNano(ms: number): string {
+  return `${Math.round(ms)}000000`;
+}
+
+/** OTLP status codes: 0 unset, 1 ok, 2 error. */
+const STATUS_CODE = { unset: 0, ok: 1, error: 2 } as const;
+
+/** OTLP span kind 2 — SERVER, which is what a per-request span is. */
+const SPAN_KIND_SERVER = 2;
+
+/**
+ * Build the OTLP/HTTP JSON trace-export request body for a batch of spans.
+ *
+ * One resource (named by `serviceName`), one scope (this package), the spans.
+ * Lesto's span ids are 32 hex chars (16 random bytes); OTLP's spanId field is
+ * exactly 16 hex chars, so span ids are truncated to spec — still 8 random
+ * bytes of identity, while the full-width traceId is carried verbatim.
+ */
+export function otlpTraceRequest(spans: readonly SpanData[], serviceName: string): unknown {
+  return {
+    resourceSpans: [
+      {
+        resource: {
+          attributes: [{ key: "service.name", value: { stringValue: serviceName } }],
+        },
+        scopeSpans: [
+          {
+            scope: { name: "@lesto/observability" },
+            spans: spans.map((span) => ({
+              traceId: span.traceId,
+              spanId: span.spanId.slice(0, 16),
+              ...(span.parentSpanId === undefined
+                ? {}
+                : { parentSpanId: span.parentSpanId.slice(0, 16) }),
+              name: span.name,
+              kind: SPAN_KIND_SERVER,
+              startTimeUnixNano: unixNano(span.startedAt),
+              endTimeUnixNano: unixNano(span.endedAt ?? span.startedAt),
+              attributes: Object.entries(span.attributes).map(([key, value]) => ({
+                key,
+                value: otlpValue(value),
+              })),
+              status: { code: STATUS_CODE[span.status] },
+            })),
+          },
+        ],
+      },
+    ],
+  };
+}
+
+/**
+ * The default ceiling on the unbounded span buffer.
+ *
+ * A flush that never ran (the collector is down, no interval was started) used
+ * to let the buffer grow without limit — a slow memory leak under load, exactly
+ * the failure telemetry must never cause. We cap it at a generous default and
+ * drop the OLDEST span when full (the newest signal is the one an operator most
+ * wants), tallying every drop so the loss is observable, not silent.
+ */
+export const DEFAULT_MAX_BUFFERED_SPANS = 10_000;
+
+/** What the OTLP exporter needs to reach a collector. Everything that varies is injected. */
+export interface OtlpHttpExporterOptions {
+  /** The collector's trace endpoint, e.g. `http://localhost:4318/v1/traces`. */
+  readonly url: string;
+
+  /** Extra request headers (an auth token, a tenant id). */
+  readonly headers?: Record<string, string>;
+
+  /** The `service.name` resource attribute. Defaults to `"lesto"`. */
+  readonly serviceName?: string;
+
+  /** The HTTP seam; defaults to the global `fetch`. */
+  readonly fetchFn?: typeof fetch;
+
+  /**
+   * The most spans the buffer may hold between flushes. When full, the OLDEST is
+   * dropped to admit the newest (and counted — see {@link OtlpHttpExporter.dropped}).
+   * Defaults to {@link DEFAULT_MAX_BUFFERED_SPANS}.
+   */
+  readonly maxBufferedSpans?: number;
+
+  /** Where a failed flush is reported. Defaults to `console.error`. */
+  readonly onError?: (error: unknown) => void;
+}
+
+/**
+ * Buffer finished spans; `flush()` ships the batch to the collector.
+ *
+ * Batching is the caller's cadence to own — flush at request end (an edge
+ * worker's `waitUntil`), on an interval (a node service), or at shutdown. A
+ * flush failure reports to `onError` and drops the batch; it never throws.
+ *
+ * The buffer is BOUNDED ({@link OtlpHttpExporterOptions.maxBufferedSpans}): if
+ * spans pile up faster than they flush (a down collector, a missing interval),
+ * the oldest are dropped to admit the newest and the loss is counted in
+ * {@link dropped} — telemetry sheds load instead of leaking memory.
+ */
+export class OtlpHttpExporter implements SpanExporter {
+  private readonly buffer: SpanData[] = [];
+
+  private readonly url: string;
+
+  private readonly headers: Record<string, string>;
+
+  private readonly serviceName: string;
+
+  private readonly fetchFn: typeof fetch;
+
+  private readonly maxBufferedSpans: number;
+
+  private readonly onError: (error: unknown) => void;
+
+  /**
+   * How many spans were dropped because the buffer was full when they arrived.
+   *
+   * A non-zero count means the exporter is shedding telemetry under backpressure
+   * — the collector is unreachable, or no flush cadence is draining the buffer.
+   * Read it to surface the loss (a periodic log, a metric) so dropped traces are
+   * a known fact, not a silent gap.
+   */
+  dropped = 0;
+
+  constructor(options: OtlpHttpExporterOptions) {
+    this.url = options.url;
+    this.headers = options.headers ?? {};
+    this.serviceName = options.serviceName ?? "lesto";
+    this.fetchFn = options.fetchFn ?? fetch;
+    this.maxBufferedSpans = options.maxBufferedSpans ?? DEFAULT_MAX_BUFFERED_SPANS;
+    this.onError = options.onError ?? ((error) => console.error("[lesto/observability]", error));
+  }
+
+  export(span: SpanData): void {
+    // Drop-oldest at the ceiling: a backed-up buffer (down collector, no flush
+    // cadence) sheds its stalest span to admit the freshest, and counts the loss
+    // so it is observable rather than an unbounded memory leak.
+    if (this.buffer.length >= this.maxBufferedSpans) {
+      this.buffer.shift();
+      this.dropped += 1;
+    }
+
+    this.buffer.push(span);
+  }
+
+  /** Ship everything buffered so far. An empty buffer is a no-op, not a request. */
+  async flush(): Promise<void> {
+    if (this.buffer.length === 0) return;
+
+    const spans = this.buffer.splice(0);
+
+    try {
+      const response = await this.fetchFn(this.url, {
+        method: "POST",
+        headers: { "content-type": "application/json", ...this.headers },
+        body: JSON.stringify(otlpTraceRequest(spans, this.serviceName)),
+      });
+
+      if (!response.ok) {
+        this.onError(
+          new Error(`OTLP export failed: ${response.status} for ${spans.length} span(s)`),
+        );
+      }
+    } catch (error) {
+      this.onError(error);
+    }
+  }
+}