@diveinto/obs 1.0.1

package/dist/context.js

@@ -0,0 +1,193 @@
+/**
+ * Trace-context core.
+ *
+ * This is the TypeScript counterpart of the agent's `obs/context.py`. It owns
+ * the ambient trace and span identifiers and nothing else - no logging, no
+ * formatting, no OpenTelemetry - so it stays easy to understand and to drop an
+ * optional OTel exporter on top of later.
+ *
+ * How the ids flow (identical model to the agent, so the two services stitch
+ * into one trace):
+ *
+ *   - An inbound request (a browser, or another service) opens a ROOT trace
+ *     with `runWithTrace()`. If the caller sent a W3C `traceparent`, we CONTINUE
+ *     that trace id (and point our first span at the caller's span); otherwise
+ *     we mint a fresh 128-bit trace id.
+ *   - Any nested unit of work opens a CHILD span with `runWithSpan()`; the
+ *     current span becomes the new span's parent, so the lines a child emits
+ *     point back at their caller.
+ *   - When this service calls another, `traceHeaders()` serialises the
+ *     current ids into a `traceparent` header; the agent continues the SAME
+ *     trace id, so one `grep <trace8>` lines up logs from both services.
+ *
+ * Storage is `AsyncLocalStorage` (the Node equivalent of Python's contextvars):
+ * the store is carried automatically across `await`, `then`, timers, and
+ * `queueMicrotask`, so a trace opened in a request handler survives every
+ * `await agent.fetch(...)` without us threading anything through.
+ *
+ * IMPORTANT runtime boundary: AsyncLocalStorage and `node:crypto` are Node-only.
+ * The Edge middleware (`src/proxy.ts`) must NOT import this module; it mints a
+ * `traceparent` header with Web Crypto instead, and the Node side reads it back
+ * here via `parseTraceparent`.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomBytes } from "node:crypto";
+import { currentIds as otelCurrentIds } from "./otel.js";
+// Empty-id state means "no active trace" (e.g. a log at module-import time). The
+// renderers show empty ids as a row of dots so those lines are obvious.
+const EMPTY = {
+    traceId: "",
+    spanId: "",
+    parentSpanId: "",
+    sampled: true,
+    baggage: {},
+};
+const als = new AsyncLocalStorage();
+/** Mint a fresh 128-bit trace id as 32 lowercase hex chars (W3C format). */
+export function newTraceId() {
+    return randomBytes(16).toString("hex");
+}
+/** Mint a fresh 64-bit span id as 16 lowercase hex chars (W3C format). */
+export function newSpanId() {
+    return randomBytes(8).toString("hex");
+}
+/** 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 function current() {
+    const store = als.getStore() ?? EMPTY;
+    const ids = otelCurrentIds();
+    if (ids) {
+        // Adopt the OTel span's parent too (same id-space as spanId), so logs carry
+        // the tree - not just the trace_id. Root spans report "" (no parent).
+        return {
+            ...store,
+            traceId: ids.traceId,
+            spanId: ids.spanId,
+            parentSpanId: ids.parentSpanId,
+        };
+    }
+    return store;
+}
+export function currentTraceId() {
+    return current().traceId;
+}
+export function currentSpanId() {
+    return current().spanId;
+}
+export function currentBaggage() {
+    return current().baggage;
+}
+export function isSampled() {
+    return current().sampled;
+}
+/**
+ * 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 function runWithTrace(seed, fn) {
+    const store = {
+        traceId: seed.traceId || newTraceId(),
+        spanId: newSpanId(),
+        parentSpanId: seed.parentSpanId || "",
+        sampled: seed.sampled ?? true,
+        baggage: {},
+    };
+    return als.run(store, fn);
+}
+/**
+ * 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 function runWithSpan(fn) {
+    const parent = current();
+    const store = {
+        traceId: parent.traceId || newTraceId(),
+        spanId: newSpanId(),
+        parentSpanId: parent.spanId || "",
+        sampled: parent.sampled,
+        baggage: { ...parent.baggage },
+    };
+    return als.run(store, fn);
+}
+/**
+ * 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 function bind(attrs) {
+    const store = als.getStore();
+    if (!store)
+        return;
+    store.baggage = { ...store.baggage, ...attrs };
+}
+/**
+ * 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 function parseTraceparent(header) {
+    if (!header)
+        return null;
+    const parts = header.split("-");
+    if (parts.length !== 4)
+        return null;
+    const traceId = parts[1];
+    const spanId = parts[2];
+    if (!traceId || !spanId)
+        return null;
+    if (traceId.length !== 32 || spanId.length !== 16)
+        return null;
+    if (!isHex(traceId) || !isHex(spanId))
+        return null;
+    if (traceId === "0".repeat(32) || spanId === "0".repeat(16))
+        return null;
+    return { traceId: traceId.toLowerCase(), parentSpanId: spanId.toLowerCase() };
+}
+/**
+ * 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 function traceIdFromCorrelationId(raw) {
+    if (!raw)
+        return null;
+    const hex = raw.replace(/-/g, "").toLowerCase();
+    if (hex.length !== 32 || !isHex(hex))
+        return null;
+    if (hex === "0".repeat(32))
+        return null;
+    return hex;
+}
+/** Serialise ids into a W3C `traceparent` string for an outbound header. */
+export function formatTraceparent(traceId, spanId, sampled) {
+    return `00-${traceId}-${spanId}-${sampled ? "01" : "00"}`;
+}
+function isHex(s) {
+    return s.length > 0 && /^[0-9a-fA-F]+$/.test(s);
+}

