Node.js SDK

Get jobviz-agent running in your Node.js application in under 2 minutes. Monitor BullMQ, bee-queue, or Agenda.js queues with zero boilerplate.

Prerequisites

Node.js 18+ (ESM required)
A Jobviz account — sign up free

1. Install

Install jobviz-agent alongside your queue library of choice.

terminal
 npm install jobviz-agent 

BullMQ 5.0.0+

bee-queue 1.7.0+

Agenda.js 5.0.0+

2. Quick setup

Add two lines to your application entry point. The agent auto-detects your queue library and starts streaming events immediately.

BullMQ

src/index.ts
 import { initJobviz } from 'jobviz-agent';

initJobviz({
  apiKey: process.env.JOBVIZ_API_KEY!,
  queues: ['emails', 'reports'],
  redisUrl: process.env.REDIS_URL ?? 'redis://localhost:6379',
}); 

bee-queue

src/index.ts
 import { initJobviz } from 'jobviz-agent';

initJobviz({
  apiKey: process.env.JOBVIZ_API_KEY!,
  queues: ['emails', 'reports'],
  redisUrl: process.env.REDIS_URL ?? 'redis://localhost:6379',
  // bee-queue is auto-detected, or specify explicitly:
  // provider: 'bee-queue',
}); 

Note: For Agenda.js, MultiProvider, or custom queue systems, see the Examples page.

3. In-job logging

Use jobviz.log() inside your workers to attach structured log entries to each job execution. These appear as a timeline in the dashboard.

src/workers/email.ts
 import { jobviz } from 'jobviz-agent';

// Inside your job worker
async function processEmail(job) {
  jobviz.log(job, 'Fetching template');

  const template = await fetchTemplate(job.data.templateId);
  jobviz.log(job, 'Template fetched', { templateId: job.data.templateId });

  await sendEmail(template, job.data.recipients);
  jobviz.log(job, 'Email sent', { count: job.data.recipients.length });
} 

4. Deployment tracking

Track deployments to correlate failures with code changes. Jobviz overlays deploy markers on your dashboard timeline.

src/index.ts
 import { initJobviz } from 'jobviz-agent';

const agent = initJobviz({
  apiKey: process.env.JOBVIZ_API_KEY!,
  queues: ['emails', 'reports'],
  redisUrl: process.env.REDIS_URL ?? 'redis://localhost:6379',
});

// Track deployments for change correlation
agent.trackDeployment({
  version: '1.4.2',
  commitHash: 'abc123f',
}); 

5. Configuration reference

All available options with their defaults.

src/index.ts
 import { initJobviz } from 'jobviz-agent';

initJobviz({
  // Required
  apiKey: process.env.JOBVIZ_API_KEY!,

  // Queue setup
  queues: ['emails', 'reports', 'notifications'],
  redisUrl: process.env.REDIS_URL ?? 'redis://localhost:6379',

  // Batching
  batchSize: 100,           // Events per batch (default: 100)
  flushInterval: 3000,      // Flush interval in ms (default: 3000)
  maxBufferSize: 10000,     // Max buffered events (default: 10000)

  // Data capture
  captureInput: true,       // Capture job input data (default: true)
  captureStackTraces: true, // Capture error stacks (default: true)
  redactKeys: ['password', 'token', 'secret'],  // Redact sensitive fields

  // Development
  debug: false,             // Log events to console (default: false)
}); 

Option	Type	Default	Description
`apiKey`	`string`	required	Your Jobviz API key
`queues`	`string[]`	-	Queue names to monitor
`redisUrl`	`string`	`redis://localhost:6379`	Redis connection URL
`batchSize`	`number`	`100`	Events per batch
`flushInterval`	`number`	`3000`	Flush interval in ms
`maxBufferSize`	`number`	`10000`	Max buffered events before dropping
`captureInput`	`boolean`	`true`	Capture job input data
`captureStackTraces`	`boolean`	`true`	Capture error stack traces
`redactKeys`	`boolean \| string[]`	`false`	Redact sensitive fields from job data
`debug`	`boolean`	`false`	Log events to console + enable health endpoint

6. Graceful shutdown

Call agent.shutdown() to flush pending events and cleanly disconnect before your process exits.

src/index.ts
 import { initJobviz } from 'jobviz-agent';

const agent = initJobviz({
  apiKey: process.env.JOBVIZ_API_KEY!,
  queues: ['emails'],
  redisUrl: 'redis://localhost:6379',
});

// Flush pending events and disconnect on shutdown
process.on('SIGTERM', async () => {
  await agent.shutdown();
  process.exit(0);
}); 

7. Verify it works

Once your application is running with the agent:

Enable debug mode

Set debug: true in your config. You'll see events logged to console as they're captured.

Check the health endpoint

With debug mode on, visit http://127.0.0.1:9888/agent/health to see the agent status, buffer size, and connection state.

Open your dashboard

Go to https://app.jobviz.dev — you should see your queues and jobs appearing in real-time within seconds.

Need help getting set up?

Open an issue on GitHub or ask in our Discord community — we're happy to help.

Get started free