Skip to main content

Observability

@opentelemetry/api 1.10+ is a peer dependency. The OpenTelemetry 3 SDK used for development and tests requires Node.js 22.15+. Applications register their own tracer and meter providers; without a provider, the instrumentation is a no-op.

Subject operations emit xstate.nats.subscribe, xstate.nats.message, xstate.nats.publish, and xstate.nats.request spans. NATS reconnect events emit xstate.nats.reconnect; KV watches emit xstate.nats.kv.watch and xstate.nats.kv.entry. Publish/request operations inject trace context into NATS headers; received messages extract it so traces can cross application boundaries.

Lifecycle diagnostics

config: {
  opts: { servers: ['wss://your-nats.example'] },
  maxRetries: 3,
  diagnostics: { lifecycle: true },
}

When enabled, root transitions emit sanitized xstate.nats.lifecycle spans and console breadcrumbs with state, event type, server URLs, retry count, auth type, and manager readiness. Raw protocol debugging is separate from lifecycle diagnostics.

Credential instrumentation

Credential load/refresh spans are xstate.nats.credentials.load and .refresh. Metrics are:

Metric Kind
xstate.nats.credentials.operations Counter by operation/outcome
xstate.nats.credentials.operation.duration Duration histogram in milliseconds
xstate.nats.credentials.state.transitions Counter by state

Set credentials.diagnostics: true for sanitized credential state/operation breadcrumbs. Credential contents and provider error messages are excluded from credential instrumentation. The browser demo’s State panel likewise summarizes state and counters without dumping auth configuration.