@jr200-labs/xstate-nats 0.6.0 → 0.7.0

package/README.md

@@ -218,6 +218,60 @@ auth: {
 - `KV.UNSUBSCRIBE`: Unsubscribe from KV changes
 - `KV.UNSUBSCRIBE_ALL`: Unsubscribe from all KV changes
 
+## OpenTelemetry
+
+This library emits OpenTelemetry spans for NATS operations and propagates W3C
+trace context across the wire so a single trace can span publisher, subscriber,
+and request/reply replier.
+
+### Emitted spans
+
+| Span name               | Emitted by           | Attributes                               |
+| ----------------------- | -------------------- | ---------------------------------------- |
+| `xstate.nats.subscribe` | `SUBJECT.SUBSCRIBE`  | `subject`                                |
+| `xstate.nats.message`   | per received message | `subject`, `payload.bytes`               |
+| `xstate.nats.publish`   | `SUBJECT.PUBLISH`    | `subject`, `payload.bytes`               |
+| `xstate.nats.request`   | `SUBJECT.REQUEST`    | `subject`, `payload.bytes`, `timeout.ms` |
+| `xstate.nats.reconnect` | NATS status loop     | `reconnect.type`                         |
+| `xstate.nats.kv.watch`  | `KV.SUBSCRIBE`       | `bucket`, `key`                          |
+| `xstate.nats.kv.entry`  | per KV watch entry   | `bucket`, `key`, `operation`             |
+
+All error paths record exceptions on the active span, set span status to
+`ERROR`, and emit a named event (`xstate.nats.error` / `xstate.nats.kv.error`)
+with a truncated stack.
+
+### Enabling tracing
+
+`@opentelemetry/api` is a peer dependency — the consumer controls the installed
+version and registers the SDK. If no provider is registered all telemetry calls
+become no-ops. Minimal setup:
+
+```ts
+import { trace, propagation, context } from '@opentelemetry/api'
+import { AsyncLocalStorageContextManager } from '@opentelemetry/context-async-hooks'
+import { W3CTraceContextPropagator } from '@opentelemetry/core'
+import { BasicTracerProvider, SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base'
+
+const provider = new BasicTracerProvider({
+  spanProcessors: [
+    /* your exporter */
+  ],
+})
+trace.setGlobalTracerProvider(provider)
+propagation.setGlobalPropagator(new W3CTraceContextPropagator())
+
+const ctxMgr = new AsyncLocalStorageContextManager()
+ctxMgr.enable()
+context.setGlobalContextManager(ctxMgr)
+```
+
+### Context propagation
+
+Publish and request operations inject `traceparent` into the outgoing NATS
+headers; received messages extract the traceparent and parent their
+`xstate.nats.message` span on it. Downstream services that propagate the header
+appear as children of the originating publisher/requester span.
+
 ## Examples
 
 Check out the [React example](./examples/react-test/) for a complete working implementation.

package/dist/actions/connection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../src/actions/connection.ts"],"names":[],"mappings":"AACA,OAAO,EACL,iBAAiB,EAEjB,GAAG,EACH,cAAc,EACd,MAAM,EAEP,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AACrC,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,SAAS,CAAA;AA6BzC,MAAM,MAAM,oBAAoB,GAC5B;IAAE,IAAI,EAAE,8BAA8B,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACxD;IAAE,IAAI,EAAE,2BAA2B,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACrD;IAAE,IAAI,EAAE,uBAAuB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,uBAAuB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,8BAA8B,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAE5D,eAAO,MAAM,aAAa;UAIP,iBAAiB;WAAS,UAAU;gCAwDtD,CAAA;AAED,eAAO,MAAM,cAAc;gBACgB,cAAc,GAAG,IAAI;gCAM/D,CAAA;AAED,eAAO,MAAM,eAAe,GAAI,KAAK,GAAG,GAAG,OAAO,GAAG,IAAI,GAAG,KAAK,YAiBhE,CAAA"}
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../src/actions/connection.ts"],"names":[],"mappings":"AACA,OAAO,EACL,iBAAiB,EAEjB,GAAG,EACH,cAAc,EACd,MAAM,EAEP,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AACrC,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,SAAS,CAAA;AA8BzC,MAAM,MAAM,oBAAoB,GAC5B;IAAE,IAAI,EAAE,8BAA8B,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACxD;IAAE,IAAI,EAAE,2BAA2B,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACrD;IAAE,IAAI,EAAE,uBAAuB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,uBAAuB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,8BAA8B,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAE5D,eAAO,MAAM,aAAa;UAIP,iBAAiB;WAAS,UAAU;gCA+EtD,CAAA;AAED,eAAO,MAAM,cAAc;gBACgB,cAAc,GAAG,IAAI;gCAM/D,CAAA;AAED,eAAO,MAAM,eAAe,GAAI,KAAK,GAAG,GAAG,OAAO,GAAG,IAAI,GAAG,KAAK,YAiBhE,CAAA"}

package/dist/actions/connection.js

@@ -1,6 +1,7 @@
 import { fromPromise } from 'xstate';
 import { credsAuthenticator, wsconnect, } from '@nats-io/nats-core';
 import { sendParent } from 'xstate';
+import { withSpan } from '../telemetry';
 const makeAuthConfig = (auth) => {
     if (!auth) {
         return {};
@@ -41,7 +42,11 @@ export const connectToNats = fromPromise(async ({ input, }) => {
                     sendParent({ type: 'NATS_CONNECTION.DISCONNECTED', status });
                     break;
                 case 'reconnect':
-                    sendParent({ type: 'NATS_CONNECTION.RECONNECT', status });
+                    // Per-event span so reconnect attempts become discoverable in
+                    // the trace backend (searchable, durations, span counts).
+                    withSpan('xstate.nats.reconnect', 'xstate.nats.error', { 'reconnect.type': type }, () => {
+                        sendParent({ type: 'NATS_CONNECTION.RECONNECT', status });
+                    });
                     break;
                 case 'error':
                     sendParent({ type: 'NATS_CONNECTION.ERROR', status });
@@ -56,10 +61,14 @@ export const connectToNats = fromPromise(async ({ input, }) => {
                     // console.debug('Received ping, pong sent automatically')
                     break;
                 case 'forceReconnect':
-                    sendParent({ type: 'NATS_CONNECTION.RECONNECT', status });
+                    withSpan('xstate.nats.reconnect', 'xstate.nats.error', { 'reconnect.type': type }, () => {
+                        sendParent({ type: 'NATS_CONNECTION.RECONNECT', status });
+                    });
                     break;
                 case 'reconnecting':
-                    sendParent({ type: 'NATS_CONNECTION.RECONNECTING', status });
+                    withSpan('xstate.nats.reconnect', 'xstate.nats.error', { 'reconnect.type': type }, () => {
+                        sendParent({ type: 'NATS_CONNECTION.RECONNECTING', status });
+                    });
                     break;
                 case 'slowConsumer':
                     console.debug('SLOW_CONSUMER', status);

package/dist/actions/connection.js.map

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

package/dist/actions/kv.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kv.d.ts","sourceRoot":"","sources":["../../src/actions/kv.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACnE,OAAO,EAAE,GAAG,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAC/D,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAA;AAG/B,qBAAa,iBAAkB,SAAQ,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC;CAAG;AAE9D,MAAM,MAAM,oBAAoB,GAAG;IACjC,MAAM,EAAE,MAAM,CAAA;IACd,GAAG,EAAE,MAAM,CAAA;IACX,QAAQ,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,IAAI,CAAA;IAC7B,IAAI,CAAC,EAAE,cAAc,CAAA;IACrB,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAC5B,CAAA;AAED,eAAO,MAAM,kBAAkB;mBAWZ,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,YAAY,CAAC,CAAC;;SANjD,GAAG,GAAG,IAAI;gBACH,cAAc,GAAG,IAAI;kBACnB,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,YAAY,CAAC,CAAC;iBAC1C,GAAG,CAAC,MAAM,EAAE,oBAAoB,CAAC;gCAoEnD,CAAA"}
+{"version":3,"file":"kv.d.ts","sourceRoot":"","sources":["../../src/actions/kv.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACnE,OAAO,EAAE,GAAG,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAC/D,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAA;AAI/B,qBAAa,iBAAkB,SAAQ,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC;CAAG;AAE9D,MAAM,MAAM,oBAAoB,GAAG;IACjC,MAAM,EAAE,MAAM,CAAA;IACd,GAAG,EAAE,MAAM,CAAA;IACX,QAAQ,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,IAAI,CAAA;IAC7B,IAAI,CAAC,EAAE,cAAc,CAAA;IACrB,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAC5B,CAAA;AAED,eAAO,MAAM,kBAAkB;mBAWZ,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,YAAY,CAAC,CAAC;;SANjD,GAAG,GAAG,IAAI;gBACH,cAAc,GAAG,IAAI;kBACnB,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,YAAY,CAAC,CAAC;iBAC1C,GAAG,CAAC,MAAM,EAAE,oBAAoB,CAAC;gCA+FnD,CAAA"}

package/dist/actions/kv.js

@@ -1,5 +1,6 @@
 import { Pair } from '../utils';
 import { fromPromise } from 'xstate';
+import { recordError, withSpan } from '../telemetry';
 export class KvSubscriptionKey extends Pair {
 }
 export const kvConsolidateState = fromPromise(async ({ input, }) => {
@@ -28,23 +29,38 @@ export const kvConsolidateState = fromPromise(async ({ input, }) => {
             try {
                 const kv = await input.kvm.open(config.bucket);
                 const watchOptions = config;
-                const watcher = await kv.watch(watchOptions);
+                // Short span around the synchronous-ish watch() setup — the watcher
+                // iterator itself is long-lived, so each received entry gets its
+                // own span below rather than one indefinite parent.
+                const watcher = (await withSpan('xstate.nats.kv.watch', 'xstate.nats.kv.error', { bucket: config.bucket, key: config.key }, () => kv.watch(watchOptions)));
                 syncedState.set(kvKey, watcher);
                 (async () => {
                     try {
                         for await (const e of watcher) {
                             if (e.operation !== 'DEL') {
-                                let parsedValue;
-                                try {
-                                    parsedValue = JSON.parse(e.string());
-                                }
-                                catch {
-                                    parsedValue = e.string();
-                                }
-                                config.callback({
+                                await withSpan('xstate.nats.kv.entry', 'xstate.nats.kv.error', {
                                     bucket: config.bucket,
                                     key: config.key,
-                                    value: parsedValue,
+                                    operation: e.operation,
+                                }, (span) => {
+                                    let parsedValue;
+                                    try {
+                                        parsedValue = JSON.parse(e.string());
+                                    }
+                                    catch {
+                                        parsedValue = e.string();
+                                    }
+                                    try {
+                                        config.callback({
+                                            bucket: config.bucket,
+                                            key: config.key,
+                                            value: parsedValue,
+                                        });
+                                    }
+                                    catch (callbackError) {
+                                        recordError(span, 'xstate.nats.kv.error', callbackError);
+                                        console.error(`KV_SUBSCRIBE (connected): Callback error for ${kvKey}:`, callbackError);
+                                    }
                                 });
                             }
                         }

package/dist/actions/kv.js.map

@@ -1 +1 @@
-{"version":3,"file":"kv.js","sourceRoot":"","sources":["../../src/actions/kv.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAA;AAC/B,OAAO,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAA;AAEpC,MAAM,OAAO,iBAAkB,SAAQ,IAAoB;CAAG;AAU9D,MAAM,CAAC,MAAM,kBAAkB,GAAG,WAAW,CAC3C,KAAK,EAAE,EACL,KAAK,GAQN,EAEE,EAAE;IACH,IAAI,CAAC,KAAK,CAAC,UAAU,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAA;IAC5D,CAAC;IAED,MAAM,EAAE,YAAY,EAAE,WAAW,EAAE,GAAG,KAAK,CAAA;IAC3C,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,YAAY,CAAC,CAAA;IAEzC,yEAAyE;IACzE,KAAK,MAAM,CAAC,KAAK,EAAE,YAAY,CAAC,IAAI,YAAY,EAAE,CAAC;QACjD,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAC5B,IAAI,CAAC;gBACH,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;gBACzB,YAAY,CAAC,IAAI,EAAE,CAAA;YACrB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO,CAAC,KAAK,CAAC,qCAAqC,KAAK,GAAG,EAAE,KAAK,CAAC,CAAA;YACrE,CAAC;QACH,CAAC;IACH,CAAC;IAED,4EAA4E;IAC5E,KAAK,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,WAAW,EAAE,CAAC;QAC1C,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAC7B,6EAA6E;YAC7E,4BAA4B;YAC5B,IAAI,CAAC;gBACH,MAAM,EAAE,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;gBAE9C,MAAM,YAAY,GAAG,MAAwB,CAAA;gBAC7C,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC,CAAA;gBAE5C,WAAW,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAC9B;gBAAA,CAAC,KAAK,IAAI,EAAE;oBACX,IAAI,CAAC;wBACH,IAAI,KAAK,EAAE,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;4BAC9B,IAAI,CAAC,CAAC,SAAS,KAAK,KAAK,EAAE,CAAC;gCAC1B,IAAI,WAAW,CAAA;gCACf,IAAI,CAAC;oCACH,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAA;gCACtC,CAAC;gCAAC,MAAM,CAAC;oCACP,WAAW,GAAG,CAAC,CAAC,MAAM,EAAE,CAAA;gCAC1B,CAAC;gCAED,MAAM,CAAC,QAAQ,CAAC;oCACd,MAAM,EAAE,MAAM,CAAC,MAAM;oCACrB,GAAG,EAAE,MAAM,CAAC,GAAG;oCACf,KAAK,EAAE,WAAW;iCACnB,CAAC,CAAA;4BACJ,CAAC;wBACH,CAAC;oBACH,CAAC;oBAAC,OAAO,KAAK,EAAE,CAAC;wBACf,OAAO,CAAC,KAAK,CAAC,oDAAoD,KAAK,GAAG,EAAE,KAAK,CAAC,CAAA;oBACpF,CAAC;gBACH,CAAC,CAAC,EAAE,CAAA;YACN,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO,CAAC,KAAK,CAAC,iCAAiC,KAAK,GAAG,EAAE,KAAK,CAAC,CAAA;YACjE,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO;QACL,aAAa,EAAE,WAAW;KAC3B,CAAA;AACH,CAAC,CACF,CAAA"}
+{"version":3,"file":"kv.js","sourceRoot":"","sources":["../../src/actions/kv.ts"],"names":[],"mappings":"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"}

package/dist/actions/subject.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"subject.d.ts","sourceRoot":"","sources":["../../src/actions/subject.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,cAAc,EACd,cAAc,EACd,cAAc,EACd,YAAY,EACZ,mBAAmB,EACpB,MAAM,oBAAoB,CAAA;AAG3B,MAAM,MAAM,yBAAyB,GAAG;IACtC,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,IAAI,CAAA;IAC7B,IAAI,CAAC,EAAE,mBAAmB,CAAA;CAC3B,CAAA;AAED,eAAO,MAAM,uBAAuB,GAAI,YAErC;IACD,KAAK,EAAE;QACL,UAAU,EAAE,cAAc,GAAG,IAAI,CAAA;QACjC,oBAAoB,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;QAC/C,mBAAmB,EAAE,GAAG,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAA;KAC5D,CAAA;CACF;;CAmDA,CAAA;AAED,eAAO,MAAM,cAAc,GAAI,YAE5B;IACD,KAAK,EAAE;QACL,UAAU,EAAE,cAAc,GAAG,IAAI,CAAA;QACjC,OAAO,EAAE,MAAM,CAAA;QACf,OAAO,EAAE,GAAG,CAAA;QACZ,IAAI,CAAC,EAAE,cAAc,CAAA;QACrB,QAAQ,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,IAAI,CAAA;KAC9B,CAAA;CACF,SAcA,CAAA;AAED,eAAO,MAAM,cAAc,GAAI,YAE5B;IACD,KAAK,EAAE;QACL,UAAU,EAAE,cAAc,GAAG,IAAI,CAAA;QACjC,OAAO,EAAE,MAAM,CAAA;QACf,OAAO,EAAE,GAAG,CAAA;QACZ,OAAO,CAAC,EAAE,cAAc,CAAA;QACxB,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE;YAAE,EAAE,EAAE,IAAI,CAAA;SAAE,GAAG;YAAE,EAAE,EAAE,KAAK,CAAC;YAAC,KAAK,EAAE,KAAK,CAAA;SAAE,KAAK,IAAI,CAAA;KAC/E,CAAA;CACF,SAaA,CAAA"}
+{"version":3,"file":"subject.d.ts","sourceRoot":"","sources":["../../src/actions/subject.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,cAAc,EACd,cAAc,EACd,cAAc,EACd,YAAY,EACZ,mBAAmB,EACpB,MAAM,oBAAoB,CAAA;AAS3B,MAAM,MAAM,yBAAyB,GAAG;IACtC,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,IAAI,CAAA;IAC7B,IAAI,CAAC,EAAE,mBAAmB,CAAA;CAC3B,CAAA;AAED,eAAO,MAAM,uBAAuB,GAAI,YAErC;IACD,KAAK,EAAE;QACL,UAAU,EAAE,cAAc,GAAG,IAAI,CAAA;QACjC,oBAAoB,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;QAC/C,mBAAmB,EAAE,GAAG,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAA;KAC5D,CAAA;CACF;;CA2EA,CAAA;AAED,eAAO,MAAM,cAAc,GAAI,YAE5B;IACD,KAAK,EAAE;QACL,UAAU,EAAE,cAAc,GAAG,IAAI,CAAA;QACjC,OAAO,EAAE,MAAM,CAAA;QACf,OAAO,EAAE,GAAG,CAAA;QACZ,IAAI,CAAC,EAAE,cAAc,CAAA;QACrB,QAAQ,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,IAAI,CAAA;KAC9B,CAAA;CACF,SA4CA,CAAA;AAED,eAAO,MAAM,cAAc,GAAI,YAE5B;IACD,KAAK,EAAE;QACL,UAAU,EAAE,cAAc,GAAG,IAAI,CAAA;QACjC,OAAO,EAAE,MAAM,CAAA;QACf,OAAO,EAAE,GAAG,CAAA;QACZ,OAAO,CAAC,EAAE,cAAc,CAAA;QACxB,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE;YAAE,EAAE,EAAE,IAAI,CAAA;SAAE,GAAG;YAAE,EAAE,EAAE,KAAK,CAAC;YAAC,KAAK,EAAE,KAAK,CAAA;SAAE,KAAK,IAAI,CAAA;KAC/E,CAAA;CACF,SA+BA,CAAA"}

package/dist/actions/subject.js

@@ -1,4 +1,5 @@
 import { parseNatsResult } from './connection';
+import { extractContextFromHeaders, injectContextIntoHeaders, recordError, withSpan, } from '../telemetry';
 export const subjectConsolidateState = ({ input, }) => {
     const { connection, currentSubscriptions, targetSubscriptions } = input;
     if (!connection) {
@@ -21,16 +22,28 @@ export const subjectConsolidateState = ({ input, }) => {
     for (const [subject, subscriptionConfig] of targetSubscriptions) {
         if (!currentSubscriptions.has(subject)) {
             try {
-                const sub = connection.subscribe(subject, subscriptionConfig.opts);
+                // Short span around the synchronous subscribe() call. The iterator
+                // below is long-lived; we don't span its whole lifetime (indefinite
+                // spans are anti-pattern in most tracing backends).
+                const sub = withSpan('xstate.nats.subscribe', 'xstate.nats.error', { subject }, () => connection.subscribe(subject, subscriptionConfig.opts));
                 (async () => {
                     try {
                         for await (const msg of sub) {
-                            try {
-                                subscriptionConfig?.callback(parseNatsResult(msg));
-                            }
-                            catch (callbackError) {
-                                console.error(`Callback error for subject "${subject}"`, callbackError);
-                            }
+                            const parentCtx = extractContextFromHeaders(msg.headers);
+                            await withSpan('xstate.nats.message', 'xstate.nats.error', {
+                                subject,
+                                'payload.bytes': msg.data?.length,
+                            }, (span) => {
+                                try {
+                                    subscriptionConfig?.callback(parseNatsResult(msg));
+                                }
+                                catch (callbackError) {
+                                    // Record on span AND preserve the existing console.error
+                                    // so consumers without OTel still see the failure.
+                                    recordError(span, 'xstate.nats.error', callbackError);
+                                    console.error(`Callback error for subject "${subject}"`, callbackError);
+                                }
+                            }, parentCtx);
                         }
                     }
                     catch (iteratorError) {
@@ -53,13 +66,35 @@ export const subjectRequest = ({ input, }) => {
     if (!connection) {
         throw new Error('NATS connection is not available');
     }
-    connection
-        .request(subject, payload, opts)
-        .then((msg) => {
-        callback(parseNatsResult(msg));
-    })
-        .catch((err) => {
-        console.error(`RequestReply error for subject "${subject}"`, err);
+    const payloadBytes = payload instanceof Uint8Array
+        ? payload.byteLength
+        : typeof payload === 'string'
+            ? payload.length
+            : undefined;
+    void withSpan('xstate.nats.request', 'xstate.nats.error', {
+        subject,
+        'payload.bytes': payloadBytes,
+        'timeout.ms': opts?.timeout,
+    }, (span) => {
+        // Inject INSIDE the span so the replying service parents its handler
+        // span on this request span (not on an ambient context). RequestOptions
+        // declares `timeout` as required but nats-core only enforces it when
+        // opts is provided; cast preserves the "no opts = use conn default"
+        // contract.
+        const headers = injectContextIntoHeaders(opts?.headers);
+        const requestOpts = (opts ? { ...opts, headers } : { headers });
+        return connection
+            .request(subject, payload, requestOpts)
+            .then((msg) => {
+            callback(parseNatsResult(msg));
+        })
+            .catch((err) => {
+            // Record on span manually so we can swallow the rejection here —
+            // the original fire-and-forget API didn't propagate request errors
+            // to callers and changing that now would be a breaking behaviour.
+            recordError(span, 'xstate.nats.error', err);
+            console.error(`RequestReply error for subject "${subject}"`, err);
+        });
     });
 };
 export const subjectPublish = ({ input, }) => {
@@ -67,8 +102,19 @@ export const subjectPublish = ({ input, }) => {
     if (!connection) {
         throw new Error('NATS connection is not available');
     }
+    const payloadBytes = payload instanceof Uint8Array
+        ? payload.byteLength
+        : typeof payload === 'string'
+            ? payload.length
+            : undefined;
     try {
-        connection.publish(subject, payload, options);
+        withSpan('xstate.nats.publish', 'xstate.nats.error', { subject, 'payload.bytes': payloadBytes }, () => {
+            // Inject INSIDE the span so downstream subscribers see THIS span as
+            // parent instead of whatever was ambient before publish.
+            const headers = injectContextIntoHeaders(options?.headers);
+            const publishOpts = { ...(options ?? {}), headers };
+            connection.publish(subject, payload, publishOpts);
+        });
         onPublishResult?.({ ok: true });
     }
     catch (callbackError) {

package/dist/actions/subject.js.map

@@ -1 +1 @@
-{"version":3,"file":"subject.js","sourceRoot":"","sources":["../../src/actions/subject.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAQ9C,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,EACtC,KAAK,GAON,EAAE,EAAE;IACH,MAAM,EAAE,UAAU,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,GAAG,KAAK,CAAA;IACvE,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAA;IACrD,CAAC;IAED,MAAM,mBAAmB,GAAG,IAAI,GAAG,CAAC,oBAAoB,CAAC,CAAA;IAEzD,4FAA4F;IAC5F,KAAK,MAAM,CAAC,OAAO,EAAE,YAAY,CAAC,IAAI,oBAAoB,EAAE,CAAC;QAC3D,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YACtC,IAAI,CAAC;gBACH,mBAAmB,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;gBACnC,YAAY,CAAC,WAAW,EAAE,CAAA;YAC5B,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO,CAAC,KAAK,CAAC,qCAAqC,OAAO,GAAG,EAAE,KAAK,CAAC,CAAA;YACvE,CAAC;QACH,CAAC;IACH,CAAC;IAED,4FAA4F;IAC5F,KAAK,MAAM,CAAC,OAAO,EAAE,kBAAkB,CAAC,IAAI,mBAAmB,EAAE,CAAC;QAChE,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YACvC,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,UAAU,CAAC,SAAS,CAAC,OAAO,EAAE,kBAAkB,CAAC,IAAI,CAAC,CAGjE;gBAAA,CAAC,KAAK,IAAI,EAAE;oBACX,IAAI,CAAC;wBACH,IAAI,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,EAAE,CAAC;4BAC5B,IAAI,CAAC;gCACH,kBAAkB,EAAE,QAAQ,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,CAAA;4BACpD,CAAC;4BAAC,OAAO,aAAa,EAAE,CAAC;gCACvB,OAAO,CAAC,KAAK,CAAC,+BAA+B,OAAO,GAAG,EAAE,aAAa,CAAC,CAAA;4BACzE,CAAC;wBACH,CAAC;oBACH,CAAC;oBAAC,OAAO,aAAa,EAAE,CAAC;wBACvB,OAAO,CAAC,KAAK,CAAC,+BAA+B,OAAO,GAAG,EAAE,aAAa,CAAC,CAAA;oBACzE,CAAC;gBACH,CAAC,CAAC,EAAE,CAAA;gBAEJ,mBAAmB,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,CAAA;YACvC,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO,CAAC,KAAK,CAAC,iCAAiC,OAAO,GAAG,EAAE,KAAK,CAAC,CAAA;YACnE,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO;QACL,aAAa,EAAE,mBAAmB;KACnC,CAAA;AACH,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,EAC7B,KAAK,GASN,EAAE,EAAE;IACH,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,KAAK,CAAA;IAC9D,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAA;IACrD,CAAC;IAED,UAAU;SACP,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC;SAC/B,IAAI,CAAC,CAAC,GAAQ,EAAE,EAAE;QACjB,QAAQ,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,CAAA;IAChC,CAAC,CAAC;SACD,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;QACb,OAAO,CAAC,KAAK,CAAC,mCAAmC,OAAO,GAAG,EAAE,GAAG,CAAC,CAAA;IACnE,CAAC,CAAC,CAAA;AACN,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,EAC7B,KAAK,GASN,EAAE,EAAE;IACH,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,GAAG,KAAK,CAAA;IACxE,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAA;IACrD,CAAC;IAED,IAAI,CAAC;QACH,UAAU,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAA;QAC7C,eAAe,EAAE,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAA;IACjC,CAAC;IAAC,OAAO,aAAa,EAAE,CAAC;QACvB,OAAO,CAAC,KAAK,CAAC,uCAAuC,OAAO,GAAG,EAAE,aAAa,CAAC,CAAA;QAC/E,eAAe,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,aAAsB,EAAE,CAAC,CAAA;IACjE,CAAC;AACH,CAAC,CAAA"}
+{"version":3,"file":"subject.js","sourceRoot":"","sources":["../../src/actions/subject.ts"],"names":[],"mappings":"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"}

package/dist/telemetry.d.ts

@@ -0,0 +1,27 @@
+import type { Context, Span, Tracer } from '@opentelemetry/api';
+import type { MsgHdrs } from '@nats-io/nats-core';
+export declare function getTracer(): Tracer;
+/**
+ * Record an error on a span using the OTel canonical pattern:
+ * recordException + ERROR status + a named event with the truncated stack.
+ */
+export declare function recordError(span: Span, errorEventName: string, err: unknown): void;
+/**
+ * Run `fn` inside an active span. On synchronous throw or async rejection the
+ * error is recorded, the span status is set to ERROR, and the error is
+ * re-thrown (callers keep their existing error-handling semantics).
+ */
+export declare function withSpan<T>(name: string, errorEventName: string, attributes: Record<string, string | number | boolean | undefined>, fn: (span: Span) => T | Promise<T>, parentContext?: Context): T | Promise<T>;
+/**
+ * Inject the active OTel context into a NATS headers object, creating one if
+ * none was supplied. Returns the headers object so the caller can pass it to
+ * `connection.publish` / `connection.request` via the `opts.headers` field.
+ */
+export declare function injectContextIntoHeaders(existing?: MsgHdrs): MsgHdrs;
+/**
+ * Extract a parent OTel context from an incoming NATS message's headers. When
+ * no traceparent is present the returned context is whatever was already
+ * active — callers can use it as the parent for a new span without a branch.
+ */
+export declare function extractContextFromHeaders(hdrs: MsgHdrs | undefined): Context;
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAA;AAE/D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAA;AASjD,wBAAgB,SAAS,IAAI,MAAM,CAElC;AAcD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,IAAI,CAQlF;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EACxB,IAAI,EAAE,MAAM,EACZ,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,EACjE,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAClC,aAAa,CAAC,EAAE,OAAO,GACtB,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CA4BhB;AA8BD;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,OAAO,CAIpE;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,OAAO,GAAG,SAAS,GAAG,OAAO,CAG5E"}

package/dist/telemetry.js

@@ -0,0 +1,125 @@
+// OpenTelemetry helpers scoped to this package.
+//
+// `@opentelemetry/api` is declared as a peer dependency so the consumer
+// controls the installed version. If the consumer never registers a
+// TracerProvider / TextMapPropagator, every call here becomes a no-op.
+//
+// Design choices:
+//   - Single module-level tracer, named and versioned from package.json.
+//   - `withSpan` wraps the common try/catch/recordException/setStatus pattern
+//     so call sites stay readable.
+//   - `injectContextIntoHeaders` / `extractContextFromHeaders` bridge the
+//     OTel propagation API onto NATS `MsgHdrs`. Outgoing messages carry the
+//     active traceparent; incoming messages become the active context for
+//     the per-message span so cross-process traces nest automatically.
+import { context as otelContext, propagation, SpanStatusCode, trace } from '@opentelemetry/api';
+import { headers as natsHeaders } from '@nats-io/nats-core';
+import pkg from '../package.json' with { type: 'json' };
+const TRACER_NAME = '@jr200-labs/xstate-nats';
+// Do not cache — `trace.getTracer` already returns a lightweight ProxyTracer,
+// and caching across global-provider swaps (e.g. test teardown / re-register)
+// would pin the delegate to a retired provider and silently lose spans.
+export function getTracer() {
+    return trace.getTracer(TRACER_NAME, pkg.version);
+}
+// Truncate the stack trace before attaching it to a span event. Some backends
+// (and the wire format itself) perform poorly with arbitrarily long strings;
+// the first ~1KB is almost always enough to identify the site.
+const MAX_STACK_LEN = 1024;
+function truncateStack(err) {
+    if (!(err instanceof Error) || !err.stack)
+        return undefined;
+    return err.stack.length > MAX_STACK_LEN
+        ? err.stack.slice(0, MAX_STACK_LEN) + '...(truncated)'
+        : err.stack;
+}
+/**
+ * Record an error on a span using the OTel canonical pattern:
+ * recordException + ERROR status + a named event with the truncated stack.
+ */
+export function recordError(span, errorEventName, err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (err instanceof Error) {
+        span.recordException(err);
+    }
+    span.setStatus({ code: SpanStatusCode.ERROR, message });
+    const stack = truncateStack(err);
+    span.addEvent(errorEventName, stack ? { stack } : undefined);
+}
+/**
+ * Run `fn` inside an active span. On synchronous throw or async rejection the
+ * error is recorded, the span status is set to ERROR, and the error is
+ * re-thrown (callers keep their existing error-handling semantics).
+ */
+export function withSpan(name, errorEventName, attributes, fn, parentContext) {
+    const tracer = getTracer();
+    const sanitized = sanitizeAttributes(attributes);
+    const ctx = parentContext ?? otelContext.active();
+    return tracer.startActiveSpan(name, { attributes: sanitized }, ctx, (span) => {
+        try {
+            const result = fn(span);
+            if (result && typeof result.then === 'function') {
+                return result.then((value) => {
+                    span.end();
+                    return value;
+                }, (err) => {
+                    recordError(span, errorEventName, err);
+                    span.end();
+                    throw err;
+                });
+            }
+            span.end();
+            return result;
+        }
+        catch (err) {
+            recordError(span, errorEventName, err);
+            span.end();
+            throw err;
+        }
+    });
+}
+// OTel attributes cannot be `undefined`; strip those so call sites can pass
+// optional values without a pre-filter.
+function sanitizeAttributes(attrs) {
+    const out = {};
+    for (const [k, v] of Object.entries(attrs)) {
+        if (v !== undefined)
+            out[k] = v;
+    }
+    return out;
+}
+// Carrier adapters: NATS `MsgHdrs` exposes `.set(k, v)`, `.get(k)`, `.keys()`
+// which maps cleanly to the OTel TextMapSetter / TextMapGetter interface.
+const natsHeaderSetter = {
+    set: (carrier, key, value) => {
+        carrier.set(key, value);
+    },
+};
+const natsHeaderGetter = {
+    get: (carrier, key) => {
+        const v = carrier?.get(key);
+        return v || undefined;
+    },
+    keys: (carrier) => carrier?.keys() ?? [],
+};
+/**
+ * Inject the active OTel context into a NATS headers object, creating one if
+ * none was supplied. Returns the headers object so the caller can pass it to
+ * `connection.publish` / `connection.request` via the `opts.headers` field.
+ */
+export function injectContextIntoHeaders(existing) {
+    const hdrs = existing ?? natsHeaders();
+    propagation.inject(otelContext.active(), hdrs, natsHeaderSetter);
+    return hdrs;
+}
+/**
+ * Extract a parent OTel context from an incoming NATS message's headers. When
+ * no traceparent is present the returned context is whatever was already
+ * active — callers can use it as the parent for a new span without a branch.
+ */
+export function extractContextFromHeaders(hdrs) {
+    if (!hdrs)
+        return otelContext.active();
+    return propagation.extract(otelContext.active(), hdrs, natsHeaderGetter);
+}
+//# sourceMappingURL=telemetry.js.map

package/dist/telemetry.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jr200-labs/xstate-nats",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "XState machine for NATS",
   "license": "MIT",
   "author": "Jayshan Raghunandan",
@@ -37,12 +37,24 @@
     "@nats-io/obj": "^3.3.1",
     "xstate": "^5.30.0"
   },
+  "peerDependencies": {
+    "@opentelemetry/api": "^1.9.0"
+  },
   "devDependencies": {
-    "@vitest/coverage-v8": "^4.1.3",
+    "@eslint/js": "^10.0.1",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/context-async-hooks": "^2.7.0",
+    "@opentelemetry/core": "^2.7.0",
+    "@opentelemetry/sdk-trace-base": "^2.7.0",
+    "@vitest/coverage-v8": "^4.1.4",
+    "eslint": "^10.2.1",
+    "globals": "^17.5.0",
     "husky": "^9.1.7",
-    "prettier": "^3.8.1",
+    "prettier": "^3.8.3",
+    "syncpack": "^14.3.0",
     "typescript": "^6.0.2",
-    "vitest": "^4.1.3"
+    "typescript-eslint": "^8.58.2",
+    "vitest": "^4.1.4"
   },
   "scripts": {
     "build": "tsc",
@@ -50,6 +62,6 @@
     "test:run": "vitest run",
     "test:watch": "vitest",
     "prettier": "prettier --write \"**/*.{ts,mjs,js,json,md,yml,yaml}\"",
-    "lint": "tsc --noEmit"
+    "lint": "tsc --noEmit && eslint \"src/**/*.{ts,tsx}\""
   }
 }

package/src/actions/connection.ts

@@ -10,6 +10,7 @@ import {
 import { KvEntry } from '@nats-io/kv'
 import { type AuthConfig } from './types'
 import { sendParent } from 'xstate'
+import { withSpan } from '../telemetry'
 
 const makeAuthConfig = (auth?: AuthConfig) => {
   if (!auth) {
@@ -68,7 +69,16 @@ export const connectToNats = fromPromise(
             sendParent({ type: 'NATS_CONNECTION.DISCONNECTED', status })
             break
           case 'reconnect':
-            sendParent({ type: 'NATS_CONNECTION.RECONNECT', status })
+            // Per-event span so reconnect attempts become discoverable in
+            // the trace backend (searchable, durations, span counts).
+            withSpan(
+              'xstate.nats.reconnect',
+              'xstate.nats.error',
+              { 'reconnect.type': type },
+              () => {
+                sendParent({ type: 'NATS_CONNECTION.RECONNECT', status })
+              },
+            )
             break
           case 'error':
             sendParent({ type: 'NATS_CONNECTION.ERROR', status })
@@ -83,10 +93,24 @@ export const connectToNats = fromPromise(
             // console.debug('Received ping, pong sent automatically')
             break
           case 'forceReconnect':
-            sendParent({ type: 'NATS_CONNECTION.RECONNECT', status })
+            withSpan(
+              'xstate.nats.reconnect',
+              'xstate.nats.error',
+              { 'reconnect.type': type },
+              () => {
+                sendParent({ type: 'NATS_CONNECTION.RECONNECT', status })
+              },
+            )
             break
           case 'reconnecting':
-            sendParent({ type: 'NATS_CONNECTION.RECONNECTING', status })
+            withSpan(
+              'xstate.nats.reconnect',
+              'xstate.nats.error',
+              { 'reconnect.type': type },
+              () => {
+                sendParent({ type: 'NATS_CONNECTION.RECONNECTING', status })
+              },
+            )
             break
           case 'slowConsumer':
             console.debug('SLOW_CONSUMER', status)

package/src/actions/kv.ts

@@ -2,6 +2,7 @@ import { NatsConnection, QueuedIterator } from '@nats-io/nats-core'
 import { Kvm, KvWatchEntry, KvWatchOptions } from '@nats-io/kv'
 import { Pair } from '../utils'
 import { fromPromise } from 'xstate'
+import { recordError, withSpan } from '../telemetry'
 
 export class KvSubscriptionKey extends Pair<string, string> {}
 
@@ -54,25 +55,52 @@ export const kvConsolidateState = fromPromise(
           const kv = await input.kvm.open(config.bucket)
 
           const watchOptions = config as KvWatchOptions
-          const watcher = await kv.watch(watchOptions)
+          // Short span around the synchronous-ish watch() setup — the watcher
+          // iterator itself is long-lived, so each received entry gets its
+          // own span below rather than one indefinite parent.
+          const watcher = (await withSpan(
+            'xstate.nats.kv.watch',
+            'xstate.nats.kv.error',
+            { bucket: config.bucket, key: config.key },
+            () => kv.watch(watchOptions),
+          )) as QueuedIterator<KvWatchEntry>
 
           syncedState.set(kvKey, watcher)
           ;(async () => {
             try {
               for await (const e of watcher) {
                 if (e.operation !== 'DEL') {
-                  let parsedValue
-                  try {
-                    parsedValue = JSON.parse(e.string())
-                  } catch {
-                    parsedValue = e.string()
-                  }
+                  await withSpan(
+                    'xstate.nats.kv.entry',
+                    'xstate.nats.kv.error',
+                    {
+                      bucket: config.bucket,
+                      key: config.key,
+                      operation: e.operation,
+                    },
+                    (span) => {
+                      let parsedValue
+                      try {
+                        parsedValue = JSON.parse(e.string())
+                      } catch {
+                        parsedValue = e.string()
+                      }
 
-                  config.callback({
-                    bucket: config.bucket,
-                    key: config.key,
-                    value: parsedValue,
-                  })
+                      try {
+                        config.callback({
+                          bucket: config.bucket,
+                          key: config.key,
+                          value: parsedValue,
+                        })
+                      } catch (callbackError) {
+                        recordError(span, 'xstate.nats.kv.error', callbackError)
+                        console.error(
+                          `KV_SUBSCRIBE (connected): Callback error for ${kvKey}:`,
+                          callbackError,
+                        )
+                      }
+                    },
+                  )
                 }
               }
             } catch (error) {

package/src/actions/subject.telemetry.test.ts

@@ -0,0 +1,199 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { SpanStatusCode } from '@opentelemetry/api'
+import { headers as natsHeaders } from '@nats-io/nats-core'
+import { setupInMemoryTracer, type OtelTestHarness } from '../../test/otel-setup'
+import { subjectConsolidateState, subjectPublish, subjectRequest } from './subject'
+import type { SubjectSubscriptionConfig } from './subject'
+
+vi.mock('./connection', () => ({
+  parseNatsResult: vi.fn((msg: any) => {
+    if (!msg) return null
+    try {
+      return msg.json()
+    } catch {
+      return msg.string()
+    }
+  }),
+}))
+
+function createMockConnection() {
+  return {
+    subscribe: vi.fn(),
+    request: vi.fn(),
+    publish: vi.fn(),
+  } as any
+}
+
+describe('subject telemetry', () => {
+  let harness: OtelTestHarness
+
+  beforeEach(() => {
+    harness = setupInMemoryTracer()
+    vi.spyOn(console, 'error').mockImplementation(() => {})
+  })
+
+  afterEach(() => {
+    harness.teardown()
+    vi.restoreAllMocks()
+  })
+
+  it('emits xstate.nats.subscribe span when adding a subscription', () => {
+    const connection = createMockConnection()
+    connection.subscribe.mockReturnValue({
+      unsubscribe: vi.fn(),
+      [Symbol.asyncIterator]: () => ({ next: () => new Promise(() => {}) }),
+    })
+
+    const target = new Map<string, SubjectSubscriptionConfig>([
+      ['t.sub', { subject: 't.sub', callback: vi.fn() }],
+    ])
+
+    subjectConsolidateState({
+      input: { connection, currentSubscriptions: new Map(), targetSubscriptions: target },
+    })
+
+    const spans = harness.exporter.getFinishedSpans()
+    const sub = spans.find((s) => s.name === 'xstate.nats.subscribe')
+    expect(sub).toBeDefined()
+    expect(sub!.attributes.subject).toBe('t.sub')
+    expect(sub!.status.code).not.toBe(SpanStatusCode.ERROR)
+  })
+
+  it('emits xstate.nats.publish span with payload bytes', () => {
+    const connection = createMockConnection()
+    subjectPublish({
+      input: { connection, subject: 't.pub', payload: 'hello' },
+    })
+
+    const spans = harness.exporter.getFinishedSpans()
+    const pub = spans.find((s) => s.name === 'xstate.nats.publish')
+    expect(pub).toBeDefined()
+    expect(pub!.attributes.subject).toBe('t.pub')
+    expect(pub!.attributes['payload.bytes']).toBe(5)
+  })
+
+  it('injects traceparent into publish headers', () => {
+    const connection = createMockConnection()
+    subjectPublish({
+      input: { connection, subject: 't.pub', payload: 'x' },
+    })
+
+    const call = connection.publish.mock.calls[0]
+    const opts = call[2]
+    expect(opts.headers).toBeDefined()
+    // traceparent header is set by W3CTraceContextPropagator
+    expect(opts.headers.get('traceparent')).toBeTruthy()
+  })
+
+  it('records error on publish span when connection.publish throws', () => {
+    const connection = createMockConnection()
+    connection.publish.mockImplementation(() => {
+      throw new Error('boom')
+    })
+
+    subjectPublish({
+      input: { connection, subject: 't.fail', payload: 'x' },
+    })
+
+    const spans = harness.exporter.getFinishedSpans()
+    const pub = spans.find((s) => s.name === 'xstate.nats.publish')
+    expect(pub).toBeDefined()
+    expect(pub!.status.code).toBe(SpanStatusCode.ERROR)
+    expect(pub!.events.some((e) => e.name === 'xstate.nats.error')).toBe(true)
+  })
+
+  it('emits xstate.nats.request span with request attrs', async () => {
+    const connection = createMockConnection()
+    connection.request.mockResolvedValue({
+      json: () => ({ ok: true }),
+      string: () => '{"ok":true}',
+    })
+
+    subjectRequest({
+      input: {
+        connection,
+        subject: 't.req',
+        payload: 'x',
+        opts: { timeout: 2500 } as any,
+        callback: vi.fn(),
+      },
+    })
+
+    await vi.waitFor(() => {
+      expect(
+        harness.exporter.getFinishedSpans().some((s) => s.name === 'xstate.nats.request'),
+      ).toBe(true)
+    })
+
+    const req = harness.exporter.getFinishedSpans().find((s) => s.name === 'xstate.nats.request')!
+    expect(req.attributes.subject).toBe('t.req')
+    expect(req.attributes['timeout.ms']).toBe(2500)
+  })
+
+  it('records error on request span when connection.request rejects', async () => {
+    const connection = createMockConnection()
+    connection.request.mockRejectedValue(new Error('nope'))
+
+    subjectRequest({
+      input: { connection, subject: 't.req', payload: 'x', callback: vi.fn() },
+    })
+
+    await vi.waitFor(() => {
+      const req = harness.exporter.getFinishedSpans().find((s) => s.name === 'xstate.nats.request')
+      expect(req?.status.code).toBe(SpanStatusCode.ERROR)
+    })
+  })
+
+  it('parents per-message span on extracted traceparent', async () => {
+    const connection = createMockConnection()
+    // Craft a headers object containing a known traceparent so the extractor
+    // has something to parent on.
+    const incomingHdrs = natsHeaders()
+    incomingHdrs.set('traceparent', '00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01')
+
+    let resolveIter: () => void
+    const iterDone = new Promise<void>((r) => (resolveIter = r))
+    let delivered = false
+    connection.subscribe.mockReturnValue({
+      unsubscribe: vi.fn(),
+      [Symbol.asyncIterator]: () => ({
+        next: () => {
+          if (!delivered) {
+            delivered = true
+            return Promise.resolve({
+              value: {
+                headers: incomingHdrs,
+                json: () => ({ hi: 1 }),
+                string: () => '{"hi":1}',
+                data: new Uint8Array([1, 2, 3]),
+              },
+              done: false,
+            })
+          }
+          resolveIter!()
+          return new Promise(() => {})
+        },
+      }),
+    })
+
+    const target = new Map<string, SubjectSubscriptionConfig>([
+      ['t.msg', { subject: 't.msg', callback: vi.fn() }],
+    ])
+    subjectConsolidateState({
+      input: { connection, currentSubscriptions: new Map(), targetSubscriptions: target },
+    })
+
+    await iterDone
+    await vi.waitFor(() => {
+      expect(
+        harness.exporter.getFinishedSpans().some((s) => s.name === 'xstate.nats.message'),
+      ).toBe(true)
+    })
+
+    const msgSpan = harness.exporter
+      .getFinishedSpans()
+      .find((s) => s.name === 'xstate.nats.message')!
+    expect(msgSpan.spanContext().traceId).toBe('0af7651916cd43dd8448eb211c80319c')
+    expect(msgSpan.attributes.subject).toBe('t.msg')
+  })
+})

package/src/actions/subject.test.ts

@@ -332,7 +332,11 @@ describe('subjectRequest', () => {
       expect(callback).toHaveBeenCalled()
     })
 
-    expect(connection.request).toHaveBeenCalledWith('test.request', { data: 1 }, { timeout: 5000 })
+    expect(connection.request).toHaveBeenCalledWith(
+      'test.request',
+      { data: 1 },
+      expect.objectContaining({ timeout: 5000 }),
+    )
   })
 
   it('should handle request errors', async () => {
@@ -387,7 +391,11 @@ describe('subjectPublish', () => {
       },
     })
 
-    expect(connection.publish).toHaveBeenCalledWith('test.publish', { msg: 'hello' }, undefined)
+    expect(connection.publish).toHaveBeenCalledWith(
+      'test.publish',
+      { msg: 'hello' },
+      expect.objectContaining({ headers: expect.anything() }),
+    )
   })
 
   it('should call onPublishResult with ok on success', () => {
@@ -419,7 +427,11 @@ describe('subjectPublish', () => {
       },
     })
 
-    expect(connection.publish).toHaveBeenCalledWith('test.publish', 'data', options)
+    expect(connection.publish).toHaveBeenCalledWith(
+      'test.publish',
+      'data',
+      expect.objectContaining({ headers: expect.anything() }),
+    )
   })
 
   it('should call onPublishResult with error on failure', () => {

package/src/actions/subject.ts

@@ -7,6 +7,12 @@ import {
   SubscriptionOptions,
 } from '@nats-io/nats-core'
 import { parseNatsResult } from './connection'
+import {
+  extractContextFromHeaders,
+  injectContextIntoHeaders,
+  recordError,
+  withSpan,
+} from '../telemetry'
 
 export type SubjectSubscriptionConfig = {
   subject: string
@@ -46,17 +52,41 @@ export const subjectConsolidateState = ({
   for (const [subject, subscriptionConfig] of targetSubscriptions) {
     if (!currentSubscriptions.has(subject)) {
       try {
-        const sub = connection.subscribe(subject, subscriptionConfig.opts)
+        // Short span around the synchronous subscribe() call. The iterator
+        // below is long-lived; we don't span its whole lifetime (indefinite
+        // spans are anti-pattern in most tracing backends).
+        const sub = withSpan('xstate.nats.subscribe', 'xstate.nats.error', { subject }, () =>
+          connection.subscribe(subject, subscriptionConfig.opts),
+        ) as Subscription
 
-        // Set up the message handler
+        // Message loop: each received message starts its own span, parented
+        // on the traceparent extracted from the message headers (OTel
+        // messaging semconv). If the publisher did not propagate context the
+        // extracted context falls back to the ambient one, so the span
+        // simply becomes a root.
         ;(async () => {
           try {
             for await (const msg of sub) {
-              try {
-                subscriptionConfig?.callback(parseNatsResult(msg))
-              } catch (callbackError) {
-                console.error(`Callback error for subject "${subject}"`, callbackError)
-              }
+              const parentCtx = extractContextFromHeaders((msg as Msg).headers)
+              await withSpan(
+                'xstate.nats.message',
+                'xstate.nats.error',
+                {
+                  subject,
+                  'payload.bytes': (msg as Msg).data?.length,
+                },
+                (span) => {
+                  try {
+                    subscriptionConfig?.callback(parseNatsResult(msg))
+                  } catch (callbackError) {
+                    // Record on span AND preserve the existing console.error
+                    // so consumers without OTel still see the failure.
+                    recordError(span, 'xstate.nats.error', callbackError)
+                    console.error(`Callback error for subject "${subject}"`, callbackError)
+                  }
+                },
+                parentCtx,
+              )
             }
           } catch (iteratorError) {
             console.error(`Iterator error for subject "${subject}"`, iteratorError)
@@ -91,14 +121,44 @@ export const subjectRequest = ({
     throw new Error('NATS connection is not available')
   }
 
-  connection
-    .request(subject, payload, opts)
-    .then((msg: Msg) => {
-      callback(parseNatsResult(msg))
-    })
-    .catch((err) => {
-      console.error(`RequestReply error for subject "${subject}"`, err)
-    })
+  const payloadBytes =
+    payload instanceof Uint8Array
+      ? payload.byteLength
+      : typeof payload === 'string'
+        ? payload.length
+        : undefined
+
+  void withSpan(
+    'xstate.nats.request',
+    'xstate.nats.error',
+    {
+      subject,
+      'payload.bytes': payloadBytes,
+      'timeout.ms': opts?.timeout,
+    },
+    (span) => {
+      // Inject INSIDE the span so the replying service parents its handler
+      // span on this request span (not on an ambient context). RequestOptions
+      // declares `timeout` as required but nats-core only enforces it when
+      // opts is provided; cast preserves the "no opts = use conn default"
+      // contract.
+      const headers = injectContextIntoHeaders(opts?.headers)
+      const requestOpts = (opts ? { ...opts, headers } : { headers }) as RequestOptions
+
+      return connection
+        .request(subject, payload, requestOpts)
+        .then((msg: Msg) => {
+          callback(parseNatsResult(msg))
+        })
+        .catch((err) => {
+          // Record on span manually so we can swallow the rejection here —
+          // the original fire-and-forget API didn't propagate request errors
+          // to callers and changing that now would be a breaking behaviour.
+          recordError(span, 'xstate.nats.error', err)
+          console.error(`RequestReply error for subject "${subject}"`, err)
+        })
+    },
+  )
 }
 
 export const subjectPublish = ({
@@ -117,8 +177,26 @@ export const subjectPublish = ({
     throw new Error('NATS connection is not available')
   }
 
+  const payloadBytes =
+    payload instanceof Uint8Array
+      ? payload.byteLength
+      : typeof payload === 'string'
+        ? payload.length
+        : undefined
+
   try {
-    connection.publish(subject, payload, options)
+    withSpan(
+      'xstate.nats.publish',
+      'xstate.nats.error',
+      { subject, 'payload.bytes': payloadBytes },
+      () => {
+        // Inject INSIDE the span so downstream subscribers see THIS span as
+        // parent instead of whatever was ambient before publish.
+        const headers = injectContextIntoHeaders(options?.headers)
+        const publishOpts: PublishOptions = { ...(options ?? {}), headers }
+        connection.publish(subject, payload, publishOpts)
+      },
+    )
     onPublishResult?.({ ok: true })
   } catch (callbackError) {
     console.error(`Publish callback error for subject "${subject}"`, callbackError)

package/src/machines/kv.test.ts

@@ -2,9 +2,13 @@ import { describe, it, expect, vi, beforeEach } from 'vitest'
 import { createActor, fromPromise, sendTo, setup, assign } from 'xstate'
 import { kvManagerLogic } from './kv'
 
-vi.mock('@nats-io/nats-core', () => ({
-  wsconnect: vi.fn(),
-}))
+vi.mock('@nats-io/nats-core', async () => {
+  const actual = await vi.importActual<typeof import('@nats-io/nats-core')>('@nats-io/nats-core')
+  return {
+    ...actual,
+    wsconnect: vi.fn(),
+  }
+})
 
 // We'll set up specific Kvm mock behavior per test
 const mockKvStore = {

package/src/machines/root.test.ts

@@ -2,10 +2,14 @@ import { describe, it, expect, vi, beforeEach } from 'vitest'
 import { createActor, fromPromise, createMachine, sendParent } from 'xstate'
 import { natsMachine } from './root'
 
-vi.mock('@nats-io/nats-core', () => ({
-  wsconnect: vi.fn(),
-  credsAuthenticator: vi.fn(),
-}))
+vi.mock('@nats-io/nats-core', async () => {
+  const actual = await vi.importActual<typeof import('@nats-io/nats-core')>('@nats-io/nats-core')
+  return {
+    ...actual,
+    wsconnect: vi.fn(),
+    credsAuthenticator: vi.fn(),
+  }
+})
 
 vi.mock('@nats-io/kv', () => ({
   Kvm: vi.fn().mockImplementation(() => ({})),

package/src/machines/subject.test.ts

@@ -2,9 +2,13 @@ import { describe, it, expect, vi, beforeEach } from 'vitest'
 import { createActor, createMachine, assign, fromPromise, sendTo, setup } from 'xstate'
 import { subjectManagerLogic } from './subject'
 
-vi.mock('@nats-io/nats-core', () => ({
-  wsconnect: vi.fn(),
-}))
+vi.mock('@nats-io/nats-core', async () => {
+  const actual = await vi.importActual<typeof import('@nats-io/nats-core')>('@nats-io/nats-core')
+  return {
+    ...actual,
+    wsconnect: vi.fn(),
+  }
+})
 
 function createMockConnection() {
   return {
@@ -195,7 +199,11 @@ describe('subjectManagerLogic', () => {
       payload: { msg: 'hello' },
     })
 
-    expect(connection.publish).toHaveBeenCalledWith('test.pub', { msg: 'hello' }, undefined)
+    expect(connection.publish).toHaveBeenCalledWith(
+      'test.pub',
+      { msg: 'hello' },
+      expect.objectContaining({ headers: expect.anything() }),
+    )
     parentActor.stop()
   })
 
@@ -214,7 +222,11 @@ describe('subjectManagerLogic', () => {
       callback,
     })
 
-    expect(connection.request).toHaveBeenCalledWith('test.req', { data: 1 }, undefined)
+    expect(connection.request).toHaveBeenCalledWith(
+      'test.req',
+      { data: 1 },
+      expect.objectContaining({ headers: expect.anything() }),
+    )
     parentActor.stop()
   })
 

package/src/telemetry.ts

@@ -0,0 +1,145 @@
+// OpenTelemetry helpers scoped to this package.
+//
+// `@opentelemetry/api` is declared as a peer dependency so the consumer
+// controls the installed version. If the consumer never registers a
+// TracerProvider / TextMapPropagator, every call here becomes a no-op.
+//
+// Design choices:
+//   - Single module-level tracer, named and versioned from package.json.
+//   - `withSpan` wraps the common try/catch/recordException/setStatus pattern
+//     so call sites stay readable.
+//   - `injectContextIntoHeaders` / `extractContextFromHeaders` bridge the
+//     OTel propagation API onto NATS `MsgHdrs`. Outgoing messages carry the
+//     active traceparent; incoming messages become the active context for
+//     the per-message span so cross-process traces nest automatically.
+
+import type { Context, Span, Tracer } from '@opentelemetry/api'
+import { context as otelContext, propagation, SpanStatusCode, trace } from '@opentelemetry/api'
+import type { MsgHdrs } from '@nats-io/nats-core'
+import { headers as natsHeaders } from '@nats-io/nats-core'
+import pkg from '../package.json' with { type: 'json' }
+
+const TRACER_NAME = '@jr200-labs/xstate-nats'
+
+// Do not cache — `trace.getTracer` already returns a lightweight ProxyTracer,
+// and caching across global-provider swaps (e.g. test teardown / re-register)
+// would pin the delegate to a retired provider and silently lose spans.
+export function getTracer(): Tracer {
+  return trace.getTracer(TRACER_NAME, pkg.version)
+}
+
+// Truncate the stack trace before attaching it to a span event. Some backends
+// (and the wire format itself) perform poorly with arbitrarily long strings;
+// the first ~1KB is almost always enough to identify the site.
+const MAX_STACK_LEN = 1024
+
+function truncateStack(err: unknown): string | undefined {
+  if (!(err instanceof Error) || !err.stack) return undefined
+  return err.stack.length > MAX_STACK_LEN
+    ? err.stack.slice(0, MAX_STACK_LEN) + '...(truncated)'
+    : err.stack
+}
+
+/**
+ * Record an error on a span using the OTel canonical pattern:
+ * recordException + ERROR status + a named event with the truncated stack.
+ */
+export function recordError(span: Span, errorEventName: string, err: unknown): void {
+  const message = err instanceof Error ? err.message : String(err)
+  if (err instanceof Error) {
+    span.recordException(err)
+  }
+  span.setStatus({ code: SpanStatusCode.ERROR, message })
+  const stack = truncateStack(err)
+  span.addEvent(errorEventName, stack ? { stack } : undefined)
+}
+
+/**
+ * Run `fn` inside an active span. On synchronous throw or async rejection the
+ * error is recorded, the span status is set to ERROR, and the error is
+ * re-thrown (callers keep their existing error-handling semantics).
+ */
+export function withSpan<T>(
+  name: string,
+  errorEventName: string,
+  attributes: Record<string, string | number | boolean | undefined>,
+  fn: (span: Span) => T | Promise<T>,
+  parentContext?: Context,
+): T | Promise<T> {
+  const tracer = getTracer()
+  const sanitized = sanitizeAttributes(attributes)
+  const ctx = parentContext ?? otelContext.active()
+  return tracer.startActiveSpan(name, { attributes: sanitized }, ctx, (span) => {
+    try {
+      const result = fn(span)
+      if (result && typeof (result as Promise<T>).then === 'function') {
+        return (result as Promise<T>).then(
+          (value) => {
+            span.end()
+            return value
+          },
+          (err: unknown) => {
+            recordError(span, errorEventName, err)
+            span.end()
+            throw err
+          },
+        ) as unknown as T
+      }
+      span.end()
+      return result
+    } catch (err) {
+      recordError(span, errorEventName, err)
+      span.end()
+      throw err
+    }
+  })
+}
+
+// OTel attributes cannot be `undefined`; strip those so call sites can pass
+// optional values without a pre-filter.
+function sanitizeAttributes(
+  attrs: Record<string, string | number | boolean | undefined>,
+): Record<string, string | number | boolean> {
+  const out: Record<string, string | number | boolean> = {}
+  for (const [k, v] of Object.entries(attrs)) {
+    if (v !== undefined) out[k] = v
+  }
+  return out
+}
+
+// Carrier adapters: NATS `MsgHdrs` exposes `.set(k, v)`, `.get(k)`, `.keys()`
+// which maps cleanly to the OTel TextMapSetter / TextMapGetter interface.
+const natsHeaderSetter = {
+  set: (carrier: MsgHdrs, key: string, value: string) => {
+    carrier.set(key, value)
+  },
+}
+
+const natsHeaderGetter = {
+  get: (carrier: MsgHdrs | undefined, key: string): string | undefined => {
+    const v = carrier?.get(key)
+    return v || undefined
+  },
+  keys: (carrier: MsgHdrs | undefined): string[] => carrier?.keys() ?? [],
+}
+
+/**
+ * Inject the active OTel context into a NATS headers object, creating one if
+ * none was supplied. Returns the headers object so the caller can pass it to
+ * `connection.publish` / `connection.request` via the `opts.headers` field.
+ */
+export function injectContextIntoHeaders(existing?: MsgHdrs): MsgHdrs {
+  const hdrs = existing ?? natsHeaders()
+  propagation.inject(otelContext.active(), hdrs, natsHeaderSetter)
+  return hdrs
+}
+
+/**
+ * Extract a parent OTel context from an incoming NATS message's headers. When
+ * no traceparent is present the returned context is whatever was already
+ * active — callers can use it as the parent for a new span without a branch.
+ */
+export function extractContextFromHeaders(hdrs: MsgHdrs | undefined): Context {
+  if (!hdrs) return otelContext.active()
+  return propagation.extract(otelContext.active(), hdrs, natsHeaderGetter)
+}