Diagnostics: channels, async context, and profiles

diagnostics_channel: instrument without monkey-patching

The old way to add tracing or metrics to a library was to monkey-patch its prototype — wrap http.request, swap a method on the driver — which breaks silently on the next upgrade and couples your observability code to internals. node:diagnostics_channel replaces that with a built-in, in-process pub/sub bus. A producer publishes named messages; subscribers receive them synchronously. Core, undici, and http already expose channels, so you instrument them without touching their code.

The performance property that makes it safe to leave in hot paths is hasSubscribers. A publish with no listeners is essentially free, so a library can guard the cost of building the message and pay nothing when nobody is watching.

import diagnostics_channel from "node:diagnostics_channel";

const channel = diagnostics_channel.channel("app:db:query");

// producer (in the DB wrapper) — pay to build the payload only if observed
function runQuery(sql, params) {
  if (channel.hasSubscribers) {
    channel.publish({ sql, params, startedAt: performance.now() });
  }
  return driver.query(sql, params);
}

// subscriber (in your tracing setup) — attach with zero coupling to the wrapper
channel.subscribe((message) => {
  metrics.increment("db.query", { sql: message.sql });
});

The tradeoff versus an event emitter or a wrapper: channels are synchronous and unordered across producers, so a subscriber must be fast and must not throw into the producer’s call. The win is decoupling — you can subscribe to undici’s built-in request channels for distributed tracing without a single line of patching, and the instrumentation survives library upgrades.

AsyncLocalStorage: request context that survives await

The hook’s bug — a traceId dropped two layers down — is the canonical case for AsyncLocalStorage (from node:async_hooks). It gives you a store that is scoped to an asynchronous call tree: you call als.run(store, fn) once at the request boundary, and any code reached from fn — across await, setTimeout, promise chains, library callbacks — can call als.getStore() and read the same store. You never pass the id as an argument again.

import { AsyncLocalStorage } from "node:async_hooks";

const als = new AsyncLocalStorage();

// at the boundary: open a context for this request
app.use((req, res, next) => {
  const store = { traceId: req.headers["x-trace-id"] ?? crypto.randomUUID() };
  als.run(store, () => next());
});

// anywhere downstream, however deep, with no plumbing:
function log(msg) {
  const { traceId } = als.getStore() ?? {};
  logger.info({ traceId, msg });
}

Contrast this with a module-level variable: a global is shared across all concurrent requests, so under load request B overwrites request A’s id and your traces interleave into nonsense. AsyncLocalStorage keeps a separate store per async context, which is exactly the isolation a server needs. The cost is real but bounded — it rides on async_hooks, so there is per-async-operation overhead; keep the store small (ids and flags, not large objects) and you pay single-digit-percent in typical request handlers.

Signals and on-demand profiling

When a container misses a deployment rollout or a process leaks memory in staging, you need to act on a live process without restarting it — and that’s exactly what signals and on-demand profiling give you. A long-running process talks to its operator through signals. Orchestrators send SIGTERM to ask for a graceful shutdown — you get a window to stop accepting new work, drain in-flight requests, close DB pools, and exit; if you ignore it, Kubernetes follows with SIGKILL after the grace period (30s by default) and cuts you off mid-request. SIGINT is Ctrl-C in a terminal. SIGUSR1 is special: Node opens the inspector on receipt by default, so you can attach a debugger to a live process without a restart.

// graceful shutdown: stop accepting → drain → close deps → exit
process.on("SIGTERM", async () => {
  server.close();             // stop accepting new connections
  await drainInFlight();      // let active requests finish
  await db.end();             // close pools / flush
  process.exit(0);
});

When you need to see why a process is slow or leaking, profile it on demand. Launch with --cpu-prof (or --heap-prof) and Node writes a .cpuprofile (or .heapprofile) on exit that you open in Chrome DevTools’ Performance/Memory panel; --diagnostic-dir controls where the files land. For a hard crash, enable core dumps (ulimit -c unlimited, and --abort-on-uncaught-exception to dump on an uncaught throw) and inspect the dump post-mortem with llnode/lldb. The throughline: none of these requires editing your application code, so they’re safe to add to a misbehaving production process.