workers-axiom 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sapt
+
+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,156 @@
+# workers-axiom
+
+Structured logging, tracing, and metrics for Cloudflare Workers, with an Axiom tail-worker sink.
+
+> **Status:** used internally by Sapt. Open source, MIT-licensed. PRs welcome, support is best-effort.
+
+## What it does
+
+- **Producer** (`workers-axiom/producer`): a `Logger` your worker uses to emit structured logs, metrics, and OpenTelemetry-style spans. Output is plain `console.log` JSON — nothing leaves the worker directly.
+- **Tail consumer** (`workers-axiom/tail`): a factory that builds a Cloudflare `tail()` handler. Point your other workers at it via `tail_consumers`. It parses the producer's JSON, batches it, and forwards logs to Axiom's ingest endpoint and sampled spans to Axiom's OTLP traces endpoint.
+
+The two halves communicate through a shared wire format (`workers-axiom/protocol`) and nothing else. You can deploy them independently.
+
+## Install
+
+```bash
+pnpm add workers-axiom
+```
+
+## Producer usage
+
+```ts
+import { withTrace, type Logger } from 'workers-axiom/producer'
+
+interface Env { ENVIRONMENT: string }
+
+export default {
+  fetch: (request: Request, env: Env, ctx: ExecutionContext) =>
+    withTrace(
+      {
+        name: 'api.fetch',
+        kind: 'server',
+        service: 'my-api',
+        environment: env.ENVIRONMENT,
+        headers: request.headers, // continues inbound traceparent if present
+      },
+      async (logger) => handle(request, env, logger),
+      {
+        onError: (_err, logger) => {
+          logger.error(_err, 'unhandled')
+          return new Response('Internal error', { status: 500 })
+        },
+      }
+    ),
+}
+
+async function handle(request: Request, env: Env, logger: Logger) {
+  logger.info('handling request')
+  return logger.span('db.query', { kind: 'client' }, async (logger) => {
+    // ... use logger.tracingHeaders() on outbound fetches to propagate the trace
+    return new Response('ok')
+  })
+}
+```
+
+## Tail consumer usage
+
+A minimal Worker:
+
+```ts
+// src/index.ts
+import { createTailHandler } from 'workers-axiom/tail'
+
+interface Env {
+  AXIOM_TOKEN: string
+  AXIOM_DATASET: string
+}
+
+export default {
+  tail: (events: TraceItem[], env: Env, ctx: ExecutionContext) =>
+    createTailHandler({
+      axiomToken: env.AXIOM_TOKEN,
+      axiomDataset: env.AXIOM_DATASET,
+    })(events, env, ctx),
+}
+```
+
+```jsonc
+// wrangler.jsonc for the tail worker
+{
+  "name": "my-tail-worker",
+  "main": "src/index.ts",
+  "compatibility_date": "2026-01-01",
+  "vars": { "AXIOM_DATASET": "my-dataset" }
+  // AXIOM_TOKEN set via: wrangler secret put AXIOM_TOKEN
+}
+```
+
+Then opt each producing worker in:
+
+```jsonc
+// wrangler.jsonc for a producer worker
+{
+  "tail_consumers": [{ "service": "my-tail-worker" }]
+}
+```
+
+## How it works
+
+Three event types flow through `console.log` from producer to tail:
+
+- **`type: "log"` / `"metric"` / `"error"`** — forwarded to Axiom's ingest endpoint (`https://us-east-1.aws.edge.axiom.co/v1/ingest/{dataset}` by default).
+- **`type: "span"`** — wire format defined in `workers-axiom/protocol`. The tail worker filters by `sampled === true`, converts to OTLP, and POSTs to `https://api.axiom.co/v1/traces`.
+- **`type: "summary_properties"`** — emitted by `logger.summary({ ... })`. Merged onto a synthesized `invocation_summary` event the tail worker writes for every worker invocation (with CPU/wall time, request metadata from `event.event`, and `trace_id`).
+
+Sampling is decided once at the trace root, propagated via `traceparent`, and stamped on every span. Logs, metrics, and errors are forwarded unconditionally — sampling gates traces only.
+
+## Config reference
+
+### `createTailHandler(config)`
+
+| Field | Required | Default | Notes |
+|---|---|---|---|
+| `axiomToken` | yes | — | Axiom API token, bearer-auth. |
+| `axiomDataset` | yes | — | Dataset name for both ingest and OTLP traces. |
+| `ingestBaseUrl` | no | `https://us-east-1.aws.edge.axiom.co/v1/ingest` | Override for EU edge or self-hosted Axiom. Dataset name is appended. |
+| `tracesEndpoint` | no | `https://api.axiom.co/v1/traces` | Full URL of the OTLP traces endpoint. |
+
+### `withTrace(options, fn, hooks?)` / `createLogger(options)`
+
+| Field | Required | Default | Notes |
+|---|---|---|---|
+| `service` | yes | — | OTel `service.name`. |
+| `environment` | no | — | OTel `deployment.environment`. `"development"` enables pretty-printed logs and suppresses metrics. |
+| `level` | no | `"info"` | Log level. Forced to `"debug"` when `environment === "development"`. |
+| `context` | no | `{}` | Correlation fields merged into every emitted record. |
+| `isExpectedError` | no | — | Predicate marking expected/business errors so spans aren't flagged as failed. |
+| `headers` | no | — | Inbound `Request.headers`. Continues `traceparent` if present. |
+| `sampleRate` | no | `1` | Trace-root sampling probability. Inbound traces inherit the upstream verdict. |
+| `kv` | no | — | KV namespace for dynamic log-level lookup at key `logLevel` (or `logLevel:{logLevelKey}`). |
+| `name` | yes (`withTrace`) | — | Root span name, e.g. `"api.fetch"`, `"scheduled.tick"`. |
+| `kind` | no (`withTrace`) | `"server"` | Use `"consumer"` for queue/cron handlers. |
+
+## Outbound trace propagation
+
+The logger doesn't auto-instrument outbound `fetch`. Wrap each outbound call in `logger.span(...)` and copy `logger.tracingHeaders()` onto the request — that's what makes the downstream service join the same trace:
+
+```ts
+await logger.span('backend.fetch', { kind: 'client' }, async (logger) => {
+  const headers = new Headers(init.headers)
+  for (const [k, v] of logger.tracingHeaders()) headers.set(k, v)
+  return fetch(url, { ...init, headers })
+})
+```
+
+`tracingHeaders()` on an unbound root logger returns an empty `Headers` — you must be inside a `.span(...)` for propagation to fire.
+
+## Limitations
+
+- Axiom-specific. There is no sink abstraction; the tail worker speaks Axiom's ingest API and OTLP/HTTP JSON. If you need a different backend, fork the `tail/` directory.
+- No browser entry. This package is server-side only, targeted at Cloudflare Workers (and works in any environment with `crypto.getRandomValues` and `console.log`).
+- The `tail()` handler runs forwarding synchronously, not via `waitUntil`, so ingest failures surface in tail logs.
+
+## License
+
+MIT

