@js-ak/watchdog

Native watchdog for Node.js that detects event loop freezes with near-zero overhead.

Status: native event-loop freeze detector (N-API). Prebuilds ship for major platforms on release.

Install

npm install @js-ak/watchdog

Published builds include ABI-tagged prebuilds for win32-x64, linux-x64, linux-arm64, darwin-arm64, and darwin-x64 (Node 22 / 24 / 26). npm install loads the matching ABI — no C++ toolchain needed on those targets.

captureStack needs a matching NODE_MODULE_VERSION prebuild (same rule Node uses for native addons). All patches within a shipped major share one ABI; an unsupported major disables capture with a warning until that ABI is published.

Linux: glibc vs musl

On Linux the native addon must match the C library of the runtime, not just linux-x64 / linux-arm64:

| Runtime | libc | Prebuild tag | Typical images / hosts | | --- | --- | --- | --- | | Debian, Ubuntu, RHEL, most cloud VMs | glibc | *.glibc.node | node:*-bookworm, node:*-slim, GitHub ubuntu-* | | Alpine Linux | musl | *.musl.node | node:*-alpine |

npm install (via node-gyp-build) picks the tagged file automatically — you do not choose it by hand; your OS / Docker base image decides which one you need.

Why it matters: a glibc .node can sometimes dlopen on Alpine and then SIGSEGV later (exit 139), especially with captureStack / V8 RequestInterrupt. That is why Linux prebuilds are libc-tagged and why Alpine gets its own musl builds.

glibc builds are produced on Ubuntu 22.04 (broader libstdc++ reach for Debian bookworm / slim). musl builds are produced on Alpine.

From a git checkout (no prebuilds yet):

npm install
npm run rebuild

Requires a C++ toolchain (node-gyp / Visual Studio Build Tools on Windows).

Quick start

const watchdog = require("@js-ak/watchdog");

watchdog.on("freeze", (event) => {
  // freeze_started | freeze_stack (heartbeat is native-log only)
  console.log(event.event, event.duration_ms);
});

watchdog.on("recovered", (event) => {
  console.log("recovered after", event.duration_ms, "ms");
});

const started = watchdog.start({
  freezeThresholdMs: 1000,
  heartbeatMs: 1000,
  logTarget: "stderr", // stderr | file | both
  logFile: "./watchdog.log",
  source: "payments-api", // optional app label for monitoring
});

if (!started) {
  console.error("watchdog already running");
}

// later
watchdog.stop();

Native side writes JSON Lines from the monitor thread, so freeze logs (including freeze_heartbeat) appear even while the event loop is blocked. JS only receives freeze_started / freeze_stack / freeze_recovered (queued until the loop can run again).

API

| Method | Description | | --- | --- | | start(config?) | Start monitoring. Returns false if already running. | | stop() | Stop monitoring (idempotent). | | isRunning() | Whether the native monitor thread is active. | | getConfig() | Active config (logFile absolute), or null when stopped. | | on(event, listener) | Subscribe (freeze, recovered, event). | | once(event, listener) | One-shot subscription. | | off(event, listener) | Unsubscribe. | | removeAllListeners(event?) | Clear listeners. | | DEFAULTS | Frozen default config values. |

Config

| Key | Default | Notes | | --- | --- | --- | | freezeThresholdMs | 1000 | 1..3600000 | | heartbeatMs | 1000 | 1..3600000; native log cadence while frozen (not bridged to JS) | | logTarget | "stderr" | "stderr" | "file" | "both" | | logFile | "./watchdog.log" | used when target is file/both; getConfig() returns the resolved absolute path | | logMaxBytes | 10485760 (10 MiB) | soft size cap for the active log file; on overflow rename to <logFile>.1 (one backup) and reopen; 0 disables; 0..1073741824 | | source | omit | optional app/service label (max 256 chars); included on native JSON Lines and JS events when set. Library identity is always lib: "js-ak/watchdog" | | captureStack | false | opt-in JS stack capture (unstable). true or { mode, on, maxFrames, maxSamples } — see below |

Local demo of size rotation (repo checkout only; not shipped in the npm tarball):

node examples/log-max-bytes.js

captureStack (experimental)

Two modes:

interrupt (default via true) — V8 RequestInterrupt snapshots. Works best for JS busy-loops; sync I/O / native blocks may leave stack_status: "unavailable". Under heavy parallel async work, a sample often lands in processTicksAndRejections only. Prefer on: "both" so longer freezes re-sample; on recovered, stack is the most frequent shape and stack_samples lists counts. Interrupt stacks show the JS line at the next safepoint — often the statement after a long native call (e.g. JSON.parse).

