@spanhq/bullmq 0.1.0

package/README.md

@@ -0,0 +1,171 @@
+# @spanhq/bullmq
+
+Distributed tracing SDK for BullMQ background jobs. Automatically captures job execution traces, retry timelines, and failure details without modifying your processor code.
+
+## Installation
+
+```bash
+npm install @spanhq/bullmq
+# or
+bun add @spanhq/bullmq
+# or
+yarn add @spanhq/bullmq
+```
+
+**Peer dependency:** `bullmq >= 4.0.0`
+
+## Quick Start
+
+```typescript
+import { createTracer } from '@spanhq/bullmq'
+import { Worker, Queue } from 'bullmq'
+
+const tracer = createTracer({ apiKey: 'jt_live_xxxx' })
+
+const worker = tracer.traceWorker(new Worker('my-queue', async (job) => {
+  // your existing processor logic — no changes needed
+}, { connection: redis }))
+
+const queue = tracer.traceQueue(new Queue('my-queue', { connection: redis }))
+
+// On shutdown:
+process.on('SIGTERM', async () => {
+  await tracer.shutdown()
+  process.exit(0)
+})
+```
+
+That's it. Every job processed by the worker will automatically generate tracing spans.
+
+## API Reference
+
+### `createTracer(config)`
+
+Creates a new tracer instance.
+
+```typescript
+const tracer = createTracer({
+  apiKey:   'jt_live_xxxx',              // required
+  endpoint: 'https://api.spanhq.dev', // optional (default: production)
+  debug:    false,                        // optional (default: false)
+})
+```
+
+| Option     | Type     | Required | Default                          | Description                     |
+|------------|----------|----------|----------------------------------|---------------------------------|
+| `apiKey`   | `string` | Yes      | `process.env.SPANHQ_API_KEY`  | Your project API key            |
+| `endpoint` | `string` | No       | `https://api.spanhq.dev`      | Backend URL (for self-hosted)   |
+| `debug`    | `boolean`| No       | `false`                          | Enable console logging          |
+
+### `tracer.traceWorker(worker)`
+
+Instruments a BullMQ Worker to capture lifecycle events.
+
+```typescript
+const worker = tracer.traceWorker(new Worker('queue', processor, opts))
+```
+
+**Events captured:**
+- `active` — Job starts processing. Generates trace ID if not inherited.
+- `completed` — Job finishes successfully. Records duration.
+- `failed` — Job fails. Records error message and stack trace. Marks as `dead` if all retries exhausted.
+- `stalled` — Job stalled. Records as a failure event.
+
+Returns the same worker instance (pass-through).
+
+### `tracer.traceQueue(queue)`
+
+Instruments a BullMQ Queue to propagate trace context to child jobs.
+
+```typescript
+const queue = tracer.traceQueue(new Queue('child-queue', opts))
+```
+
+When `queue.add()` is called inside a traced worker processor, the SDK automatically injects `__trace_id` and `__parent_id` into the child job's data. This enables distributed trace propagation across job chains.
+
+Returns the same queue instance (pass-through).
+
+### `tracer.shutdown()`
+
+Gracefully shuts down the tracer. Flushes all buffered spans to the backend.
+
+```typescript
+await tracer.shutdown()
+```
+
+**Important:** Always await `shutdown()` before exiting the process to prevent span loss.
+
+## How Trace Context Propagation Works
+
+```
+Job A (Worker 1)
+  └─ queue.add('child-job', data)
+       └─ Job B (Worker 2)         ← inherits trace_id from Job A
+            └─ queue.add('grandchild', data)
+                 └─ Job C (Worker 3)  ← inherits trace_id from Job A
+```
+
+1. When a root job starts, the SDK generates a unique `trace_id`
+2. If the worker processor calls `queue.add()`, the SDK injects `__trace_id` and `__parent_id` into the child job data
+3. When the child job starts, the SDK reads `__trace_id` from the job data and continues the trace
+4. This works across any number of job chain levels
+
+**AsyncLocalStorage:** The SDK uses Node.js `AsyncLocalStorage` to maintain context across async boundaries within a single worker processor execution.
+
+## Batching & Performance
+
+- Spans are buffered in memory and flushed every **2 seconds**
+- If the buffer reaches **10 spans**, an immediate flush is triggered
+- The SDK **never blocks** your job processing
+- All network errors are silently caught (logged in debug mode)
+
+## Environment Variables
+
+| Variable              | Description                              |
+|-----------------------|------------------------------------------|
+| `SPANHQ_API_KEY`   | API key (alternative to config)          |
+| `SPANHQ_ENDPOINT`  | Backend URL (alternative to config)      |
+
+## Safety Guarantees
+
+The SDK is designed to **never crash your application**:
+
+- All event handlers are wrapped in try-catch blocks
+- Network failures are silently caught and optionally logged
+- The SDK uses fire-and-forget for span delivery
+- If the backend is unreachable, spans are dropped (not queued indefinitely)
+- The `traceWorker` and `traceQueue` functions return the original instances
+
+## Troubleshooting
+
+### Spans not appearing in the dashboard
+
+1. **Check your API key:** Ensure `apiKey` is correct and the project exists
+2. **Enable debug mode:** Set `debug: true` to see SDK logs in the console
+3. **Check the endpoint:** If self-hosted, ensure `endpoint` points to your backend
+4. **Verify network access:** The SDK needs to reach the backend via HTTP POST
+
+### Debug mode output
+
+```typescript
+const tracer = createTracer({ apiKey: '...', debug: true })
+```
+
+Debug mode logs:
+- Every span buffered
+- Every flush (with span count)
+- Backend responses
+- Errors (network, validation, etc.)
+
+### Self-hosted setup
+
+```typescript
+const tracer = createTracer({
+  apiKey: 'jt_live_xxxx',
+  endpoint: 'http://localhost:3000',
+})
+```
+
+## License
+
+MIT