package/dist/producer/index.d.ts

@@ -0,0 +1,4 @@
+export { LogLevel, createLogger, noopLogger, withTrace, type KVLike, type LogContext, type Logger, type LoggerOptions, type WithTraceOptions, } from './logger';
+export type { SpanOptions, TraceContext } from './tracing';
+export { SPAN_EVENT_TYPE, SUMMARY_PROPERTIES_TYPE, isSpanEvent, parseTraceparent, formatTraceparent, type AttributeValue, type SpanEvent, type SpanKind, type SpanStatus, type TraceParent, } from '../protocol';
+//# sourceMappingURL=index.d.ts.map

package/dist/producer/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/producer/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,YAAY,EACZ,UAAU,EACV,SAAS,EACT,KAAK,MAAM,EACX,KAAK,UAAU,EACf,KAAK,MAAM,EACX,KAAK,aAAa,EAClB,KAAK,gBAAgB,GACtB,MAAM,UAAU,CAAA;AAEjB,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAI1D,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,QAAQ,EACb,KAAK,UAAU,EACf,KAAK,WAAW,GACjB,MAAM,aAAa,CAAA"}

package/dist/producer/index.js

@@ -0,0 +1,5 @@
+export { LogLevel, createLogger, noopLogger, withTrace, } from './logger';
+// Re-export wire-format types that consumers commonly need when extending
+// the producer (custom attributes, propagation helpers in middleware, etc.).
+export { SPAN_EVENT_TYPE, SUMMARY_PROPERTIES_TYPE, isSpanEvent, parseTraceparent, formatTraceparent, } from '../protocol';
+//# sourceMappingURL=index.js.map

package/dist/producer/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/producer/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,YAAY,EACZ,UAAU,EACV,SAAS,GAMV,MAAM,UAAU,CAAA;AAIjB,0EAA0E;AAC1E,6EAA6E;AAC7E,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,WAAW,EACX,gBAAgB,EAChB,iBAAiB,GAMlB,MAAM,aAAa,CAAA"}