package/dist/http.d.ts

@@ -0,0 +1,49 @@
+import type { Fields } from "./types.js";
+/**
+ * The headers to attach to an outbound request to the agent so it CONTINUES
+ * this trace. Returns `{ traceparent }` when a trace is active, else `{}`. The
+ * agent's `parse_traceparent` accepts this exact format, and its request span
+ * becomes a child of our current span - so caller and callee are one tree.
+ */
+export declare function traceHeaders(): Record<string, string>;
+/**
+ * Where this request's trace continues from.
+ *
+ * A W3C `traceparent` always wins: it is the standard and it is what the
+ * middleware and other services send. Only when there is none does the
+ * service's own `traceSeed` get a say, which is how a service continues a
+ * trace from a front end's correlation UUID rather than starting a second,
+ * unconnected one. A service that configures no seed gets
+ * `traceparent` or a fresh root, which is the behaviour three of the four
+ * copies had.
+ */
+export declare function resolveTraceSeed(req: Request): {
+    traceId?: string;
+    parentSpanId?: string;
+};
+/**
+ * Wrap a request handler in a trace. Continues an inbound `traceparent` (set by
+ * the Edge middleware, or sent by an upstream service) so the whole chain shares
+ * one trace_id; otherwise mints a fresh root. Logs request.received (debug) and
+ * request.completed (info, or error on 5xx), and best-effort sets X-Trace-Id on
+ * the response (wrapped in try/catch - a streaming response may forbid header
+ * mutation, and that must never break the request).
+ */
+export declare function withApiTrace<T extends Response>(req: Request, handler: () => Promise<T>, opts?: {
+    fields?: Fields;
+}): Promise<T>;
+/**
+ * Wrap a server action (which has no NextRequest) in a FRESH root trace named
+ * after the action, so each action invocation is its own story. Binds the
+ * action name and any extra fields, logs start/finish/failed, and records two
+ * domain metrics that complement the span-derived RED with a clean, alertable
+ * action signal:
+ *   - diveinto.action.duration: histogram of elapsed ms
+ *   - diveinto.action.count:    counter of invocations
+ * Both carry only {action, outcome} - the action NAME is a fixed, low-cardinality
+ * set and outcome is ok/error, so the time-series count stays bounded. We pass
+ * those attrs EXPLICITLY (not `fields`) on purpose: the bound `fields` carry
+ * per-entity ids / operator / email, which belong on the span and the logs but
+ * would explode the metric cardinality. See metrics.ts for the why.
+ */
+export declare function withAction<T>(name: string, fn: () => Promise<T>, fields?: Fields): Promise<T>;

package/dist/http.js

