@gnldev/otel 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Karaca Yılmaz (https://gnl.dev)
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,100 @@
+# @gnldev/otel
+
+Converts the journal into a real **OpenTelemetry trace** and sends it to a SpanExporter (or an OTLP endpoint). Deterministic span ids → **idempotent**; since it's produced post-hoc from the journal, it stays complete even after a crash and consistent across replays = **crash-proof, idempotent observability** — exporting the same run twice produces the same trace rather than a duplicate (live-instrumenting frameworks cannot offer this).
+
+> Install: `pnpm add @gnldev/otel` — or use it from a [repo clone](https://github.com/Karaca7/gnldev): `pnpm install && pnpm -r build`.
+
+```bash
+npm i @gnldev/otel   # peer: @gnldev/durable, (optional) @opentelemetry/exporter-trace-otlp-http
+```
+
+```ts
+import { exportRun } from '@gnldev/otel';
+
+// Send a run to an OTLP collector (Jaeger/Tempo/Honeycomb…).
+const { traceId, spans } = await exportRun(journal, 'order-123', {
+  endpoint: 'http://localhost:4318/v1/traces',
+  serviceName: 'support-desk',
+});
+
+// Test: pass a ready-made InMemorySpanExporter → getFinishedSpans().
+```
+
+## API
+- `exportRun(journal, runId, opts?) → { traceId, spans, exporter }`
+  - `opts`: `exporter?` (ready-made SpanExporter) · `endpoint?` (OTLP-HTTP, set up lazily) · `serviceName?` · `pricing?` · `modelId?` · `redact?`
+
+### `redact` — the one free-text value a span carries
+
+Spans from this package hold model ids, finish reasons, token counts and tool statuses; prompts, responses and tool results are never read. The single exception is a **failed run's error message**, which travels as `gnl.error` and as the root span's status message.
+
+That message is not always your own text — a provider refusing a request commonly echoes the offending input back inside it. And a processor chain does not cover this path: `piiRedactor` hooks `processInput`/`processOutput`/`processToolResult`, while a run's verdict is written by `recordRunOutcome` in `@gnldev/durable`, which no processor sees. So with the redactor installed, the address still reaches your collector — which for a hosted backend is a third party.
+
+It stays raw by default, because the message is the main debugging value a trace carries and this package cannot know whether `endpoint` is your own collector. One line turns it on, sharing `piiRedactor`'s defaults:
+
+```ts
+import { exportRun } from '@gnldev/otel';
+import { piiTextRedactor } from '@gnldev/processors';
+
+await exportRun(journal, 'order-123', {
+  endpoint: 'http://localhost:4318/v1/traces',
+  redact: piiTextRedactor(),
+});
+```
+
+A redactor that throws or returns a non-string **drops** the message rather than falling back to the raw text — the run is still exported as failed, only the reason is withheld.
+
+## How it works
+Each model/tool journal entry maps to a span; trace/span ids are derived from runId+seq (deterministic) → exporting the same run again produces the same trace. Cost/token span attributes are added via `getRunCost`.
+
+## Zero-dependency OTLP/HTTP JSON exporter (`exportRunToOtlp` / `toOtlpJson`)
+
+The `exportRun` above uses `@opentelemetry/sdk-trace-base` (a dependency of this package, installed for you). Alongside it there is also a smaller alternative that **doesn't need any OTel SDK** — it manually converts `packages/durable`'s `toTraceSpans` output into an OTLP/HTTP JSON body and POSTs it with plain `fetch` (~8KB footprint: just `node:crypto` + the global `fetch`).
+
+```ts
+import { exportRunToOtlp, toOtlpJson } from '@gnldev/otel';
+import { toTraceSpans } from '@gnldev/durable';
+
+// Send a run directly to an OTLP/HTTP collector.
+const { traceId, spans, ok, status } = await exportRunToOtlp(journal, 'order-123', {
+  endpoint: process.env.OTLP_ENDPOINT!, // e.g. 'http://localhost:4318/v1/traces'
+  headers: process.env.OTLP_HEADERS ? JSON.parse(process.env.OTLP_HEADERS) : undefined,
+  serviceName: 'support-desk',
+});
+
+// Network-free testing / custom delivery: a PURE function.
+const spans2 = await toTraceSpans(journal, 'order-123');
+const payload = toOtlpJson(spans2, { runId: 'order-123', serviceName: 'support-desk' });
+```
+
+### API
+- `toOtlpJson(spans: TraceSpan[], opts) → OtlpPayload` — PURE, no network. `opts`: `runId` (required) · `serviceName?` · `resourceAttributes?` · `now?` (fallback timestamp for entries without a `ts`, for test determinism).
+- `exportRunToOtlp(journal, runId, opts) → { traceId, spans, ok, status }` — `toTraceSpans` + `toOtlpJson` + `fetch(POST)`. `opts`: `endpoint` (required) · `headers?` · `serviceName?` · `resourceAttributes?` · `now?`.
+- `otlpTraceId(runId)` / `otlpSpanId(runId, seq | 'root')` — deterministic id generators (idempotent export).
+
+### Connecting to your own endpoint (Langfuse / Datadog / Jaeger / Honeycomb …)
+
+This package **never sends to a server of ours** — the `endpoint` is always supplied by the caller, opt-in. How this relates to the "no telemetry" principle: gnl sends data nowhere by default; the OTLP exporter only runs when `endpoint` is explicitly given, and that data always goes to the CALLER's own chosen collector/backend.
+
+```bash
+# Local OTel Collector / Jaeger (OTLP/HTTP ingest, usually port 4318)
+OTLP_ENDPOINT=http://localhost:4318/v1/traces
+
+# Langfuse (OTLP ingest endpoint; project public/secret key in the Basic Auth header)
+OTLP_ENDPOINT=https://cloud.langfuse.com/api/public/otel/v1/traces
+OTLP_HEADERS='{"authorization":"Basic <base64(public_key:secret_key)>"}'
+
+# Datadog Agent (if the OTLP receiver is enabled, usually 4318)
+OTLP_ENDPOINT=http://localhost:4318/v1/traces
+OTLP_HEADERS='{"dd-api-key":"<DATADOG_API_KEY>"}'
+
+# Honeycomb
+OTLP_ENDPOINT=https://api.honeycomb.io/v1/traces
+OTLP_HEADERS='{"x-honeycomb-team":"<HONEYCOMB_API_KEY>"}'
+```
+
+Spans carry `gen_ai.*` semantic convention fields (`gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`, `gen_ai.request.model`) — most LLM-observability backends recognize these automatically.
+
+## License
+
+Apache-2.0 — see [LICENSE](./LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,57 @@
+import { type SpanExporter } from '@opentelemetry/sdk-trace-base';
+import type { JournalReader, ModelPricing } from '@gnldev/durable';
+export interface ExportRunOptions {
+    /** A ready-made OTEL SpanExporter (InMemorySpanExporter for tests). If not given, falls back to the endpoint or the default. */
+    exporter?: SpanExporter;
+    /** OTLP-HTTP endpoint (e.g. 'http://localhost:4318/v1/traces'). If exporter is not given, one is built from this (lazily). */
+    endpoint?: string;
+    /** Price table for cost attributes (passed to getRunCost). */
+    pricing?: Record<string, ModelPricing>;
+    /** Default when the journal has no model id. */
+    modelId?: string;
+    /** service.name attribute. */
+    serviceName?: string;
+    /**
+     * Applied to every free-text attribute this exporter emits. Today that is exactly one value — a
+     * failed run's `outcome.error`, which reaches both the `gnl.error` attribute and the root span's
+     * status message. Everything else emitted here is a model id, a finish reason, a token count or a
+     * tool status; `mapEntry` never reads prompt, response or tool-result text.
+     *
+     * It exists because a processor chain does NOT cover this path. `piiRedactor` runs in
+     * `processInput`/`processOutput`/`processToolResult`, while the run's verdict is written from a
+     * different place entirely (`recordRunOutcome` in @gnldev/durable), which no processor sees.
+     * Measured with the redactor installed: a provider that echoes the offending input back in its
+     * refusal — `Invalid request: message contained disallowed content: "<address>"` — still put that
+     * address into the span raw, and from there into whatever collector `endpoint` names, which is
+     * commonly a third party's.
+     *
+     * Off by default rather than redacting unconditionally: the message is the main debugging value a
+     * trace carries, and this package cannot know whether the endpoint is the host's own collector.
+     * One line to turn on, sharing `piiRedactor`'s defaults:
+     *
+     *   import { piiTextRedactor } from '@gnldev/processors';
+     *   await exportRun(journal, runId, { endpoint, redact: piiTextRedactor() });
+     *
+     * A redactor that throws or returns a non-string DROPS the message rather than falling back to the
+     * raw text — the raw text is the exact value it was installed to keep out.
+     */
+    redact?: (text: string) => string;
+}
+export interface ExportRunResult {
+    traceId: string;
+    spans: number;
+    /** The exporter used (if InMemorySpanExporter, tests can call getFinishedSpans()). */
+    exporter: SpanExporter;
+}
+/**
+ * Exports a run from the journal as an OTEL trace: 1 root span `agent.run` + one child span per
+ * model/tool entry. trace_id/span_id are deterministic (hash of runId/seq) → exporting the same run
+ * twice yields the SAME trace (idempotent). Duration is derived from each entry's `ts` (created_at).
+ */
+export declare function exportRun(reader: JournalReader, runId: string, opts?: ExportRunOptions): Promise<ExportRunResult>;
+export { traceIdFor, spanIdFor, mapEntry } from './spans.js';
+export { toOtlpJson, exportRunToOtlp, otlpTraceId, otlpSpanId } from './otlp.js';
+export { toOtlpMetricsJson, nextEpoch } from './metrics.js';
+export type { ToOtlpMetricsOptions, MetricsEpoch, OtlpMetricsPayload, OtlpMetric } from './metrics.js';
+export type { OtlpPayload, OtlpSpan, OtlpKeyValue, OtlpAttributeValue, ToOtlpJsonOptions, ExportRunToOtlpOptions, ExportRunToOtlpResult, OtlpRetryOptions, } from './otlp.js';
+export { otlpPresets, langfuse, apiKeyOtlp, braintrust, honeycomb, datadogAgent, collector } from './presets.js';

package/dist/index.js

@@ -0,0 +1,126 @@
+// @gnldev/otel — converts the journal into a real OpenTelemetry trace and sends it to a SpanExporter (or an
+// OTLP endpoint). Deterministic ids → idempotent; post-hoc from the journal → complete even after a crash,
+// consistent across replays = exactly-once / crash-proof observability (frameworks that live-instrument cannot offer this).
+import { BasicTracerProvider, SimpleSpanProcessor, InMemorySpanExporter, } from '@opentelemetry/sdk-trace-base';
+import { trace, context, SpanKind, SpanStatusCode } from '@opentelemetry/api';
+import { getRunCost } from '@gnldev/durable';
+import { traceIdFor, spanIdFor, QueueIdGenerator, mapEntry } from './spans.js';
+async function otlpExporter(endpoint) {
+    const mod = '@opentelemetry/exporter-trace-otlp-http'; // string variable → doesn't break the optional peer build
+    const { OTLPTraceExporter } = (await import(mod));
+    return new OTLPTraceExporter({ url: endpoint });
+}
+/**
+ * Exports a run from the journal as an OTEL trace: 1 root span `agent.run` + one child span per
+ * model/tool entry. trace_id/span_id are deterministic (hash of runId/seq) → exporting the same run
+ * twice yields the SAME trace (idempotent). Duration is derived from each entry's `ts` (created_at).
+ */
+export async function exportRun(reader, runId, opts = {}) {
+    const entries = await reader.readRun(runId);
+    // The run's recorded outcome. Without it, a run that DIED — a 401 on the first call, a cost ceiling —
+    // produced no error-bearing entry and was therefore exported as OK with $0 of cost: the single most
+    // misleading signal this exporter could send. `get` is optional on a bare JournalReader, so this
+    // degrades to the old derivation rather than throwing.
+    const outcome = typeof reader.get === 'function'
+        ? await reader
+            .get(`${runId}:outcome`).catch(() => undefined)
+        : undefined;
+    const runFailed = outcome?.status === 'failed';
+    const runCanceled = outcome?.status === 'canceled';
+    // The one free-text value that leaves this exporter — see `redact` on the options for why the
+    // processor chain never touched it. Computed once so the status message and the attribute cannot
+    // disagree about what was masked.
+    const errorText = (() => {
+        const raw = outcome?.error;
+        if (!raw || !opts.redact)
+            return raw;
+        try {
+            const out = opts.redact(raw);
+            return typeof out === 'string' ? out : undefined;
+        }
+        catch {
+            return undefined; // fail CLOSED: a broken redactor must not resurrect the raw text
+        }
+    })();
+    const exporter = opts.exporter ?? (opts.endpoint ? await otlpExporter(opts.endpoint) : new InMemorySpanExporter());
+    // Deterministic id queues: root traceId + (for the root + each entry) spanId.
+    const traceId = traceIdFor(runId);
+    const spanIds = ['root', ...entries.map((_, i) => i)].map((s) => spanIdFor(runId, s));
+    const idGenerator = new QueueIdGenerator(runId, [traceId], spanIds);
+    // OpenTelemetry JS 2.x removed `provider.addSpanProcessor()`: a processor can no longer be
+    // attached after construction, it is declared with the provider. Passed via `spanProcessors`.
+    const provider = new BasicTracerProvider({ idGenerator, spanProcessors: [new SimpleSpanProcessor(exporter)] });
+    const tracer = provider.getTracer('@gnldev/otel');
+    const cost = await getRunCost(reader, runId, { pricing: opts.pricing, modelId: opts.modelId });
+    // Timing: span start = entry.ts, end = next entry.ts (last = end of run). Falls back to now if ts is missing.
+    const now = Date.now();
+    const firstTs = entries.find((e) => e.ts != null)?.ts ?? now;
+    const lastTs = [...entries].reverse().find((e) => e.ts != null)?.ts ?? firstTs;
+    const root = tracer.startSpan('agent.run', {
+        kind: SpanKind.INTERNAL,
+        startTime: firstTs,
+        attributes: {
+            'gnl.run_id': runId,
+            'gen_ai.usage.input_tokens': cost.inputTokens,
+            'gen_ai.usage.output_tokens': cost.outputTokens,
+            'gen_ai.usage.total_tokens': cost.totalTokens,
+            'gnl.cost_usd': cost.costUsd,
+            'gnl.model_calls': cost.modelCalls,
+            'gnl.tool_calls': cost.toolCalls,
+            ...(opts.serviceName ? { 'service.name': opts.serviceName } : {}),
+        },
+    });
+    const parentCtx = trace.setSpan(context.active(), root);
+    let anyError = false;
+    let anySuspended = false;
+    for (let i = 0; i < entries.length; i++) {
+        const e = entries[i];
+        const m = mapEntry(e);
+        const start = e.ts ?? firstTs;
+        const end = entries[i + 1]?.ts ?? lastTs;
+        const span = tracer.startSpan(m.name, { kind: e.kind === 'model' ? SpanKind.CLIENT : SpanKind.INTERNAL, startTime: start, attributes: m.attributes }, parentCtx);
+        if (m.isError) {
+            span.setStatus({ code: SpanStatusCode.ERROR });
+            anyError = true;
+        }
+        if (m.isSuspended)
+            anySuspended = true;
+        span.end(end > start ? end : start);
+    }
+    // A cancel is an OPERATOR ACTION, not a system fault, so it decides the run's ending outright — the
+    // outcome record is the authority on HOW a run ended, and an errored entry earlier in a run someone
+    // then chose to stop does not make the stopping a failure. The child span that errored keeps its own
+    // ERROR status, so nothing is hidden; it simply stops being the root's verdict.
+    const failed = !runCanceled && (anyError || runFailed);
+    const stillRunning = !failed && !runCanceled && outcome?.status === 'running';
+    // A run whose write-ahead has no terminal yet is UNSET, not OK: OTel's OK means "ended fine", and
+    // this run has not ended — exporting mid-flight (or after a crash) must not report a success.
+    // A canceled run is UNSET for the mirror-image reason: it ended, but not WELL enough for OK and not
+    // BADLY enough for ERROR. OTel's semantic conventions reserve ERROR for unexpected endings, and
+    // paging an on-call because an operator cancelled a run is exactly the false alarm that trains
+    // people to ignore the signal. `gnl.status` carries the fact for anyone filtering on it.
+    root.setStatus(failed
+        ? { code: SpanStatusCode.ERROR, ...(errorText ? { message: errorText } : {}) }
+        : stillRunning || runCanceled ? { code: SpanStatusCode.UNSET } : { code: SpanStatusCode.OK });
+    // Same precedence as deriveRunStatus in @gnldev/durable: canceled is terminal and wins over even
+    // suspended (a canceled run's pending approval can never be applied), then suspended is a live state.
+    root.setAttribute('gnl.status', runCanceled ? 'canceled' : anySuspended ? 'suspended' : failed ? 'failed' : stillRunning ? 'running' : 'completed');
+    if (runFailed && errorText)
+        root.setAttribute('gnl.error', errorText);
+    root.end(lastTs > firstTs ? lastTs : firstTs);
+    // Guarantee the export via forceFlush; DO NOT call shutdown (the caller owns the exporter; on InMemory,
+    // shutdown would reset the finished spans). SimpleSpanProcessor already exports synchronously on span.end.
+    await provider.forceFlush();
+    return { traceId, spans: entries.length + 1, exporter };
+}
+export { traceIdFor, spanIdFor, mapEntry } from './spans.js';
+// Zero-dependency OTLP/HTTP JSON exporter (no OTel SDK, fetch only). Added alongside
+// exportRun; does not change the existing API.
+export { toOtlpJson, exportRunToOtlp, otlpTraceId, otlpSpanId } from './otlp.js';
+// Counters → OTLP metrics. Also reachable as `@gnldev/otel/metrics`, which is the leaner route:
+// this entry point statically imports the OTel trace SDK, and the metrics path needs none of it.
+export { toOtlpMetricsJson, nextEpoch } from './metrics.js';
+// Named observability presets (Langfuse/Braintrust/Honeycomb/Datadog/Collector) + a generic
+// API-key-authenticated OTLP/HTTP preset for any other provider.
+export { otlpPresets, langfuse, apiKeyOtlp, braintrust, honeycomb, datadogAgent, collector } from './presets.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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","sourcesContent":["// @gnldev/otel — converts the journal into a real OpenTelemetry trace and sends it to a SpanExporter (or an\n// OTLP endpoint). Deterministic ids → idempotent; post-hoc from the journal → complete even after a crash,\n// consistent across replays = exactly-once / crash-proof observability (frameworks that live-instrument cannot offer this).\nimport {\n  BasicTracerProvider,\n  SimpleSpanProcessor,\n  InMemorySpanExporter,\n  type SpanExporter,\n} from '@opentelemetry/sdk-trace-base';\nimport { trace, context, SpanKind, SpanStatusCode } from '@opentelemetry/api';\nimport { getRunCost } from '@gnldev/durable';\nimport type { JournalReader, ModelPricing } from '@gnldev/durable';\nimport { traceIdFor, spanIdFor, QueueIdGenerator, mapEntry } from './spans.js';\n\nexport interface ExportRunOptions {\n  /** A ready-made OTEL SpanExporter (InMemorySpanExporter for tests). If not given, falls back to the endpoint or the default. */\n  exporter?: SpanExporter;\n  /** OTLP-HTTP endpoint (e.g. 'http://localhost:4318/v1/traces'). If exporter is not given, one is built from this (lazily). */\n  endpoint?: string;\n  /** Price table for cost attributes (passed to getRunCost). */\n  pricing?: Record<string, ModelPricing>;\n  /** Default when the journal has no model id. */\n  modelId?: string;\n  /** service.name attribute. */\n  serviceName?: string;\n  /**\n   * Applied to every free-text attribute this exporter emits. Today that is exactly one value — a\n   * failed run's `outcome.error`, which reaches both the `gnl.error` attribute and the root span's\n   * status message. Everything else emitted here is a model id, a finish reason, a token count or a\n   * tool status; `mapEntry` never reads prompt, response or tool-result text.\n   *\n   * It exists because a processor chain does NOT cover this path. `piiRedactor` runs in\n   * `processInput`/`processOutput`/`processToolResult`, while the run's verdict is written from a\n   * different place entirely (`recordRunOutcome` in @gnldev/durable), which no processor sees.\n   * Measured with the redactor installed: a provider that echoes the offending input back in its\n   * refusal — `Invalid request: message contained disallowed content: \"<address>\"` — still put that\n   * address into the span raw, and from there into whatever collector `endpoint` names, which is\n   * commonly a third party's.\n   *\n   * Off by default rather than redacting unconditionally: the message is the main debugging value a\n   * trace carries, and this package cannot know whether the endpoint is the host's own collector.\n   * One line to turn on, sharing `piiRedactor`'s defaults:\n   *\n   *   import { piiTextRedactor } from '@gnldev/processors';\n   *   await exportRun(journal, runId, { endpoint, redact: piiTextRedactor() });\n   *\n   * A redactor that throws or returns a non-string DROPS the message rather than falling back to the\n   * raw text — the raw text is the exact value it was installed to keep out.\n   */\n  redact?: (text: string) => string;\n}\n\nexport interface ExportRunResult {\n  traceId: string;\n  spans: number;\n  /** The exporter used (if InMemorySpanExporter, tests can call getFinishedSpans()). */\n  exporter: SpanExporter;\n}\n\nasync function otlpExporter(endpoint: string): Promise<SpanExporter> {\n  const mod = '@opentelemetry/exporter-trace-otlp-http'; // string variable → doesn't break the optional peer build\n  const { OTLPTraceExporter } = (await import(mod)) as any;\n  return new OTLPTraceExporter({ url: endpoint });\n}\n\n/**\n * Exports a run from the journal as an OTEL trace: 1 root span `agent.run` + one child span per\n * model/tool entry. trace_id/span_id are deterministic (hash of runId/seq) → exporting the same run\n * twice yields the SAME trace (idempotent). Duration is derived from each entry's `ts` (created_at).\n */\nexport async function exportRun(\n  reader: JournalReader,\n  runId: string,\n  opts: ExportRunOptions = {},\n): Promise<ExportRunResult> {\n  const entries = await reader.readRun(runId);\n  // The run's recorded outcome. Without it, a run that DIED — a 401 on the first call, a cost ceiling —\n  // produced no error-bearing entry and was therefore exported as OK with $0 of cost: the single most\n  // misleading signal this exporter could send. `get` is optional on a bare JournalReader, so this\n  // degrades to the old derivation rather than throwing.\n  const outcome = typeof (reader as { get?: unknown }).get === 'function'\n    ? await (reader as unknown as { get<T>(k: string): Promise<T | undefined> })\n        .get<{ status?: string; error?: string }>(`${runId}:outcome`).catch(() => undefined)\n    : undefined;\n  const runFailed = outcome?.status === 'failed';\n  const runCanceled = outcome?.status === 'canceled';\n  // The one free-text value that leaves this exporter — see `redact` on the options for why the\n  // processor chain never touched it. Computed once so the status message and the attribute cannot\n  // disagree about what was masked.\n  const errorText = ((): string | undefined => {\n    const raw = outcome?.error;\n    if (!raw || !opts.redact) return raw;\n    try {\n      const out = opts.redact(raw);\n      return typeof out === 'string' ? out : undefined;\n    } catch {\n      return undefined; // fail CLOSED: a broken redactor must not resurrect the raw text\n    }\n  })();\n  const exporter = opts.exporter ?? (opts.endpoint ? await otlpExporter(opts.endpoint) : new InMemorySpanExporter());\n\n  // Deterministic id queues: root traceId + (for the root + each entry) spanId.\n  const traceId = traceIdFor(runId);\n  const spanIds = ['root' as const, ...entries.map((_, i) => i)].map((s) => spanIdFor(runId, s));\n  const idGenerator = new QueueIdGenerator(runId, [traceId], spanIds);\n\n  // OpenTelemetry JS 2.x removed `provider.addSpanProcessor()`: a processor can no longer be\n  // attached after construction, it is declared with the provider. Passed via `spanProcessors`.\n  const provider = new BasicTracerProvider({ idGenerator, spanProcessors: [new SimpleSpanProcessor(exporter)] });\n  const tracer = provider.getTracer('@gnldev/otel');\n\n  const cost = await getRunCost(reader, runId, { pricing: opts.pricing, modelId: opts.modelId });\n\n  // Timing: span start = entry.ts, end = next entry.ts (last = end of run). Falls back to now if ts is missing.\n  const now = Date.now();\n  const firstTs = entries.find((e) => e.ts != null)?.ts ?? now;\n  const lastTs = [...entries].reverse().find((e) => e.ts != null)?.ts ?? firstTs;\n\n  const root = tracer.startSpan('agent.run', {\n    kind: SpanKind.INTERNAL,\n    startTime: firstTs,\n    attributes: {\n      'gnl.run_id': runId,\n      'gen_ai.usage.input_tokens': cost.inputTokens,\n      'gen_ai.usage.output_tokens': cost.outputTokens,\n      'gen_ai.usage.total_tokens': cost.totalTokens,\n      'gnl.cost_usd': cost.costUsd,\n      'gnl.model_calls': cost.modelCalls,\n      'gnl.tool_calls': cost.toolCalls,\n      ...(opts.serviceName ? { 'service.name': opts.serviceName } : {}),\n    },\n  });\n  const parentCtx = trace.setSpan(context.active(), root);\n\n  let anyError = false;\n  let anySuspended = false;\n  for (let i = 0; i < entries.length; i++) {\n    const e = entries[i]!;\n    const m = mapEntry(e);\n    const start = e.ts ?? firstTs;\n    const end = entries[i + 1]?.ts ?? lastTs;\n    const span = tracer.startSpan(\n      m.name,\n      { kind: e.kind === 'model' ? SpanKind.CLIENT : SpanKind.INTERNAL, startTime: start, attributes: m.attributes },\n      parentCtx,\n    );\n    if (m.isError) {\n      span.setStatus({ code: SpanStatusCode.ERROR });\n      anyError = true;\n    }\n    if (m.isSuspended) anySuspended = true;\n    span.end(end > start ? end : start);\n  }\n\n  // A cancel is an OPERATOR ACTION, not a system fault, so it decides the run's ending outright — the\n  // outcome record is the authority on HOW a run ended, and an errored entry earlier in a run someone\n  // then chose to stop does not make the stopping a failure. The child span that errored keeps its own\n  // ERROR status, so nothing is hidden; it simply stops being the root's verdict.\n  const failed = !runCanceled && (anyError || runFailed);\n  const stillRunning = !failed && !runCanceled && outcome?.status === 'running';\n  // A run whose write-ahead has no terminal yet is UNSET, not OK: OTel's OK means \"ended fine\", and\n  // this run has not ended — exporting mid-flight (or after a crash) must not report a success.\n  // A canceled run is UNSET for the mirror-image reason: it ended, but not WELL enough for OK and not\n  // BADLY enough for ERROR. OTel's semantic conventions reserve ERROR for unexpected endings, and\n  // paging an on-call because an operator cancelled a run is exactly the false alarm that trains\n  // people to ignore the signal. `gnl.status` carries the fact for anyone filtering on it.\n  root.setStatus(failed\n    ? { code: SpanStatusCode.ERROR, ...(errorText ? { message: errorText } : {}) }\n    : stillRunning || runCanceled ? { code: SpanStatusCode.UNSET } : { code: SpanStatusCode.OK });\n  // Same precedence as deriveRunStatus in @gnldev/durable: canceled is terminal and wins over even\n  // suspended (a canceled run's pending approval can never be applied), then suspended is a live state.\n  root.setAttribute('gnl.status', runCanceled ? 'canceled' : anySuspended ? 'suspended' : failed ? 'failed' : stillRunning ? 'running' : 'completed');\n  if (runFailed && errorText) root.setAttribute('gnl.error', errorText);\n  root.end(lastTs > firstTs ? lastTs : firstTs);\n\n  // Guarantee the export via forceFlush; DO NOT call shutdown (the caller owns the exporter; on InMemory,\n  // shutdown would reset the finished spans). SimpleSpanProcessor already exports synchronously on span.end.\n  await provider.forceFlush();\n\n  return { traceId, spans: entries.length + 1, exporter };\n}\n\nexport { traceIdFor, spanIdFor, mapEntry } from './spans.js';\n\n// Zero-dependency OTLP/HTTP JSON exporter (no OTel SDK, fetch only). Added alongside\n// exportRun; does not change the existing API.\nexport { toOtlpJson, exportRunToOtlp, otlpTraceId, otlpSpanId } from './otlp.js';\n// Counters → OTLP metrics. Also reachable as `@gnldev/otel/metrics`, which is the leaner route:\n// this entry point statically imports the OTel trace SDK, and the metrics path needs none of it.\nexport { toOtlpMetricsJson, nextEpoch } from './metrics.js';\nexport type { ToOtlpMetricsOptions, MetricsEpoch, OtlpMetricsPayload, OtlpMetric } from './metrics.js';\nexport type {\n  OtlpPayload,\n  OtlpSpan,\n  OtlpKeyValue,\n  OtlpAttributeValue,\n  ToOtlpJsonOptions,\n  ExportRunToOtlpOptions,\n  ExportRunToOtlpResult,\n  OtlpRetryOptions,\n} from './otlp.js';\n\n// Named observability presets (Langfuse/Braintrust/Honeycomb/Datadog/Collector) + a generic\n// API-key-authenticated OTLP/HTTP preset for any other provider.\nexport { otlpPresets, langfuse, apiKeyOtlp, braintrust, honeycomb, datadogAgent, collector } from './presets.js';\n"]}

package/dist/live.d.ts

@@ -0,0 +1,60 @@
+import { type SpanExporter } from '@opentelemetry/sdk-trace-base';
+import type { ModelPricing } from '@gnldev/durable';
+export interface LiveCost {
+    inputTokens: number;
+    outputTokens: number;
+    cachedTokens: number;
+    totalTokens: number;
+    modelCalls: number;
+    toolCalls: number;
+    costUsd: number;
+}
+export interface LiveObservabilityOptions {
+    /** A ready-made OTEL SpanExporter (InMemorySpanExporter for tests). If not given, falls back to the endpoint or InMemory. */
+    exporter?: SpanExporter;
+    /** OTLP-HTTP endpoint (e.g. 'http://localhost:4318/v1/traces'). If exporter is not given, one is built from this (lazily). */
+    endpoint?: string;
+    /** Price table for cost calculation (default DEFAULT_PRICING). */
+    pricing?: Record<string, ModelPricing>;
+    /** service.name span attribute. */
+    serviceName?: string;
+    /** Sampling rate 0..1 (default 1 = all). instrument() kicks in with this probability. */
+    sampleRate?: number;
+    /** Called with the current running total cost after every model call (live budget alarm). */
+    onCost?: (cost: LiveCost) => void;
+    /**
+     * FINDING (roots leak guard): the `roots` Map holds one root span per new runId; normally this is
+     * cleared by `flush(runId)` (or plain `flush()` if never closed). If the caller forgets to do this
+     * (e.g. a long-lived multi-run server), the Map grows unbounded. This is the last-resort guardrail
+     * for that case: once the Map exceeds this size, the OLDEST (insertion-order) root is forcibly ended
+     * and removed. If not given, the guardrail is OFF (default behavior unchanged) — only opted-in callers
+     * get it. Kept simple: no TTL, just a size limit.
+     */
+    maxPendingRuns?: number;
+}
+export interface LiveInstrumentArgs {
+    runId: string;
+    model: unknown;
+    tools?: Record<string, any>;
+    [k: string]: unknown;
+}
+export interface LiveObservability {
+    /** Wraps runDurable/streamDurable args to inject live tracing (model + tool). Returns the same type. */
+    instrument<T extends LiveInstrumentArgs>(args: T): T;
+    /** Total cost/tokens accumulated so far (live). */
+    cost(): LiveCost;
+    /**
+     * If `runId` is given, closes ONLY that run's root span + removes it from the `roots` Map (does not
+     * touch other concurrent runs) — this is the cleanup point that must be called as each run finishes
+     * in a multi-run scenario. If `runId` is omitted (old behavior, UNCHANGED), closes ALL open root spans
+     * + clears the Map entirely. In both cases forces a flush to the exporter.
+     */
+    flush(runId?: string): Promise<void>;
+    /** Shut down the provider (exporter shutdown). */
+    shutdown(): Promise<void>;
+    /** The exporter used (if InMemorySpanExporter, tests can call getFinishedSpans()). */
+    exporter: SpanExporter;
+    /** Number of runs currently held in the `roots` Map (not yet closed via `flush(runId)`) — for leak monitoring. */
+    pendingRuns(): number;
+}
+export declare function liveObservability(opts?: LiveObservabilityOptions): LiveObservability;