package/dist/producer/logger.d.ts

@@ -0,0 +1,146 @@
+import { type AttributeValue, type SpanKind } from '../protocol';
+import { type SpanOptions, type TraceContext } from './tracing';
+/**
+ * Bag of correlation fields (requestId, actorId, etc.). Has no semantic meaning
+ * to the logger — it's just merged into emitted JSON. First-class metadata
+ * (`service`, `environment`, trace IDs) lives on the logger directly, not here.
+ */
+export type LogContext = Record<string, unknown>;
+export interface Logger {
+    /** OTel `service.name`. */
+    readonly service: string;
+    /** OTel `deployment.environment`, if set. */
+    readonly environment: string | undefined;
+    readonly context: Readonly<LogContext>;
+    readonly trace: TraceContext;
+    debug(message: string): void;
+    info(message: string): void;
+    warn(message: string): void;
+    error(error: unknown, message?: string): void;
+    metric(event: string, data?: Record<string, unknown>): void;
+    /**
+     * Emit fields the tail worker should merge onto this invocation's
+     * `invocation_summary` event. Use for cross-cutting correlation fields
+     * (`requestId`, `trace_id`, identity, etc.) that should appear on the
+     * per-invocation summary regardless of which log/metric also carried them.
+     *
+     * Last-write-wins on collision per invocation in the tail worker.
+     */
+    summary(properties: Record<string, unknown>): void;
+    /** Extend the correlation context. Returns a new logger sharing trace state. */
+    child(context: LogContext): Logger;
+    /**
+     * Run an async function inside a new span. The child logger passed to `fn`
+     * has the new span's traceId/spanId bound, so any logs/metrics emitted
+     * inside automatically correlate with the span.
+     *
+     * Errors thrown by `fn` are recorded on the span and re-thrown unchanged.
+     * Errors matched by the `isExpectedError` predicate (configured at logger
+     * creation) are recorded as `status: 'ok'` — they're expected user-facing
+     * failures, not span failures.
+     */
+    span<T>(name: string, options: SpanOptions, fn: (logger: Logger) => Promise<T>): Promise<T>;
+    /**
+     * Returns headers to propagate the current trace context on outbound calls.
+     * Always include the result on outbound `fetch` calls (including service
+     * bindings) to maintain a single distributed trace across services.
+     */
+    tracingHeaders(): Headers;
+}
+export declare const LogLevel: {
+    readonly debug: 0;
+    readonly info: 1;
+    readonly warn: 2;
+    readonly error: 3;
+};
+export type LogLevel = keyof typeof LogLevel;
+export declare function isValidLogLevel(value: unknown): value is LogLevel;
+export interface KVLike {
+    get(key: string): Promise<string | null>;
+}
+export interface LoggerOptions {
+    /**
+     * Logical service name. Required on every logger because OpenTelemetry
+     * mandates `service.name` on every span; loggers without it would produce
+     * spans tagged `unknown_service` by collectors.
+     */
+    service: string;
+    /**
+     * Deployment environment. Maps to OTel `deployment.environment` on spans.
+     * When set to `'development'`, metrics are suppressed and logs are
+     * pretty-printed instead of emitted as JSON.
+     */
+    environment?: string;
+    /**
+     * Explicit log level. Used as the fallback when `kv` is also provided but
+     * doesn't contain a valid level. Defaults to `'info'`.
+     */
+    level?: LogLevel;
+    /** Additional correlation fields (requestId, etc.). */
+    context?: LogContext;
+    /**
+     * Predicate identifying expected/business errors that should not mark spans
+     * as failed. Typical use: `(err) => err instanceof MyExpectedError`. The
+     * library stays domain-free; the predicate is the explicit contract.
+     */
+    isExpectedError?: (err: unknown) => boolean;
+    /**
+     * Inbound headers carrying `traceparent`. When present, the logger continues
+     * the inbound trace; otherwise it starts a fresh one. Pass at HTTP entrypoints.
+     */
+    headers?: Headers;
+    /**
+     * Probability (0..1) of sampling a freshly minted trace. The verdict is
+     * decided once at the trace root, propagated to all descendants via
+     * `traceparent`, and stamped onto every emitted record. Inbound traces
+     * inherit the upstream verdict and ignore this. Defaults to 1 (sample all).
+     *
+     * Logs/metrics/errors are always forwarded regardless — only span forwarding
+     * to Axiom's traces store is gated by the verdict.
+     */
+    sampleRate?: number;
+    /**
+     * KV namespace for log-level lookup. When set, the logger reads `logLevel`
+     * (or `logLevel:{logLevelKey}` if a suffix is provided) from KV and uses
+     * that level if valid; otherwise falls back to `level`. Forced to `'debug'`
+     * in development.
+     */
+    kv?: KVLike;
+    /** Optional KV key suffix; looks up `logLevel:{logLevelKey}` instead of `logLevel`. */
+    logLevelKey?: string;
+}
+/**
+ * Create a new logger. If `options.headers` carries a `traceparent`, the trace
+ * is continued; otherwise a fresh trace starts.
+ *
+ * Async because the log level may be resolved from KV. If `options.kv` is
+ * omitted, no I/O happens but the function is still async for shape consistency.
+ *
+ * Most entrypoints should use `withTrace` instead, which calls `createLogger`
+ * and wraps the handler in a root span. `createLogger` is the right primitive
+ * only when there's no enclosing async scope to open a span around.
+ */
+export declare function createLogger(options: LoggerOptions): Promise<Logger>;
+export interface WithTraceOptions extends LoggerOptions {
+    /** Span name. Use the entrypoint's logical operation, e.g. `api.fetch`, `scheduled.tick`. */
+    name: string;
+    /** Span kind. Defaults to `'server'`. Use `'consumer'` for queue/cron. */
+    kind?: SpanKind;
+    /** Attributes to attach to the root span. */
+    attributes?: Record<string, AttributeValue>;
+}
+/**
+ * Entrypoint helper: build a logger and wrap the handler in a root span in one
+ * call. The root span is what local child spans (`logger.span(...)`) parent to,
+ * so without it those children are orphaned in the trace viewer.
+ *
+ * For HTTP entrypoints, pass `headers` to continue any inbound `traceparent`.
+ * For queue/cron entrypoints, omit `headers` and the trace starts fresh.
+ * Pass `kv` to resolve the log level from KV.
+ */
+export declare function withTrace<T>(options: WithTraceOptions, fn: (logger: Logger) => Promise<T>, hooks?: {
+    onError?: (err: unknown, logger: Logger) => T | Promise<T>;
+}): Promise<T>;
+/** No-op logger for tests and environments where logging should be suppressed. */
+export declare const noopLogger: Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/producer/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/producer/logger.ts"],"names":[],"mappings":"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"}

