Node.js

The TraceStax Node.js SDK supports BullMQ, Bull (legacy), AWS SQS, and Temporal. One package — import only what you use.

Requirements

• Node.js 18+
• One of: BullMQ 5.x, Bull 3/4.x, @aws-sdk/client-sqs, @temporalio/worker

Installation

npm

npm install @tracestax/node

pnpm

pnpm add @tracestax/node

yarn

yarn add @tracestax/node

---

Setup

BullMQ

import { Queue, Worker } from "bullmq";
import { configure } from "@tracestax/node";

const queue = new Queue("orders", { connection });
const worker = new Worker("orders", async (job) => {
  // your job handler
}, { connection });

configure(queue, { apiKey: "ts_live_xxxxxxxxxxxx" }, worker);

configure() subscribes to BullMQ queue and worker events — no changes to your job handler needed.

Multiple queues:

import { TraceStaxMonitor } from "@tracestax/node";

const monitor = new TraceStaxMonitor({ apiKey: "ts_live_xxxxxxxxxxxx" });
monitor.monitorQueue(ordersQueue);
monitor.monitorWorker(ordersQueue, ordersWorker);
monitor.monitorQueue(emailQueue);
monitor.monitorWorker(emailQueue, emailWorker);

Bull (legacy)

import Bull from "bull";
import { TraceStaxBullMonitor } from "@tracestax/node";

const queue = new Bull("orders", { redis: { host: "localhost" } });

const monitor = new TraceStaxBullMonitor({ apiKey: "ts_live_xxxxxxxxxxxx" });
monitor.monitor(queue);
monitor.startHeartbeat();
monitor.startSnapshots();

AWS SQS

import { TraceStaxSQSConsumer } from "@tracestax/node";

const consumer = new TraceStaxSQSConsumer({
  apiKey: "ts_live_xxxxxxxxxxxx",
  queueName: "orders",
  taskName: "ProcessOrder",   // optional — shown in dashboard
});

consumer.startHeartbeat();

// In your message handler (works with sqs-consumer, @aws-sdk, etc):
await consumer.wrapHandler(message, () => processOrder(message));

wrapHandler reports started/succeeded/failed events around each message.

Temporal

import { Worker } from "@temporalio/worker";
import { TraceStaxTemporalInterceptor } from "@tracestax/node";

const worker = await Worker.create({
  taskQueue: "orders",
  interceptors: {
    activityInbound: [() => new TraceStaxTemporalInterceptor({
      apiKey: "ts_live_xxxxxxxxxxxx",
      taskQueue: "orders",
    })],
  },
});

await worker.run();

The interceptor wraps every activity execution — no per-activity changes needed.

---

Configuration

All adapters accept the same core options:

Option	Env var	Default	Description
apiKey	TRACESTAX_API_KEY	—	Required
endpoint	TRACESTAX_INGEST_URL	https://ingest.tracestax.com	Custom ingest endpoint
enabled	TRACESTAX_ENABLED	true	Set to false to disable
dryRun	TRACESTAX_DRY_RUN	false	Log events instead of sending
flushInterval	—	5000	ms between background flushes
maxBatchSize	—	100	Max events per HTTP request

---

Testing

// jest.setup.ts / vitest.setup.ts
process.env.TRACESTAX_ENABLED = "false";

Or pass enabled: false when constructing any monitor/consumer class.

---

Troubleshooting

Events not appearing

• Confirm TRACESTAX_API_KEY is set in your worker process environment
• Check your Node process can reach ingest.tracestax.com:443
• The SDK logs a [tracestax] warn line if ingest calls fail — check your worker output

TypeScript: types not resolving

Ensure moduleResolution is set to bundler or node16 in your tsconfig.json. The package ships ESM with .js extensions on all imports.