package/dist/cjs/context.d.ts

@@ -0,0 +1,42 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+/** Trace context propagated via AsyncLocalStorage */
+export interface TraceContext {
+    traceId: string;
+    spanId: string;
+}
+/** AsyncLocalStorage instance for trace context propagation */
+export declare const storage: AsyncLocalStorage<TraceContext>;
+/**
+ * Active job context tracking.
+ *
+ * We maintain a Map of ALL currently active job contexts (keyed by
+ * "queueName:jobId"). When a worker processor calls traceQueue.add(),
+ * we look up the context from the correct active job.
+ *
+ * Since BullMQ workers with concurrency > 1 may have multiple active
+ * jobs simultaneously, a single global variable is insufficient.
+ * Instead, we track each active job separately.
+ *
+ * The key insight: traceQueue.add() is called FROM WITHIN a worker
+ * processor, so the "current" context is the one for whichever job's
+ * processor is executing. We use a stack-like approach: each add()
+ * reads the MOST RECENT context that hasn't been completed yet.
+ *
+ * For single-concurrency queues (the pipeline use case), the Map
+ * will have at most one entry per queue, making lookups unambiguous.
+ */
+export declare const activeJobContexts: Map<string, TraceContext>;
+/**
+ * Set context for a specific active job.
+ */
+export declare function setJobContext(key: string, ctx: TraceContext): void;
+/**
+ * Remove context when a job completes or fails.
+ */
+export declare function clearJobContext(key: string): void;
+/**
+ * Get the current trace context.
+ * Priority: AsyncLocalStorage → most recently activated job context.
+ */
+export declare function getCurrentContext(): TraceContext | undefined;
+//# sourceMappingURL=context.d.ts.map

package/dist/cjs/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAErD,qDAAqD;AACrD,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,+DAA+D;AAC/D,eAAO,MAAM,OAAO,iCAAwC,CAAC;AAE7D;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,iBAAiB,2BAAkC,CAAC;AAEjE;;GAEG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,QAE3D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,QAE1C;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,YAAY,GAAG,SAAS,CAY5D"}