package/dist/producer/logger.js

@@ -0,0 +1,179 @@
+import { formatTraceparent, generateTraceId, parseTraceparent, SUMMARY_PROPERTIES_TYPE, } from '../protocol';
+import { createClock, runSpan, toSpanException, } from './tracing';
+const BASE_LOG_LEVEL_KEY = 'logLevel';
+export const LogLevel = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+export function isValidLogLevel(value) {
+    return typeof value === 'string' && value in LogLevel;
+}
+/**
+ * Create a new logger. If `options.headers` carries a `traceparent`, the trace
+ * is continued; otherwise a fresh trace starts.
+ *
+ * Async because the log level may be resolved from KV. If `options.kv` is
+ * omitted, no I/O happens but the function is still async for shape consistency.
+ *
+ * Most entrypoints should use `withTrace` instead, which calls `createLogger`
+ * and wraps the handler in a root span. `createLogger` is the right primitive
+ * only when there's no enclosing async scope to open a span around.
+ */
+export async function createLogger(options) {
+    const level = await resolveLogLevel(options);
+    const incoming = options.headers
+        ? parseTraceparent(options.headers.get('traceparent'))
+        : undefined;
+    const sampled = incoming?.sampled ?? Math.random() < (options.sampleRate ?? 1);
+    return _createLogger({ ...options, level }, createClock(), {
+        trace_id: incoming?.trace_id ?? generateTraceId(),
+        span_id: undefined,
+        parent_span_id: incoming?.span_id,
+        sampled,
+    });
+}
+async function resolveLogLevel(opts) {
+    if (opts.environment === 'development')
+        return 'debug';
+    if (!opts.kv)
+        return opts.level ?? 'info';
+    const key = opts.logLevelKey ? `${BASE_LOG_LEVEL_KEY}:${opts.logLevelKey}` : BASE_LOG_LEVEL_KEY;
+    const value = await opts.kv.get(key);
+    return isValidLogLevel(value) ? value : (opts.level ?? 'info');
+}
+function _createLogger(options, clock, trace) {
+    const { service, environment, isExpectedError, level = 'info' } = options;
+    const context = { ...options.context };
+    const isDev = environment === 'development';
+    const shouldLog = (logLevel) => {
+        return LogLevel[logLevel] >= LogLevel[level];
+    };
+    const emit = (entry) => {
+        // eslint-disable-next-line no-console
+        console.log(JSON.stringify({
+            service,
+            environment,
+            ...context,
+            trace_id: trace.trace_id,
+            span_id: trace.span_id,
+            parent_span_id: trace.parent_span_id,
+            sampled: trace.sampled,
+            ...entry,
+        }));
+    };
+    const log = (logLevel, message) => {
+        if (!shouldLog(logLevel))
+            return;
+        if (isDev) {
+            const levelTag = logLevel.toUpperCase().padEnd(5);
+            // eslint-disable-next-line no-console
+            console.log(`${levelTag} ${message}`);
+        }
+        else {
+            emit({ type: 'log', level: logLevel, message });
+        }
+    };
+    return {
+        service,
+        environment,
+        context,
+        trace,
+        debug(message) {
+            log('debug', message);
+        },
+        info(message) {
+            log('info', message);
+        },
+        warn(message) {
+            log('warn', message);
+        },
+        error(error, message) {
+            if (!shouldLog('error'))
+                return;
+            const exception = error instanceof Error ? toSpanException(error) : undefined;
+            const body = message ?? (error instanceof Error ? error.message : String(error));
+            if (isDev) {
+                // eslint-disable-next-line no-console
+                console.log(`ERROR ${body}${exception?.stacktrace ? `\n${exception.stacktrace}` : ''}`);
+            }
+            else {
+                emit({ type: 'error', message: body, ...(exception !== undefined ? { exception } : {}) });
+            }
+        },
+        metric(event, data) {
+            if (isDev)
+                return;
+            emit({ type: 'metric', event, ...data });
+        },
+        summary(properties) {
+            // Bypass `emit` so trace-context, service, environment, and inherited
+            // context don't ride along. Summary records are invocation-scoped and
+            // exist only to feed `invocation_summary` in the tail worker.
+            // eslint-disable-next-line no-console
+            console.log(JSON.stringify({ type: SUMMARY_PROPERTIES_TYPE, ...properties }));
+        },
+        child(newContext) {
+            return _createLogger({ ...options, context: { ...context, ...newContext } }, clock, trace);
+        },
+        async span(name, spanOptions, fn) {
+            return runSpan({
+                parent: trace,
+                resource: { service, environment },
+                name,
+                options: spanOptions,
+                clock,
+                isExpectedError,
+                fn: (childCtx) => fn(_createLogger(options, clock, childCtx)),
+                onUnexpectedError: (err, childCtx) => _createLogger(options, clock, childCtx).error(err, `span "${name}" failed`),
+            });
+        },
+        tracingHeaders() {
+            const headers = new Headers();
+            if (trace.span_id !== undefined) {
+                headers.set('traceparent', formatTraceparent(trace.trace_id, trace.span_id, trace.sampled));
+            }
+            return headers;
+        },
+    };
+}
+/**
+ * Entrypoint helper: build a logger and wrap the handler in a root span in one
+ * call. The root span is what local child spans (`logger.span(...)`) parent to,
+ * so without it those children are orphaned in the trace viewer.
+ *
+ * For HTTP entrypoints, pass `headers` to continue any inbound `traceparent`.
+ * For queue/cron entrypoints, omit `headers` and the trace starts fresh.
+ * Pass `kv` to resolve the log level from KV.
+ */
+export async function withTrace(options, fn, hooks) {
+    const { name, kind = 'server', attributes, ...loggerOptions } = options;
+    const logger = await createLogger(loggerOptions);
+    try {
+        return await logger.span(name, { kind, attributes }, fn);
+    }
+    catch (err) {
+        if (hooks?.onError) {
+            return await hooks.onError(err, logger);
+        }
+        throw err;
+    }
+}
+/** No-op logger for tests and environments where logging should be suppressed. */
+export const noopLogger = {
+    service: '',
+    environment: undefined,
+    context: {},
+    trace: { trace_id: '', span_id: undefined, parent_span_id: undefined, sampled: false },
+    debug: () => { },
+    info: () => { },
+    warn: () => { },
+    error: () => { },
+    metric: () => { },
+    summary: () => { },
+    child: () => noopLogger,
+    span: (_name, _options, fn) => fn(noopLogger),
+    tracingHeaders: () => new Headers(),
+};
+//# sourceMappingURL=logger.js.map

