@diveinto/obs 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 James Spurin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,118 @@
+# @diveinto/obs
+
+Structured logging, tracing and metrics for Next.js and Node services. One
+record shape, written to stdout and to two rotating files, with W3C trace
+context threaded through it, and optional OpenTelemetry export that stays off
+until you configure an endpoint.
+
+```bash
+npm install @diveinto/obs
+```
+
+## Why it exists
+
+It grew out of consolidating four hand-maintained copies of the same library
+across four services. Copies drift: by the time they were merged, one had
+real OpenTelemetry spans around requests and the others did not, one had
+route templating that kept metric cardinality bounded, one had fixed a
+duration that went unrecorded when something threw a non-`Error`, and one had
+made log-file resolution a pure, testable function. This package is the union
+of the four, and each of those behaviours is pinned by a test.
+
+## What you get
+
+- **One record shape**, frozen, identical in the text and JSON renderers:
+  `ts level trace_id span_id parent_span_id logger event msg` plus context.
+  A sibling Python implementation writes the same shape, so one `grep` can
+  follow a trace across services written in either language.
+- **Three sinks**: stdout (always), and two rotating files that are
+  format-locked, so `<stem>.log` is always text and `<stem>.jsonl` is always
+  JSON regardless of `LOG_FORMAT`. Daily rotation, 14 kept, both configurable.
+- **Trace context** on `AsyncLocalStorage`, continuing an inbound W3C
+  `traceparent` and propagating it outbound, so one `trace_id` spans every
+  hop.
+- **Optional OTLP export** to any OpenTelemetry collector. Off unless
+  `OTEL_EXPORTER_OTLP_ENDPOINT` is set, and the first-party logs never depend
+  on it.
+- **Serverless-aware**: on Vercel or Lambda the file sinks switch themselves
+  off rather than failing, because there is no persistent writable disk.
+
+## Usage
+
+Once, from the app's `instrumentation.ts`, on the Node runtime:
+
+```ts
+export async function register() {
+  if (process.env.NEXT_RUNTIME !== "nodejs") return;
+
+  // Optional: start OTLP export first, so the earliest logs adopt OTel ids.
+  const { startOtel } = await import("@diveinto/obs/start");
+  await startOtel("my-service");
+
+  const { createObs } = await import("@diveinto/obs");
+  createObs({ service: "my-service", envPrefix: "MYSVC" });
+}
+```
+
+Everywhere else, plain named imports:
+
+```ts
+import { getLogger, withApiTrace, withAction, traceHeaders } from "@diveinto/obs";
+
+const log = getLogger("billing.invoice");
+
+export const GET = (req: Request) =>
+  withApiTrace(req, async () => {
+    log.info("invoice.fetch", "fetching invoice", { invoice_id: id });
+    const res = await fetch(url, { headers: traceHeaders() }); // same trace, next hop
+    return Response.json(await res.json());
+  });
+```
+
+`withApiTrace` opens or continues the trace, logs `request.received` and
+`request.completed`, records a duration histogram, and sets `X-Trace-Id` on
+the response. `withAction` does the same for a server action in a fresh root
+trace.
+
+## Configuration
+
+| field | required | what it does |
+|---|---|---|
+| `service` | yes | The OpenTelemetry tracer and meter name, the `service.name` fallback, and the default var dir and file stem |
+| `envPrefix` | yes | The prefix on this service's own env vars. `MYSVC` reads `MYSVC_LOG_TEXT_FILE`, `MYSVC_VAR_DIR` and the rest, so a service adopting the library keeps the env file it already has |
+| `defaultVarDir` | no | State dir when `<PREFIX>_VAR_DIR` is unset. Default `/var/lib/<service>` |
+| `fileStem` | no | Stem for the two log files. Default: the last dash-separated word of `service` |
+| `routeTemplate` | no | Collapse dynamic path segments before a path becomes a metric label: `/orders/abc123` to `/orders/{id}`. Without it every id is its own time series |
+| `traceSeed` | no | Where a request's trace continues from when there is no W3C `traceparent`, for a front end that passes a correlation id of its own |
+| `quietPathPrefixes` | no | Request paths whose completion logs at debug rather than info. Health checks and internal polling otherwise bury what matters |
+
+### Environment
+
+Generic, never prefixed: `LOG_LEVEL` (`trace`/`debug`/`info`/`warn`/`error`/
+`fatal`), `LOG_FORMAT` (`pretty` or `json`, stdout only), and the standard
+`OTEL_*` set.
+
+Per service, prefixed: `<PREFIX>_VAR_DIR`, `<PREFIX>_LOG_TEXT_FILE`,
+`_TEXT_ROTATION`, `_TEXT_RETENTION`, and the same three for `_JSON_`. A
+`*_FILE` value is a path, or `1` for the default path, or `0`/`off`.
+
+## Cardinality
+
+Metric attributes become a separate time series per distinct value, so they
+must be low cardinality: an outcome, a status class, a route **template**.
+Never a user id, order id or request id. Those belong on spans and logs,
+where the point is finding the one bad request, and are toxic on metrics.
+`routeTemplate` exists for exactly this reason.
+
+The library registers no metric reader, so metrics are no-ops unless you wire
+one deliberately. That is a scar: auto-exporting metrics alongside traces
+once produced tens of millions of samples a month that nobody read.
+
+## Requirements
+
+Node 22 or newer, ESM. `@opentelemetry/api` is a peer dependency; the SDK
+packages are optional peers, needed only if you use OTLP export.
+
+## License
+
+MIT