@@ -0,0 +1,185 @@
+/**
+ * Next.js-aware glue between the runtime-agnostic obs core and the App Router.
+ *
+ * Kept separate from the rest of `obs/` so the core stays framework-free (and
+ * trivially unit-testable). This module is Node-only and is imported solely by
+ * Node route handlers, server actions, and the agent clients - NEVER by the Edge
+ * middleware (`src/proxy.ts`), which would fail to bundle `node:*`.
+ *
+ * It provides three seams:
+ *   - withApiTrace: wrap a request handler so it opens/continues a trace, logs
+ *     request.received/completed, and returns X-Trace-Id.
+ *   - withAction:   wrap a server action so it runs in a fresh root trace.
+ *   - traceHeaders: the outbound header that propagates the trace into the agent
+ *     (the cross-service win - one trace_id spans caller -> callee -> work).
+ */
+import { bind, currentSpanId, currentTraceId, formatTraceparent, isSampled, parseTraceparent, runWithTrace, } from "./context.js";
+import { logEvent } from "./api.js";
+import { obsConfig } from "./config.js";
+import { metricCounter, metricHistogram } from "./metrics.js";
+import { otelEnabled, withOtelServerSpan, withOtelSpan } from "./otel.js";
+/**
+ * The headers to attach to an outbound request to the agent so it CONTINUES
+ * this trace. Returns `{ traceparent }` when a trace is active, else `{}`. The
+ * agent's `parse_traceparent` accepts this exact format, and its request span
+ * becomes a child of our current span - so caller and callee are one tree.
+ */
+export function traceHeaders() {
+    const traceId = currentTraceId();
+    if (!traceId)
+        return {};
+    return { traceparent: formatTraceparent(traceId, currentSpanId(), isSampled()) };
+}
+/**
+ * Where this request's trace continues from.
+ *
+ * A W3C `traceparent` always wins: it is the standard and it is what the
+ * middleware and other services send. Only when there is none does the
+ * service's own `traceSeed` get a say, which is how a service continues a
+ * trace from a front end's correlation UUID rather than starting a second,
+ * unconnected one. A service that configures no seed gets
+ * `traceparent` or a fresh root, which is the behaviour three of the four
+ * copies had.
+ */
+export function resolveTraceSeed(req) {
+    const fromParent = parseTraceparent(req.headers.get("traceparent"));
+    if (fromParent)
+        return fromParent;
+    return obsConfig().traceSeed?.(req) ?? {};
+}
+/**
+ * Wrap a request handler in a trace. Continues an inbound `traceparent` (set by
+ * the Edge middleware, or sent by an upstream service) so the whole chain shares
+ * one trace_id; otherwise mints a fresh root. Logs request.received (debug) and
+ * request.completed (info, or error on 5xx), and best-effort sets X-Trace-Id on
+ * the response (wrapped in try/catch - a streaming response may forbid header
+ * mutation, and that must never break the request).
+ */
+export async function withApiTrace(req, handler, opts) {
+    const method = req.method;
+    let path = "";
+    try {
+        path = new URL(req.url).pathname;
+    }
+    catch {
+        /* leave path empty if the URL is unparseable */
+    }
+    const fields = { "http.method": method, "http.path": path, ...(opts?.fields ?? {}) };
+    // The first-party logging body. currentTraceId() is OTel-aware, so when export
+    // is on this logs (and stamps X-Trace-Id with) the OTel trace id.
+    const inner = () => runWithTrace(resolveTraceSeed(req), async () => {
+        bind(fields);
+        const start = Date.now();
+        logEvent("request.received", `${method} ${path}`, undefined, {
+            level: "debug",
+            logger: "http",
+        });
+        try {
+            const res = await handler();
+            const ms = Date.now() - start;
+            // One RED histogram per request. The label is the TEMPLATE, not the
+            // path: `/api/labs/abc123` and `/api/labs/def456` are one time series,
+            // not two. A service that configures no routeTemplate has few enough
+            // dynamic routes for the raw path to be safe; one that does not is how
+            // a metrics backend ends up with a million series.
+            metricHistogram("serve.request.duration", ms, {
+                route: routeLabel(path),
+                method,
+                status_class: `${Math.floor(res.status / 100)}xx`,
+            }, "ms");
+            logEvent("request.completed", `${method} ${path} -> ${res.status} in ${ms} ms`, { "http.status": res.status, dur_ms: ms }, {
+                // A service's own high-frequency machine traffic (cron polls and
+                // health checks firing every minute) is noise at
+                // INFO: the real work each does is logged separately. Those
+                // prefixes are configured per service, because one service's
+                // background poll is another's main path. A 5xx still surfaces as
+                // ERROR whatever the prefix.
+                level: res.status >= 500 ? "error" : isQuiet(path) ? "debug" : "info",
+                logger: "http",
+            });
+            try {
+                res.headers.set("X-Trace-Id", currentTraceId());
+            }
+            catch {
+                /* immutable/streaming response headers - best effort only */
+            }
+            return res;
+        }
+        catch (err) {
+            const ms = Date.now() - start;
+            logEvent("request.failed", `${method} ${path} raised after ${ms} ms`, { dur_ms: ms }, { level: "error", logger: "http", error: err });
+            throw err;
+        }
+    });
+    // When OTLP export is on, open a real SERVER span that CONTINUES the inbound
+    // W3C traceparent, then run the logging body inside it (which now adopts the
+    // OTel ids). When off, just run the body on the AsyncLocalStorage path.
+    return otelEnabled() ? withOtelServerSpan(`${method} ${path}`, req.headers, fields, inner) : inner();
+}
+/**
+ * Wrap a server action (which has no NextRequest) in a FRESH root trace named
+ * after the action, so each action invocation is its own story. Binds the
+ * action name and any extra fields, logs start/finish/failed, and records two
+ * domain metrics that complement the span-derived RED with a clean, alertable
+ * action signal:
+ *   - diveinto.action.duration: histogram of elapsed ms
+ *   - diveinto.action.count:    counter of invocations
+ * Both carry only {action, outcome} - the action NAME is a fixed, low-cardinality
+ * set and outcome is ok/error, so the time-series count stays bounded. We pass
+ * those attrs EXPLICITLY (not `fields`) on purpose: the bound `fields` carry
+ * per-entity ids / operator / email, which belong on the span and the logs but
+ * would explode the metric cardinality. See metrics.ts for the why.
+ */
+export async function withAction(name, fn, fields) {
+    const inner = () => runWithTrace({}, async () => {
+        bind({ "action.name": name, ...(fields ?? {}) });
+        const start = Date.now();
+        logEvent("action.started", `server action ${name}`, undefined, { logger: "action" });
+        try {
+            const out = await fn();
+            const ms = Date.now() - start;
+            recordActionMetrics(name, "ok", ms);
+            logEvent("action.completed", `server action ${name} ok in ${ms} ms`, { dur_ms: ms }, { logger: "action" });
+            return out;
+        }
+        catch (err) {
+            const ms = Date.now() - start;
+            recordActionMetrics(name, "error", ms);
+            logEvent("action.failed", `server action ${name} failed after ${ms} ms`, { dur_ms: ms }, { level: "error", logger: "action", error: err });
+            throw err;
+        }
+    });
+    // A server action has no inbound request, so when export is on this opens a
+    // fresh root OTel span (startActiveSpan with no active parent).
+    return otelEnabled() ? withOtelSpan(`action ${name}`, { "action.name": name, ...(fields ?? {}) }, inner) : inner();
+}
+/**
+ * Record the action duration histogram + invocation counter with the SAME
+ * low-cardinality attrs. Kept as one helper so the ok and error paths cannot
+ * drift apart, and so the cardinality contract lives in exactly one place: the
+ * only attributes are the fixed action name and a binary outcome - nothing
+ * per-entity. metricCounter/metricHistogram are themselves no-ops when export
+ * is off, so this is free in the common (no-collector) case.
+ */
+function recordActionMetrics(name, outcome, ms) {
+    const attrs = { action: name, outcome };
+    metricHistogram("diveinto.action.duration", ms, attrs, "ms");
+    metricCounter("diveinto.action.count", 1, attrs);
+}
+/** Apply the service's route template, if it configured one. */
+function routeLabel(path) {
+    const tpl = obsConfig().routeTemplate;
+    if (!tpl)
+        return path;
+    try {
+        return tpl(path);
+    }
+    catch {
+        // A bad template must not cost us the request or the metric.
+        return path;
+    }
+}
+/** True when this path's completion should log at debug rather than info. */
+function isQuiet(path) {
+    return obsConfig().quietPathPrefixes.some((p) => path.startsWith(p));
+}