package/dist/producer/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/producer/logger.ts"],"names":[],"mappings":"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"}

package/dist/producer/tracing/clock.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Monotonic-anchored wall clock for span timing.
+ *
+ * Span timestamps come from a single anchor captured at root-logger creation:
+ *   - `unixMsAtAnchor` — Date.now() at anchor time (wall clock)
+ *   - `perfAtAnchor`   — performance.now() at anchor time (monotonic, sub-ms)
+ *
+ * Subsequent reads compute `unixMsAtAnchor + (performance.now() - perfAtAnchor)`.
+ * This preserves sub-ms ordering within a request and avoids drift if Date.now()
+ * jumps mid-request (rare on Workers, but free to guard against).
+ *
+ * Cross-service clock skew is not addressed here — Workers in different colos may
+ * have small wall-clock differences. Tracing UIs tolerate this; it's not fixable
+ * from inside the worker.
+ */
+export interface Clock {
+    /** Returns the current time as Unix epoch nanoseconds (string, no precision loss). */
+    nowUnixNano(): string;
+}
+export declare function createClock(): Clock;
+//# sourceMappingURL=clock.d.ts.map

package/dist/producer/tracing/clock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.d.ts","sourceRoot":"","sources":["../../../src/producer/tracing/clock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,KAAK;IACpB,sFAAsF;IACtF,WAAW,IAAI,MAAM,CAAA;CACtB;AAED,wBAAgB,WAAW,IAAI,KAAK,CAWnC"}