package/dist/api.d.ts

@@ -0,0 +1,38 @@
+import type { Fields, LevelInput } from "./types.js";
+/**
+ * Emit one named story beat.
+ *
+ * `event` is the machine-stable key (e.g. "lab.launch.started"); `message` is
+ * the human sentence; `fields` carry the salient facts (ids, counts, durations,
+ * the actual target). Use it at meaningful seams.
+ */
+export declare function logEvent(event: string, message?: string, fields?: Fields, opts?: {
+    level?: LevelInput;
+    logger?: string;
+    error?: unknown;
+}): void;
+type SpanOpts = {
+    fields?: Fields;
+    logger?: string;
+    level?: LevelInput;
+};
+/**
+ * Open a child span around a unit of work: mints a child span id, binds
+ * `fields` as baggage (so they appear on every line inside), times the body,
+ * and logs `<name>.start` / `<name>.finish` (with dur_ms). On a throw it logs
+ * `<name>.error` with the stack and re-raises. The parent context is restored
+ * automatically when the body settles.
+ */
+export declare function withSpan<T>(name: string, fn: () => Promise<T> | T, opts?: SpanOpts): Promise<T>;
+/**
+ * Like withSpan, but opens a fresh ROOT trace (for background work with no
+ * inbound request: a scheduler tick, a server action). `seed` continues an
+ * inbound trace when its ids are provided.
+ */
+export declare function withTrace<T>(name: string, fn: () => Promise<T> | T, opts?: SpanOpts & {
+    seed?: {
+        traceId?: string;
+        parentSpanId?: string;
+    };
+}): Promise<T>;
+export { bind } from "./context.js";

package/dist/api.js