package/dist/index.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @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
+ * is off until you set an endpoint. It grew out of consolidating four
+ * hand-maintained copies of the same library across four services, each of
+ * which had drifted and grown something the others lacked; this is the union
+ * of the four, and every one of those differences is pinned by a test.
+ *
+ * WHAT IT IS NOT: this module is runtime-agnostic and must stay importable
+ * from the Edge runtime. The Node-only pieces live behind their own imports:
+ * the OTLP start path is `@diveinto/obs/start`, and the file sinks are only
+ * wired by `setupLogging()`, which an app calls from `instrumentation.ts` on
+ * the Node runtime. Do not add a static `node:*` import here.
+ *
+ * Usage, once, from the app's instrumentation.ts:
+ *
+ *     import { createObs } from "@diveinto/obs";
+ *     export const obs = createObs({
+ *       service: "my-service",
+ *       envPrefix: "MYSVC",
+ *     });
+ *
+ * and everywhere else, plain named imports:
+ *
+ *     import { getLogger, withApiTrace, traceHeaders } from "@diveinto/obs";
+ *
+ * The record shape is the contract and is frozen:
+ *   ts level trace_id span_id parent_span_id logger event msg  + context
+ * A sibling Python implementation writes the same shape, which is what lets
+ * one grep follow a trace across services in either language.
+ */
+import { type ObsConfig } from "./config.js";
+import { bind, currentSpanId, currentTraceId, runWithTrace } from "./context.js";
+import { logEvent, withSpan, withTrace } from "./api.js";
+import { metricCounter, metricHistogram, timed } from "./metrics.js";
+import { getLogger } from "./record.js";
+import { traceHeaders, withAction, withApiTrace } from "./http.js";
+export type { ObsConfig, RouteTemplate, TraceSeedFn } from "./config.js";
+export { configure, obsConfig, resetConfigForTests } from "./config.js";
+export type { ErrorInfo, Fields, LevelInput, LevelName, ObsRecord, Sink, } from "./types.js";
+export { bind, currentSpanId, currentTraceId, formatTraceparent, isSampled, parseTraceparent, runWithTrace, runWithSpan, traceIdFromCorrelationId, } from "./context.js";
+export { getLogger, setObsRecorderForTests, toErrorInfo, type Logger } from "./record.js";
+export { logEvent, withSpan, withTrace } from "./api.js";
+export { metricCounter, metricHistogram, timed } from "./metrics.js";
+export { renderJson, renderPretty } from "./render.js";
+export { configureSinks, makeFileSink, makeStdoutSink } from "./sinks.js";
+export { isServerless, resetLoggingForTests, resolveFileTargets, setupLogging, type FileTarget, } from "./setup.js";
+export { currentIds, makeOtelLogSink, otelEnabled, withOtelServerSpan, withOtelSpan } from "./otel.js";
+export { resolveTraceSeed, traceHeaders, withAction, withApiTrace } from "./http.js";
+/**
+ * Configure the library and hand back the surface an app actually uses.
+ *
+ * Calling this is equivalent to `configure()` followed by `setupLogging()`,
+ * and the returned object is a convenience: every function on it is also a
+ * named export of this module, bound to the same single configuration. Apps
+ * that prefer plain imports can call `configure()` and ignore the return.
+ *
+ * `setupLogging()` is idempotent, which matters because Next calls
+ * `register()` more than once across HMR and dev.
+ */
+export declare function createObs(cfg: ObsConfig): {
+    getLogger: typeof getLogger;
+    logEvent: typeof logEvent;
+    withSpan: typeof withSpan;
+    withTrace: typeof withTrace;
+    withApiTrace: typeof withApiTrace;
+    withAction: typeof withAction;
+    traceHeaders: typeof traceHeaders;
+    runWithTrace: typeof runWithTrace;
+    currentTraceId: typeof currentTraceId;
+    currentSpanId: typeof currentSpanId;
+    bind: typeof bind;
+    metricCounter: typeof metricCounter;
+    metricHistogram: typeof metricHistogram;
+    timed: typeof timed;
+};