package/dist/producer/tracing/clock.js

@@ -0,0 +1,17 @@
+export function createClock() {
+    const unixMsAtAnchor = Date.now();
+    const perfAtAnchor = performanceNowOrFallback();
+    return {
+        nowUnixNano() {
+            const elapsedMs = performanceNowOrFallback() - perfAtAnchor;
+            const unixMs = unixMsAtAnchor + elapsedMs;
+            return BigInt(Math.trunc(unixMs * 1_000_000)).toString();
+        },
+    };
+}
+function performanceNowOrFallback() {
+    return typeof performance !== 'undefined' && typeof performance.now === 'function'
+        ? performance.now()
+        : Date.now();
+}
+//# sourceMappingURL=clock.js.map

package/dist/producer/tracing/clock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.js","sourceRoot":"","sources":["../../../src/producer/tracing/clock.ts"],"names":[],"mappings":"AAoBA,MAAM,UAAU,WAAW;IACzB,MAAM,cAAc,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;IACjC,MAAM,YAAY,GAAG,wBAAwB,EAAE,CAAA;IAE/C,OAAO;QACL,WAAW;YACT,MAAM,SAAS,GAAG,wBAAwB,EAAE,GAAG,YAAY,CAAA;YAC3D,MAAM,MAAM,GAAG,cAAc,GAAG,SAAS,CAAA;YACzC,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAA;QAC1D,CAAC;KACF,CAAA;AACH,CAAC;AAED,SAAS,wBAAwB;IAC/B,OAAO,OAAO,WAAW,KAAK,WAAW,IAAI,OAAO,WAAW,CAAC,GAAG,KAAK,UAAU;QAChF,CAAC,CAAC,WAAW,CAAC,GAAG,EAAE;QACnB,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAA;AAChB,CAAC"}

package/dist/producer/tracing/index.d.ts

@@ -0,0 +1,3 @@
+export { createClock, type Clock } from './clock';
+export { runSpan, toSpanException, type ChildTraceContext, type SpanOptions, type TraceContext, } from './span';
+//# sourceMappingURL=index.d.ts.map

package/dist/producer/tracing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/producer/tracing/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,KAAK,KAAK,EAAE,MAAM,SAAS,CAAA;AACjD,OAAO,EACL,OAAO,EACP,eAAe,EACf,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,YAAY,GAClB,MAAM,QAAQ,CAAA"}

package/dist/producer/tracing/index.js

@@ -0,0 +1,3 @@
+export { createClock } from './clock';
+export { runSpan, toSpanException, } from './span';
+//# sourceMappingURL=index.js.map

package/dist/producer/tracing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/producer/tracing/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAc,MAAM,SAAS,CAAA;AACjD,OAAO,EACL,OAAO,EACP,eAAe,GAIhB,MAAM,QAAQ,CAAA"}