@@ -0,0 +1,80 @@
+/**
+ * The ergonomic surface feature code reaches for: logEvent, span/withSpan,
+ * withTrace, plus the bind/current re-exports.
+ *
+ * Mirrors the agent's `obs/api.py`. The guiding rule is the same one that kept
+ * the agent framework small and is the explicit lesson from the abandoned OTel
+ * attempt: instrument the few meaningful seams and decisions, NOT every line. A
+ * handful of events/spans per flow, never hundreds. If you are tempted to add a
+ * fifth logEvent to one function, you probably want a span instead.
+ */
+import { bind, runWithSpan, runWithTrace } from "./context.js";
+import { otelEnabled, withOtelSpan } from "./otel.js";
+import { emit, normalizeLevel } from "./record.js";
+/** The default logger name for one-off events not tied to a module logger. */
+const DEFAULT_LOGGER = "event";
+/**
+ * Emit one named story beat.
+ *
+ * `event` is the machine-stable key (e.g. "lab.launch.started"); `message` is
+ * the human sentence; `fields` carry the salient facts (ids, counts, durations,
+ * the actual target). Use it at meaningful seams.
+ */
+export function logEvent(event, message, fields, opts) {
+    emit(normalizeLevel(opts?.level ?? "INFO"), opts?.logger ?? DEFAULT_LOGGER, event, message ?? "", fields, opts?.error);
+}
+/**
+ * Open a child span around a unit of work: mints a child span id, binds
+ * `fields` as baggage (so they appear on every line inside), times the body,
+ * and logs `<name>.start` / `<name>.finish` (with dur_ms). On a throw it logs
+ * `<name>.error` with the stack and re-raises. The parent context is restored
+ * automatically when the body settles.
+ */
+export async function withSpan(name, fn, opts) {
+    const logger = opts?.logger ?? DEFAULT_LOGGER;
+    const level = normalizeLevel(opts?.level ?? "INFO");
+    const inner = () => runWithSpan(async () => {
+        if (opts?.fields)
+            bind(opts.fields);
+        const start = Date.now();
+        emit(level, logger, `${name}.start`, name, opts?.fields);
+        try {
+            const out = await fn();
+            emit(level, logger, `${name}.finish`, name, { dur_ms: Date.now() - start });
+            return out;
+        }
+        catch (err) {
+            emit("ERROR", logger, `${name}.error`, `${name} failed: ${err instanceof Error ? err.message : String(err)}`, { dur_ms: Date.now() - start }, err);
+            throw err;
+        }
+    });
+    // Open a real OTel child span when export is on, so the domain story appears
+    // in the backend; the logs inside adopt the OTel span ids via context.current.
+    return otelEnabled() ? withOtelSpan(name, opts?.fields ?? {}, inner) : inner();
+}
+/**
+ * Like withSpan, but opens a fresh ROOT trace (for background work with no
+ * inbound request: a scheduler tick, a server action). `seed` continues an
+ * inbound trace when its ids are provided.
+ */
+export async function withTrace(name, fn, opts) {
+    const logger = opts?.logger ?? DEFAULT_LOGGER;
+    const level = normalizeLevel(opts?.level ?? "INFO");
+    const inner = () => runWithTrace(opts?.seed ?? {}, async () => {
+        if (opts?.fields)
+            bind(opts.fields);
+        const start = Date.now();
+        emit(level, logger, `${name}.start`, name, opts?.fields);
+        try {
+            const out = await fn();
+            emit(level, logger, `${name}.finish`, name, { dur_ms: Date.now() - start });
+            return out;
+        }
+        catch (err) {
+            emit("ERROR", logger, `${name}.error`, `${name} failed: ${err instanceof Error ? err.message : String(err)}`, { dur_ms: Date.now() - start }, err);
+            throw err;
+        }
+    });
+    return otelEnabled() ? withOtelSpan(name, opts?.fields ?? {}, inner) : inner();
+}
+export { bind } from "./context.js";

package/dist/config.d.ts

@@ -0,0 +1,83 @@
+/**
+ * What a service tells the library about itself, and the module-level home
+ * for it.
+ *
+ * Everything else in this package is generic. These are the only knobs, and
+ * they exist for one reason: four services already run this code with four
+ * env prefixes and four sets of live env files. `envPrefix` means none of
+ * those files change when a service adopts the package.
+ *
+ * `configure()` is called once, from the app's `instrumentation.ts`, before
+ * anything logs. It is idempotent by design rather than by accident: Next
+ * calls `register()` more than once across HMR and can isolate the
+ * instrumentation hook from route handlers, so a second call with the same
+ * service name is a no-op and a call with a DIFFERENT one is a mistake worth
+ * hearing about.
+ */
+/** How a path becomes a metric label. See `routeTemplate` below. */
+export type RouteTemplate = (path: string) => string;
+/** Where a request's trace should continue from. See `traceSeed` below. */
+export type TraceSeedFn = (req: Request) => {
+    traceId?: string;
+    parentSpanId?: string;
+};
+export type ObsConfig = {
+    /**
+     * The service's own name: the OTel tracer and meter name, the fallback for
+     * `service.name`, and the stem of the two log files. Use the unit name,
+     * e.g. "my-service".
+     */
+    service: string;
+    /**
+     * The prefix on this service's own env vars: "MYSVC" reads
+     * MYSVC_LOG_TEXT_FILE, MYSVC_VAR_DIR and the rest. The generic names
+     * (LOG_LEVEL, LOG_FORMAT, OTEL_*) are never prefixed. This is the whole
+     * compatibility story: a service adopting the library keeps the env file
+     * it already has, unchanged.
+     */
+    envPrefix: string;
+    /** State dir when <PREFIX>_VAR_DIR is unset. Default /var/lib/<service>. */
+    defaultVarDir?: string;
+    /**
+     * Stem for the two log files under <var dir>/logs, when the env does not
+     * name a path. Defaults to the last dash-separated word of `service`, so
+     * "acme-web-api" writes api.log and api.jsonl.
+     */
+    fileStem?: string;
+    /**
+     * Collapse dynamic path segments before a path becomes a metric label:
+     * `/api/labs/abc123` to `/api/labs/{identifier}`. Without it every id is its
+     * own time series, which is how a metrics backend falls over. The patterns
+     * are the service's own routes, so the service supplies them. Omitted means
+     * the raw path, which is fine for a service with few dynamic routes.
+     */
+    routeTemplate?: RouteTemplate;
+    /**
+     * Where an inbound request's trace comes from, when it is not a W3C
+     * `traceparent`. Some front ends pass a correlation UUID of their own as a
+     * header or `?trace=`; accepting it makes a user's journey one trace rather
+     * than two unconnected halves. Omitted means `traceparent` only.
+     */
+    traceSeed?: TraceSeedFn;
+    /**
+     * Request paths logged at debug rather than info. Health checks and
+     * internal polling otherwise bury the requests a person cares about.
+     * Matched by prefix.
+     */
+    quietPathPrefixes?: string[];
+};
+type Resolved = Required<Pick<ObsConfig, "service" | "envPrefix" | "defaultVarDir" | "fileStem">> & Pick<ObsConfig, "routeTemplate" | "traceSeed"> & {
+    quietPathPrefixes: string[];
+};
+export declare function configure(cfg: ObsConfig): void;
+/**
+ * The live config. Falling back rather than throwing is deliberate: a log
+ * line emitted before `configure()` (an import-time warning, say) should
+ * still come out, named honestly, instead of taking the process down.
+ */
+export declare function obsConfig(): Resolved;
+/** Test seam: forget the configuration so a test can set a different one. */
+export declare function resetConfigForTests(): void;
+/** Read one of this service's own prefixed variables. */
+export declare function envVar(name: string, env?: NodeJS.ProcessEnv): string | undefined;
+export {};