package/dist/index.js

@@ -0,0 +1,82 @@
+/**
+ * @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
+ * is off until you set an endpoint. It grew out of consolidating four
+ * hand-maintained copies of the same library across four services, each of
+ * which had drifted and grown something the others lacked; this is the union
+ * of the four, and every one of those differences is pinned by a test.
+ *
+ * WHAT IT IS NOT: this module is runtime-agnostic and must stay importable
+ * from the Edge runtime. The Node-only pieces live behind their own imports:
+ * the OTLP start path is `@diveinto/obs/start`, and the file sinks are only
+ * wired by `setupLogging()`, which an app calls from `instrumentation.ts` on
+ * the Node runtime. Do not add a static `node:*` import here.
+ *
+ * Usage, once, from the app's instrumentation.ts:
+ *
+ *     import { createObs } from "@diveinto/obs";
+ *     export const obs = createObs({
+ *       service: "my-service",
+ *       envPrefix: "MYSVC",
+ *     });
+ *
+ * and everywhere else, plain named imports:
+ *
+ *     import { getLogger, withApiTrace, traceHeaders } from "@diveinto/obs";
+ *
+ * The record shape is the contract and is frozen:
+ *   ts level trace_id span_id parent_span_id logger event msg  + context
+ * A sibling Python implementation writes the same shape, which is what lets
+ * one grep follow a trace across services in either language.
+ */
+import { configure } from "./config.js";
+import { bind, currentSpanId, currentTraceId, runWithTrace } from "./context.js";
+import { logEvent, withSpan, withTrace } from "./api.js";
+import { metricCounter, metricHistogram, timed } from "./metrics.js";
+import { getLogger } from "./record.js";
+import { setupLogging } from "./setup.js";
+import { traceHeaders, withAction, withApiTrace } from "./http.js";
+export { configure, obsConfig, resetConfigForTests } from "./config.js";
+export { bind, currentSpanId, currentTraceId, formatTraceparent, isSampled, parseTraceparent, runWithTrace, runWithSpan, traceIdFromCorrelationId, } from "./context.js";
+export { getLogger, setObsRecorderForTests, toErrorInfo } from "./record.js";
+export { logEvent, withSpan, withTrace } from "./api.js";
+export { metricCounter, metricHistogram, timed } from "./metrics.js";
+export { renderJson, renderPretty } from "./render.js";
+export { configureSinks, makeFileSink, makeStdoutSink } from "./sinks.js";
+export { isServerless, resetLoggingForTests, resolveFileTargets, setupLogging, } from "./setup.js";
+export { currentIds, makeOtelLogSink, otelEnabled, withOtelServerSpan, withOtelSpan } from "./otel.js";
+export { resolveTraceSeed, traceHeaders, withAction, withApiTrace } from "./http.js";
+/**
+ * Configure the library and hand back the surface an app actually uses.
+ *
+ * Calling this is equivalent to `configure()` followed by `setupLogging()`,
+ * and the returned object is a convenience: every function on it is also a
+ * named export of this module, bound to the same single configuration. Apps
+ * that prefer plain imports can call `configure()` and ignore the return.
+ *
+ * `setupLogging()` is idempotent, which matters because Next calls
+ * `register()` more than once across HMR and dev.
+ */
+export function createObs(cfg) {
+    configure(cfg);
+    setupLogging();
+    return {
+        getLogger,
+        logEvent,
+        withSpan,
+        withTrace,
+        withApiTrace,
+        withAction,
+        traceHeaders,
+        runWithTrace,
+        currentTraceId,
+        currentSpanId,
+        bind,
+        metricCounter,
+        metricHistogram,
+        timed,
+    };
+}

