@use-crux/otel

import { withTelemetry } from '@use-crux/otel'
import { createUrlExporter, createCallbackExporter } from '@use-crux/otel'

withTelemetry(options?)

Creates a CruxPlugin that instruments all Crux operations with OpenTelemetry spans or lightweight structured traces.

config({
  plugins: [withTelemetry({ serviceName: 'my-app' })],
})

Options:

Payload capture is controlled by the core observability policy: config({ observability: { recordInputs, recordOutputs, redactRecord } }). recordInputs and recordOutputs accept inline, reference, or off. The OTel mapper also drops known payload attribute keys by default, even when local graph capture is inline.

Returns: CruxPlugin with name 'crux:otel'.

withTelemetry() has a process-level double-install guard. A second active install warns once and becomes a no-op, preventing duplicate exported span trees.

If the standard OTel path is used without a registered TracerProvider, Crux detects the invalid OTel span context, warns once, and falls back to lightweight span tracking. Register a provider before installing the plugin or pass exporter.

Open span registries are bounded. Registry-pressure evictions force-end spans with crux.expired: true and UNSET status.

Crux emits embedding spans as embeddings {model} with attributes for embedding name, kind, input count, chunk count, dense dimensions, token usage, and cost when available.

Generation and stream spans project Crux graph metrics into OTel GenAI and Crux attributes: gen_ai.client.operation.duration, gen_ai.server.time_to_first_token, crux.gen.output_tokens_per_second, and crux.gen.time_per_output_chunk_ms.

Corpus sync emits crux.corpus.sync spans and per-source crux.corpus.source spans. Namespace and source identifiers are exported as hashes so file paths, URLs, and tenant namespaces do not become raw telemetry attributes.

Ingest parsers emit crux.ingest.parse spans. These include parser name, source format, byte length, part count, warning count, and hashed namespace/source identifiers. Parser errors mark the span as ERROR.

Retrieval emits direct crux.retrieval.query spans for retriever calls. Retrieval recipes emit a parent crux.retrieval.recipe span and one crux.retrieval.step span per recipe step. Step spans include recipe id, step id, step kind, input/output query counts, input/output hit counts, warning count, and status. They intentionally do not include raw query text, hit content, metadata, filters, or embeddings.

Quality evaluations export crux.eval.run and crux.eval.case spans. Baseline comparison, case membership, and replay provenance are canonical graph edges for local/devtools read models; OTel export keeps those relationships as aggregate span metadata rather than raw case payloads.

UrlExporter

Configuration for HTTP POST export (ephemeral runtimes).

CallbackExporter

type CallbackExporter = (
  spans: ReadonlyArray<TraceSpan>,
) => void | Promise<void>

A function that receives completed span batches. Use for custom handling (Convex actions, PostHog, etc.).

TraceSpan

Structured span data used by the lightweight exporter path.

Propagation helpers

See the telemetry guide for suspend/resume and queue examples.

createUrlExporter(options)

Creates a SpanExporter that POSTs span batches to a URL. Fire-and-forget with 5-second timeout, failures are silently ignored.

const exporter = createUrlExporter({
  url: 'https://collector.example.com/v1/traces',
  headers: { 'X-Api-Key': 'key' },
})

createCallbackExporter(callback)

Creates a SpanExporter that delivers span batches to a callback function.

const exporter = createCallbackExporter((spans) => {
  for (const span of spans) {
    console.log(`${span.name}: ${span.durationMs}ms`)
  }
})

SpanExporter

Interface for span export backends.

Span attribute constants

GenAI semantic convention constants are exported from @use-crux/otel:

Related

• Guide: Telemetry
• Guide: Observability
• Cookbook: Observability stack