package/dist/cjs/context.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.activeJobContexts = exports.storage = void 0;
+exports.setJobContext = setJobContext;
+exports.clearJobContext = clearJobContext;
+exports.getCurrentContext = getCurrentContext;
+const node_async_hooks_1 = require("node:async_hooks");
+/** AsyncLocalStorage instance for trace context propagation */
+exports.storage = new node_async_hooks_1.AsyncLocalStorage();
+/**
+ * Active job context tracking.
+ *
+ * We maintain a Map of ALL currently active job contexts (keyed by
+ * "queueName:jobId"). When a worker processor calls traceQueue.add(),
+ * we look up the context from the correct active job.
+ *
+ * Since BullMQ workers with concurrency > 1 may have multiple active
+ * jobs simultaneously, a single global variable is insufficient.
+ * Instead, we track each active job separately.
+ *
+ * The key insight: traceQueue.add() is called FROM WITHIN a worker
+ * processor, so the "current" context is the one for whichever job's
+ * processor is executing. We use a stack-like approach: each add()
+ * reads the MOST RECENT context that hasn't been completed yet.
+ *
+ * For single-concurrency queues (the pipeline use case), the Map
+ * will have at most one entry per queue, making lookups unambiguous.
+ */
+exports.activeJobContexts = new Map();
+/**
+ * Set context for a specific active job.
+ */
+function setJobContext(key, ctx) {
+    exports.activeJobContexts.set(key, ctx);
+}
+/**
+ * Remove context when a job completes or fails.
+ */
+function clearJobContext(key) {
+    exports.activeJobContexts.delete(key);
+}
+/**
+ * Get the current trace context.
+ * Priority: AsyncLocalStorage → most recently activated job context.
+ */
+function getCurrentContext() {
+    const alsCtx = exports.storage.getStore();
+    if (alsCtx)
+        return alsCtx;
+    // Fallback: return the most recently added active context.
+    // In single-concurrency workers this is always correct.
+    // In multi-concurrency workers, there's a small risk of picking
+    // the wrong context, but for tracing purposes this is acceptable.
+    if (exports.activeJobContexts.size === 0)
+        return undefined;
+    const entries = Array.from(exports.activeJobContexts.values());
+    return entries[entries.length - 1];
+}
+//# sourceMappingURL=context.js.map

package/dist/cjs/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/context.ts"],"names":[],"mappings":";;;AAmCA,sCAEC;AAKD,0CAEC;AAMD,8CAYC;AA9DD,uDAAqD;AAQrD,+DAA+D;AAClD,QAAA,OAAO,GAAG,IAAI,oCAAiB,EAAgB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;GAkBG;AACU,QAAA,iBAAiB,GAAG,IAAI,GAAG,EAAwB,CAAC;AAEjE;;GAEG;AACH,SAAgB,aAAa,CAAC,GAAW,EAAE,GAAiB;IAC1D,yBAAiB,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;AAClC,CAAC;AAED;;GAEG;AACH,SAAgB,eAAe,CAAC,GAAW;IACzC,yBAAiB,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AAChC,CAAC;AAED;;;GAGG;AACH,SAAgB,iBAAiB;IAC/B,MAAM,MAAM,GAAG,eAAO,CAAC,QAAQ,EAAE,CAAC;IAClC,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAE1B,2DAA2D;IAC3D,wDAAwD;IACxD,gEAAgE;IAChE,kEAAkE;IAClE,IAAI,yBAAiB,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAEnD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,yBAAiB,CAAC,MAAM,EAAE,CAAC,CAAC;IACvD,OAAO,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACrC,CAAC"}

package/dist/cjs/index.d.ts

@@ -0,0 +1,47 @@
+import type { TracerConfig } from "@spanhq/shared";
+export { getCurrentContext } from "./context.js";
+export type { TraceContext } from "./context.js";
+export type { TracerConfig } from "@spanhq/shared";
+/** BullMQ Worker type (minimal interface) */
+interface BullMQWorker {
+    name: string;
+    on(event: string, callback: (...args: unknown[]) => void): unknown;
+}
+/** BullMQ Queue type (minimal interface) */
+interface BullMQQueue {
+    name: string;
+    add(name: string, data: Record<string, unknown>, opts?: Record<string, unknown>): Promise<unknown>;
+}
+/** The tracer object returned by createTracer */
+export interface Tracer {
+    /** Instrument a BullMQ Worker to emit tracing spans */
+    traceWorker<T extends BullMQWorker>(worker: T): T;
+    /** Instrument a BullMQ Queue to propagate trace context */
+    traceQueue<T extends BullMQQueue>(queue: T): T;
+    /** Gracefully shutdown — flushes remaining spans before resolving */
+    shutdown(): Promise<void>;
+}
+/**
+ * Create a SpanHQ instance.
+ *
+ * ```ts
+ * import { createTracer } from '@spanhq/bullmq'
+ *
+ * const tracer = createTracer({
+ *   apiKey: 'jt_live_xxxx',
+ *   endpoint: 'https://api.spanhq.dev',
+ *   debug: false,
+ * })
+ *
+ * const worker = tracer.traceWorker(new Worker(...))
+ * const queue  = tracer.traceQueue(new Queue(...))
+ *
+ * // On shutdown:
+ * await tracer.shutdown()
+ * ```
+ *
+ * @param config - API key (required), optional endpoint and debug flag
+ * @returns A tracer object with traceWorker, traceQueue, and shutdown methods
+ */
+export declare function createTracer(config: TracerConfig): Tracer;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAgB,MAAM,gBAAgB,CAAC;AAIjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAInD,6CAA6C;AAC7C,UAAU,YAAY;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,OAAO,CAAC;CACpE;AAED,4CAA4C;AAC5C,UAAU,WAAW;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CACD,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB;AAED,iDAAiD;AACjD,MAAM,WAAW,MAAM;IACrB,uDAAuD;IACvD,WAAW,CAAC,CAAC,SAAS,YAAY,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC;IAClD,2DAA2D;IAC3D,UAAU,CAAC,CAAC,SAAS,WAAW,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC;IAC/C,qEAAqE;IACrE,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAoCzD"}