package/dist/config.js

@@ -0,0 +1,60 @@
+/**
+ * What a service tells the library about itself, and the module-level home
+ * for it.
+ *
+ * Everything else in this package is generic. These are the only knobs, and
+ * they exist for one reason: four services already run this code with four
+ * env prefixes and four sets of live env files. `envPrefix` means none of
+ * those files change when a service adopts the package.
+ *
+ * `configure()` is called once, from the app's `instrumentation.ts`, before
+ * anything logs. It is idempotent by design rather than by accident: Next
+ * calls `register()` more than once across HMR and can isolate the
+ * instrumentation hook from route handlers, so a second call with the same
+ * service name is a no-op and a call with a DIFFERENT one is a mistake worth
+ * hearing about.
+ */
+let current = null;
+function resolve(cfg) {
+    const service = cfg.service.trim();
+    if (!service)
+        throw new Error("[obs] configure() needs a service name");
+    const prefix = cfg.envPrefix.trim().toUpperCase();
+    if (!/^[A-Z][A-Z0-9_]*$/.test(prefix)) {
+        throw new Error(`[obs] envPrefix '${cfg.envPrefix}' is not a usable env var prefix`);
+    }
+    return {
+        service,
+        envPrefix: prefix,
+        defaultVarDir: cfg.defaultVarDir ?? `/var/lib/${service}`,
+        fileStem: cfg.fileStem ?? (service.split("-").pop() || service),
+        routeTemplate: cfg.routeTemplate,
+        traceSeed: cfg.traceSeed,
+        quietPathPrefixes: cfg.quietPathPrefixes ?? [],
+    };
+}
+export function configure(cfg) {
+    const next = resolve(cfg);
+    if (current && current.service !== next.service) {
+        // Two services in one process is not a thing this library supports, and
+        // the symptom (logs filed under the wrong service) is miserable to chase.
+        throw new Error(`[obs] already configured as '${current.service}'; cannot reconfigure as '${next.service}'`);
+    }
+    current = next;
+}
+/**
+ * The live config. Falling back rather than throwing is deliberate: a log
+ * line emitted before `configure()` (an import-time warning, say) should
+ * still come out, named honestly, instead of taking the process down.
+ */
+export function obsConfig() {
+    return current ?? (current = resolve({ service: "unconfigured", envPrefix: "OBS" }));
+}
+/** Test seam: forget the configuration so a test can set a different one. */
+export function resetConfigForTests() {
+    current = null;
+}
+/** Read one of this service's own prefixed variables. */
+export function envVar(name, env = process.env) {
+    return env[`${obsConfig().envPrefix}_${name}`];
+}

