how to view memory usage per worker instance?

[arthurvanl]

I want to know if it uses more than the maxMemory and how much each worker uses. I am using embedded mode

I do want to switch to server mode but I have not used it yet and I just got a production setup ready.

[egeominotti]

Good question. Right now there's no built-in per-worker memory monitoring — this is a gap I'm aware of.

What's available today

Process-wide memory (embedded mode)

# Health endpoint shows total process memory
curl http://localhost:6790/health
# Returns: { memory: { heapUsed: 45.2, heapTotal: 67.1, rss: 120.5 } } (in MB)

# Detailed heap breakdown
curl http://localhost:6790/heapstats

But this shows the entire process memory, not per-worker.

SandboxedWorker stats

const stats = worker.getStats();
// { total: 3, busy: 2, idle: 1, restarts: 0 }

This gives you thread counts and restart info, but not memory usage.

maxMemory behavior

The maxMemory option controls Bun's smol mode:

• maxMemory <= 64: enables smol mode (reduced heap overhead)
• maxMemory > 64: standard mode (default: 256 MB)

Bun's Worker threads have their own heap, but bunqueue doesn't actively poll their memory. If a worker exceeds available memory, the OS kills it and bunqueue's handleCrash() auto-restarts it (up to maxRestarts times).

Workaround: monitor from inside the processor

You can track memory from within your processor file and log it:

// In your processor file
export default async (job) => {
  const before = process.memoryUsage();
  console.log(`[${job.id}] Memory before: ${(before.heapUsed / 1024 / 1024).toFixed(1)}MB`);

  const result = await doWork(job.data);

  const after = process.memoryUsage();
  console.log(`[${job.id}] Memory after: ${(after.heapUsed / 1024 / 1024).toFixed(1)}MB`);

  // You could also store it in the result
  return { ...result, _memoryMB: (after.heapUsed / 1024 / 1024).toFixed(1) };
};

Workaround: OS-level monitoring

Since each SandboxedWorker thread runs as a visible thread in the process, you can monitor with system tools:

# Watch all bun threads
watch -n 1 "ps -eo pid,tid,rss,comm | grep bun"

# Or use htop with thread view (press H to toggle threads)
htop

Coming soon

I'll add a getMemoryUsage() method to SandboxedWorker that queries each worker thread's heap via IPC. Something like:

// Future API
const memoryStats = await worker.getMemoryUsage();
// [
//   { index: 0, heapUsed: 45.2, heapTotal: 67.1, rss: 89.0 },
//   { index: 1, heapUsed: 32.1, heapTotal: 67.1, rss: 75.0 },
//   { index: 2, heapUsed: 51.8, heapTotal: 67.1, rss: 92.0 },
// ]

For now, the processor-level process.memoryUsage() workaround is the most reliable way to track per-worker memory. Let me know how your production setup is going!