profile — V8 CpuProfiler over the stall. Arms when lag ≥ freezeThresholdMs / 2, stops on recover (or discards if lag drops without freezing). On recovered, stack_mode: "profile" and stack_samples are top hot paths by hit count (no live freeze_stack spam). Better attribution for CPU-bound work that yields to safepoints while profiling; a single unbroken native call that never yields before recover may still produce a thin/unavailable profile. Adds sampling overhead while armed — keep opt-in.

Stack/profile capture uses V8 C++ APIs. Release CI ships one ABI-tagged binary per supported Node major; node-gyp-build picks the match at install/load time.

| Value | Meaning | | --- | --- | | false / omit | disabled (default) | | true | { mode: "interrupt", on: "both", maxFrames: 50, maxSamples: 8 } | | { mode, on, maxFrames, maxSamples } | mode: "interrupt" | "profile"; on (interrupt only): "started" | "heartbeat" | "both"; maxFrames: 1..256; maxSamples: 1..32 |

When enabled, native logs / JS events may include:

• freeze_stack — interrupt mode live sample (channel: "freeze"); rss_mb / cpu_pct copied from the latest lifecycle event
• on freeze_recovered: stack_status, stack_mode ("interrupt" | "profile"), and stack when status is "ok"; stack_samples ([{ count, stack }, ...], count-desc) when samples exist
• frames often contain absolute paths — keep logs access-controlled when capture is on

Event payload

{
  ts: "2026-07-22T13:18:38.696Z", // JS delivery time; native log lines use sample time
  lib: "js-ak/watchdog", // fixed library identity
  // source: "payments-api", // only when start({ source }) was set
  pid: 28440,
  event: "freeze_started", // JS: freeze_started | freeze_recovered | freeze_stack
                           // native logs also include freeze_heartbeat
  freeze_id: 1,
  duration_ms: 170,
  threshold_ms: 1000,
  heartbeat_ms: 1000,
  sequence: 0,
  rss_mb: 44.15,
  cpu_pct: 79.92, // -1 if unavailable
  // only when captureStack is enabled (on freeze_stack / freeze_recovered):
  // stack_status: "ok" | "unavailable",
  // stack_mode: "interrupt" | "profile",
  // stack: ["at busyWait (test.js:12:5)", ...], // omitted when unavailable
  // on freeze_recovered when samples exist:
  // stack_samples: [{ count: 3, stack: ["at busyWait ..."] }, ...],
}

Troubleshooting

| Symptom | Likely cause | What to do | | --- | --- | --- | | Cannot find module ... watchdog.node / load error on install | No matching prebuild and no local toolchain | Install on a supported target, or install build tools and npm rebuild | | No JS events during a freeze | Event loop is blocked | Expected: JS listeners fire after recovery; use native JSON logs for in-freeze signal | | start() returns false | Already running | Call stop() first, or check isRunning() | | Config throws TypeError / RangeError | Invalid options | See config table; values must be plain object + ranges | | Log file missing | Unwritable path / missing directories | Logger fails open quietly; stderr/both still work; create parent dirs if you need a file | | High cpu_pct during freeze | Busy-loop / CPU-bound block | Expected for sync CPU spins; use with RSS/duration context | | No freeze_stack / stack_status: "unavailable" | Sync I/O, native addon, or interrupt never reached a V8 safepoint | Expected for non-JS blocks; check native logs around recovery; try on: "both" or mode: "profile" | | stack_status: "ok" but only processTicksAndRejections / task_queues | Interrupt landed in the promise microtask runner under async load | Expected for many concurrent awaits; try mode: "profile"; use duration/RSS/CPU; raise freezeThresholdMs if short stalls are noise | | Interrupt stack line is after JSON.parse / other native | Interrupt runs at the next safepoint after native returns | Expected; use mode: "profile" for hit-count attribution when the profiler was armed in time | | Profile unavailable / empty on short native-only stalls | Profiler start interrupt could not run until after the block | Expected for one unbroken native call; lengthen work or accept interrupt function-level hint | | captureStack off + ABI warning | No prebuild for this Node major / wrong binary loaded | Use Node 22/24/26, or upgrade @js-ak/watchdog once that ABI is published | | npm ci in Debian slim tries to compile / needs Python | Linux prebuild needs newer libstdc++ than the image, so load fails and install falls back to node-gyp | Use a newer base image, or upgrade @js-ak/watchdog (Ubuntu 22.04 prebuilds) | | Container exit 139 / SIGSEGV (often with captureStack) on Alpine | glibc Linux prebuild loaded on musl | Use a release with libc-tagged + musl prebuilds; or switch to a glibc image (node:*-bookworm-slim); or rebuild from source on Alpine after removing node_modules/@js-ak/watchdog/prebuilds |

Compatibility

See COMPATIBILITY.md for the v1 stability contract.

Docs

• ARCHITECTURE.md
• COMPATIBILITY.md