package/dist/context.d.ts

@@ -0,0 +1,88 @@
+import type { Fields } from "./types.js";
+/** The ambient trace state for the current async scope. */
+export type TraceState = {
+    /** 32 hex chars, or "" when there is no active trace. */
+    traceId: string;
+    /** 16 hex chars, or "". */
+    spanId: string;
+    /** 16 hex chars, or "" for a root span. */
+    parentSpanId: string;
+    /** W3C sampled flag; we always log locally, this only guides a future exporter. */
+    sampled: boolean;
+    /** Domain attributes stamped onto every line in scope (lab/session/agent ids). */
+    baggage: Fields;
+};
+/** Mint a fresh 128-bit trace id as 32 lowercase hex chars (W3C format). */
+export declare function newTraceId(): string;
+/** Mint a fresh 64-bit span id as 16 lowercase hex chars (W3C format). */
+export declare function newSpanId(): string;
+/** The current trace state. When OTLP export is live, the active OTel span is
+ *  authoritative for the ids (so logs match the backend exactly and traceHeaders
+ *  injects the OTel trace); baggage stays in our AsyncLocalStorage store.
+ *  Outside any trace, the empty stand-in. */
+export declare function current(): TraceState;
+export declare function currentTraceId(): string;
+export declare function currentSpanId(): string;
+export declare function currentBaggage(): Fields;
+export declare function isSampled(): boolean;
+/**
+ * Run `fn` inside a brand-new ROOT trace.
+ *
+ * `seed.traceId` continues an inbound trace (e.g. a `traceparent` from the
+ * upstream caller); when absent a fresh id is minted. `seed.parentSpanId` is the
+ * caller's span id from the inbound header, so our first span points back at the
+ * remote caller and the tree spans both services.
+ *
+ * Unlike the agent's save/restore pattern, `als.run` restores the parent store
+ * automatically when `fn` returns or throws - the runtime does the "finally" for
+ * us.
+ */
+export declare function runWithTrace<T>(seed: {
+    traceId?: string;
+    parentSpanId?: string;
+    sampled?: boolean;
+}, fn: () => T): T;
+/**
+ * Run `fn` inside a CHILD span of the current trace (the current span becomes
+ * the parent). If no trace is active we mint one defensively, so a stray span
+ * still produces a usable (if un-parented) trace rather than blank ids.
+ *
+ * The child copies the parent's baggage by value, so a child's `bind()` cannot
+ * leak back up into the parent - matching the agent's copy-on-write contract.
+ */
+export declare function runWithSpan<T>(fn: () => T): T;
+/**
+ * Stamp domain attributes onto the current scope so they appear on every later
+ * line. This deliberately MUTATES the live store's baggage (the one object
+ * AsyncLocalStorage hands back for the whole scope); it is a no-op outside a
+ * trace. Child scopes snapshot baggage at creation, so this never leaks across
+ * sibling requests.
+ */
+export declare function bind(attrs: Fields): void;
+/**
+ * Parse a W3C `traceparent` header into `{ traceId, parentSpanId }`.
+ *
+ * Format: `version-traceid-spanid-flags`, e.g.
+ * `00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01`. Returns null for
+ * anything malformed so the caller mints a fresh root rather than trusting junk;
+ * the all-zero ids are explicitly invalid per the spec. This is the exact mirror
+ * of the agent's `parse_traceparent`, so each side accepts the other's output.
+ */
+export declare function parseTraceparent(header: string | null | undefined): {
+    traceId: string;
+    parentSpanId: string;
+} | null;
+/**
+ * Accept a plain UUID as a trace id.
+ *
+ * Some front ends pass a correlation UUID rather than a W3C
+ * `traceparent`, and a 32-hex UUID with the dashes stripped IS a valid trace
+ * id. Taking it means a user's journey is one trace from the front end through
+ * the launch to the lab, instead of two unconnected halves.
+ *
+ * Returns null for anything that is not 32 hex characters, and for the
+ * all-zero id, which W3C defines as "no trace".
+ */
+export declare function traceIdFromCorrelationId(raw: string | null | undefined): string | null;
+/** Serialise ids into a W3C `traceparent` string for an outbound header. */
+export declare function formatTraceparent(traceId: string, spanId: string, sampled: boolean): string;