package/dist/metrics.d.ts

@@ -0,0 +1,26 @@
+import { type Attributes } from "@opentelemetry/api";
+/**
+ * Add to a monotonic counter (default +1). No-op when export is off. `attrs` must
+ * be low-cardinality (see the file header) - the type is OTel's Attributes, but
+ * the cardinality contract is on the caller, not the type system.
+ */
+export declare function metricCounter(name: string, value?: number, attrs?: Attributes): void;
+/**
+ * Record one value into a histogram (latency, size, ...). No-op when export is
+ * off. Pass `unit` (e.g. "ms") on the first call to label the instrument; same
+ * low-cardinality rule applies to `attrs`.
+ */
+export declare function metricHistogram(name: string, value: number, attrs?: Attributes, unit?: string): void;
+/**
+ * Time `fn`, recording its elapsed milliseconds into the `name` histogram (unit
+ * "ms") with an `outcome` attribute of "ok" or "error". The outcome is folded
+ * into the histogram's own attributes (not a separate counter) so a single
+ * instrument carries both the latency distribution and the success/failure split
+ * - which is the standard RED-style shape an alert can read directly.
+ *
+ * When export is off this is a thin passthrough: it still runs `fn` (so callers
+ * can wrap unconditionally) but records nothing and adds no measurable overhead.
+ * It never swallows the error - it re-throws after stamping outcome="error", so
+ * the caller's control flow is unchanged.
+ */
+export declare function timed<T>(name: string, attrs: Attributes | undefined, fn: () => Promise<T> | T): Promise<T>;