package/dist/cjs/index.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCurrentContext = void 0;
+exports.createTracer = createTracer;
+const sender_js_1 = require("./sender.js");
+const tracer_js_1 = require("./tracer.js");
+var context_js_1 = require("./context.js");
+Object.defineProperty(exports, "getCurrentContext", { enumerable: true, get: function () { return context_js_1.getCurrentContext; } });
+const DEFAULT_ENDPOINT = "https://api.spanhq.dev";
+/**
+ * Create a SpanHQ instance.
+ *
+ * ```ts
+ * import { createTracer } from '@spanhq/bullmq'
+ *
+ * const tracer = createTracer({
+ *   apiKey: 'jt_live_xxxx',
+ *   endpoint: 'https://api.spanhq.dev',
+ *   debug: false,
+ * })
+ *
+ * const worker = tracer.traceWorker(new Worker(...))
+ * const queue  = tracer.traceQueue(new Queue(...))
+ *
+ * // On shutdown:
+ * await tracer.shutdown()
+ * ```
+ *
+ * @param config - API key (required), optional endpoint and debug flag
+ * @returns A tracer object with traceWorker, traceQueue, and shutdown methods
+ */
+function createTracer(config) {
+    const apiKey = config.apiKey || process.env.SPANHQ_API_KEY || "";
+    const endpoint = config.endpoint ||
+        process.env.SPANHQ_ENDPOINT ||
+        DEFAULT_ENDPOINT;
+    const debug = config.debug ?? false;
+    if (!apiKey && debug) {
+        console.warn("[spanhq] No API key provided. Spans will be buffered but will fail to send.");
+    }
+    const senderConfig = {
+        apiKey,
+        endpoint: endpoint.replace(/\/$/, ""), // Strip trailing slash
+        debug,
+    };
+    const sender = new sender_js_1.SpanSender(senderConfig);
+    return {
+        traceWorker(worker) {
+            return (0, tracer_js_1.traceWorker)(worker, sender, senderConfig);
+        },
+        traceQueue(queue) {
+            return (0, tracer_js_1.traceQueue)(queue, sender, senderConfig);
+        },
+        async shutdown() {
+            await sender.shutdown();
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;AA0DA,oCAoCC;AA7FD,2CAAyC;AACzC,2CAAsD;AAEtD,2CAAiD;AAAxC,+GAAA,iBAAiB,OAAA;AAI1B,MAAM,gBAAgB,GAAG,wBAAwB,CAAC;AA4BlD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,SAAgB,YAAY,CAAC,MAAoB;IAC/C,MAAM,MAAM,GACV,MAAM,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,EAAE,CAAC;IACpD,MAAM,QAAQ,GACZ,MAAM,CAAC,QAAQ;QACf,OAAO,CAAC,GAAG,CAAC,eAAe;QAC3B,gBAAgB,CAAC;IACnB,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,KAAK,CAAC;IAEpC,IAAI,CAAC,MAAM,IAAI,KAAK,EAAE,CAAC;QACrB,OAAO,CAAC,IAAI,CACV,6EAA6E,CAC9E,CAAC;IACJ,CAAC;IAED,MAAM,YAAY,GAAiB;QACjC,MAAM;QACN,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,EAAE,uBAAuB;QAC9D,KAAK;KACN,CAAC;IAEF,MAAM,MAAM,GAAG,IAAI,sBAAU,CAAC,YAAY,CAAC,CAAC;IAE5C,OAAO;QACL,WAAW,CAAyB,MAAS;YAC3C,OAAO,IAAA,uBAAW,EAAC,MAAM,EAAE,MAAM,EAAE,YAAY,CAAM,CAAC;QACxD,CAAC;QAED,UAAU,CAAwB,KAAQ;YACxC,OAAO,IAAA,sBAAU,EAAC,KAAK,EAAE,MAAM,EAAE,YAAY,CAAM,CAAC;QACtD,CAAC;QAED,KAAK,CAAC,QAAQ;YACZ,MAAM,MAAM,CAAC,QAAQ,EAAE,CAAC;QAC1B,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/cjs/sender.d.ts

@@ -0,0 +1,37 @@
+import type { Span, SenderConfig } from "@spanhq/shared";
+/**
+ * SpanSender batches spans and sends them to the SpanHQ backend.
+ *
+ * Safety guarantees:
+ * - NEVER throws an error — all exceptions are caught and optionally logged
+ * - Flushes remaining spans on shutdown before resolving
+ * - Uses a timer-based flush every 2 seconds + size-based flush at 10 spans
+ */
+export declare class SpanSender {
+    private batch;
+    private timer;
+    private readonly config;
+    private inflight;
+    constructor(config: SenderConfig);
+    /**
+     * Add a span to the batch buffer.
+     * Triggers an immediate flush if batch reaches MAX_BATCH_SIZE.
+     */
+    add(span: Span): void;
+    /**
+     * Flush the current batch to the backend.
+     * Copies the batch to a local variable and clears the buffer immediately
+     * to avoid blocking new span additions.
+     */
+    flush(): Promise<void>;
+    /**
+     * Send a batch of spans to the backend. Never throws.
+     */
+    private sendBatch;
+    /**
+     * Shutdown the sender. Clears the timer and flushes remaining spans.
+     * Await this to ensure no spans are lost on process exit.
+     */
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=sender.d.ts.map

package/dist/cjs/sender.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sender.d.ts","sourceRoot":"","sources":["../../src/sender.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAKzD;;;;;;;GAOG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,KAAK,CAAc;IAC3B,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAoC;gBAExC,MAAM,EAAE,YAAY;IAYhC;;;OAGG;IACH,GAAG,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAoBrB;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAW5B;;OAEG;YACW,SAAS;IAoCvB;;;OAGG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAehC"}

package/dist/cjs/sender.js

@@ -0,0 +1,116 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpanSender = void 0;
+const MAX_BATCH_SIZE = 10;
+const FLUSH_INTERVAL_MS = 2000;
+/**
+ * SpanSender batches spans and sends them to the SpanHQ backend.
+ *
+ * Safety guarantees:
+ * - NEVER throws an error — all exceptions are caught and optionally logged
+ * - Flushes remaining spans on shutdown before resolving
+ * - Uses a timer-based flush every 2 seconds + size-based flush at 10 spans
+ */
+class SpanSender {
+    batch = [];
+    timer = null;
+    config;
+    inflight = Promise.resolve();
+    constructor(config) {
+        this.config = config;
+        this.timer = setInterval(() => {
+            void this.flush();
+        }, FLUSH_INTERVAL_MS);
+        // Prevent the timer from keeping the process alive
+        if (this.timer && typeof this.timer === "object" && "unref" in this.timer) {
+            this.timer.unref();
+        }
+    }
+    /**
+     * Add a span to the batch buffer.
+     * Triggers an immediate flush if batch reaches MAX_BATCH_SIZE.
+     */
+    add(span) {
+        try {
+            this.batch.push(span);
+            if (this.config.debug) {
+                console.log(`[spanhq] Span buffered: ${span.job_name} (${span.status}), batch size: ${this.batch.length}`);
+            }
+            if (this.batch.length >= MAX_BATCH_SIZE) {
+                void this.flush();
+            }
+        }
+        catch (err) {
+            if (this.config.debug) {
+                console.error("[spanhq] Failed to add span to batch:", err);
+            }
+        }
+    }
+    /**
+     * Flush the current batch to the backend.
+     * Copies the batch to a local variable and clears the buffer immediately
+     * to avoid blocking new span additions.
+     */
+    async flush() {
+        if (this.batch.length === 0)
+            return;
+        const toSend = this.batch.slice();
+        this.batch = [];
+        const promise = this.sendBatch(toSend);
+        this.inflight = this.inflight.then(() => promise);
+        await promise;
+    }
+    /**
+     * Send a batch of spans to the backend. Never throws.
+     */
+    async sendBatch(batch) {
+        try {
+            if (this.config.debug) {
+                console.log(`[spanhq] Flushing ${batch.length} spans to ${this.config.endpoint}`);
+            }
+            const response = await fetch(`${this.config.endpoint}/v1/spans`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "x-api-key": this.config.apiKey,
+                },
+                body: JSON.stringify({ spans: batch }),
+            });
+            if (!response.ok) {
+                const text = await response.text();
+                if (this.config.debug) {
+                    console.error(`[spanhq] Backend returned ${response.status}: ${text}`);
+                }
+            }
+            else if (this.config.debug) {
+                const data = await response.json();
+                console.log(`[spanhq] Successfully sent ${batch.length} spans`, data);
+            }
+        }
+        catch (err) {
+            if (this.config.debug) {
+                console.error("[spanhq] Failed to flush spans:", err);
+            }
+            // Silently drop — never crash the host application
+        }
+    }
+    /**
+     * Shutdown the sender. Clears the timer and flushes remaining spans.
+     * Await this to ensure no spans are lost on process exit.
+     */
+    async shutdown() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        // Flush any remaining spans
+        await this.flush();
+        // Wait for any in-flight requests
+        await this.inflight;
+        if (this.config.debug) {
+            console.log("[spanhq] Sender shut down successfully");
+        }
+    }
+}
+exports.SpanSender = SpanSender;
+//# sourceMappingURL=sender.js.map

package/dist/cjs/sender.js.map

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

package/dist/cjs/tracer.d.ts

@@ -0,0 +1,38 @@
+import type { SpanSender } from "./sender.js";
+import type { SenderConfig } from "@spanhq/shared";
+/** BullMQ Worker type (minimal interface to avoid tight coupling) */
+interface BullMQWorker {
+    name: string;
+    on(event: string, callback: (...args: unknown[]) => void): unknown;
+}
+/** BullMQ Queue type (minimal interface) */
+interface BullMQQueue {
+    name: string;
+    add(name: string, data: Record<string, unknown>, opts?: Record<string, unknown>): Promise<unknown>;
+}
+/**
+ * Instrument a BullMQ Worker to emit spans for every job lifecycle event.
+ *
+ * Events tracked: active, completed, failed, stalled.
+ *
+ * Trace context propagation:
+ *   - On "active": Store trace context in the global activeJobContexts map.
+ *   - During processor: traceQueue.add() reads the context from the map.
+ *   - On "completed"/"failed": Remove context from the map, emit span.
+ *
+ * All errors are caught — this function NEVER crashes the host app.
+ */
+export declare function traceWorker(worker: BullMQWorker, sender: SpanSender, config: SenderConfig): BullMQWorker;
+/**
+ * Instrument a BullMQ Queue to inject trace context into job data.
+ *
+ * When queue.add() is called inside a traced worker processor,
+ * the trace_id and parent span_id are automatically injected into
+ * the child job's data. This enables distributed trace propagation
+ * across job chains (e.g., ingest → transform → validate → publish).
+ *
+ * All errors are caught — this function NEVER crashes the host app.
+ */
+export declare function traceQueue(queue: BullMQQueue, sender: SpanSender, config: SenderConfig): BullMQQueue;
+export {};
+//# sourceMappingURL=tracer.d.ts.map

package/dist/cjs/tracer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracer.d.ts","sourceRoot":"","sources":["../../src/tracer.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAQ,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEzD,qEAAqE;AACrE,UAAU,YAAY;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,OAAO,CAAC;CACpE;AAED,4CAA4C;AAC5C,UAAU,WAAW;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CACD,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB;AAwBD;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,YAAY,GACnB,YAAY,CA+Nd;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,YAAY,GACnB,WAAW,CA6Cb"}