@nodezor/job-watch

Zero-overhead real-time background job execution, metrics, and stalled task observability monitor.

The Problem

Background queue workers (BullMQ, Redis, Celery, RabbitMQ) silently stall, duplicate jobs, or crash due to memory leaks and unhandled promise rejections without alerting engineering teams. Developers lack lightweight, zero-overhead observability to detect stuck background jobs, memory spikes, and queue backpressure in real time before users notice delayed background processes.

Features

• ⏱️ Job Lifecycle Tracking: Tracks execution start, completion, failure, and execution duration.
• 🚨 Stalled Job Detection: Automatically flags tasks exceeding custom execution thresholds.
• 📊 Real-Time Metrics: Calculates activeCount, stalledCount, totalProcessed, and avgDurationMs.
• ⚡ Zero External Dependencies: Pure TypeScript native monitor.

Installation

# pnpm
pnpm add @nodezor/job-watch

# npm
npm install @nodezor/job-watch

# yarn
yarn add @nodezor/job-watch

Quick Start / Usage Example

import { createJobWatcher } from '@nodezor/job-watch';

// Monitor jobs with a 30s stalled threshold
const watcher = createJobWatcher(30000);

async function runWorkerTask(jobId: string) {
  watcher.startJob(jobId, 'process-payment');

  try {
    // Process background task
    await new Promise((r) => setTimeout(r, 500));
    watcher.completeJob(jobId);
  } catch (err) {
    watcher.failJob(jobId, err as Error);
  }

  // Get real-time metrics
  console.log(watcher.getMetrics());
}

API Reference

createJobWatcher(stalledTimeoutMs?: number)

Creates a background job watcher monitor.

Methods

• startJob(id: string, name: string): TrackedJob
• completeJob(id: string): TrackedJob | undefined
• failJob(id: string, error: string | Error): TrackedJob | undefined
• getStalledJobs(): TrackedJob[]
• getMetrics(): JobMetrics
• clear(): void

License

MIT © PRX2112