SKILL.md
GitHubNode.js diagnostics (v24+)
| Feature | Versions | Stability | Flag |
|---|---|---|---|
TracingChannel |
v19.9.0, v18.19.0 (Stable in v26.8.0) | 2 | — |
boundedChannel, channel.withStoreScope |
v26.1.0 (not v24) | 1 | — |
als.withScope / RunScope |
v25.9.0, v24.20.0 | 1 | — |
AsyncLocalStorage({ defaultValue, name }) |
v24.0.0 | 2 | — |
v8.startCpuProfile (sync) |
v25.0.0, v24.12.0 | — | — |
v8.startHeapProfile (sync) |
v26.1.0 (not v24) | 1 | — |
v8.setHeapProfileNearHeapLimit |
v26.9.0 (not v24) | 1 | — |
worker.startCpuProfile / .startHeapProfile |
v24.8.0 / v24.9.0, v22.20.0 | 2 | — |
node inspect --probe |
v26.1.0, v24.16.0; JSON v2 + --max-hit v26.4.0, v24.19.0; --cond v26.6.0, v24.20.0 |
1 | — |
inspector DOMStorage.* |
v25.5.0, v24.16.0 | 1.1 | --experimental-storage-inspection |
| Built-in channels | see rules/diagnostics-channel.md | 1 | — |
Experimental API. Before relying on these details, run the
node-experimental-checkskill's probe (ornode --versionplus a feature-detect one-liner) and check the docs for the installed version:https://nodejs.org/docs/<version>/api/<module>.html. If the installed version disagrees with this skill, the installed version wins.
Instrument a library (APM)
import { tracingChannel } from 'node:diagnostics_channel';
const ch = tracingChannel('mylib.db.query'); // once, at module top level
export function query(sql) {
if (!ch.hasSubscribers) return run(sql);
return ch.tracePromise(run, { sql }, null, sql);
}
// APM side: ch.start.bindStore(als, (ctx) => span(ctx)); ch.subscribe({...})
Scoped context with using
{ using _ = als.withScope(store); syncWork(); } // restored on exit/throw
{ using _ = ch.withStoreScope(msg); } // enter bound stores + publish
{ using _ = bounded.withScope(ctx); } // tracing:<name>:start ... end
Profile a section
const h = v8.startCpuProfile({ sampleInterval: 1 }); hot();
writeFileSync('x.cpuprofile', h.stop()); // JSON string; `using` discards
// worker.startCpuProfile() is async: await handle.stop()
Logpoint without editing code
node inspect --json --probe src/app.js:42 --expr 'user.id' --cond 'user.admin' --max-hit 5 app.js
Pitfalls
- A
usingscope opened in anasyncfunction before the firstawaitleaks into the caller; useals.run(). boundedChannel.run()sets neitherctx.resultnorctx.error. A bound store makeshasSubscriberstrue.tracePromise(v26+) returns thenables as-is, non-thenables with a warning; v24 wraps both in a Promise.defaultValueapplies only when no store was entered;run(undefined)/exit()giveundefined.- One heap profile at a time.
setHeapProfileNearHeapLimitneeds an activestartHeapProfile(). - Before v24.20,
--condis rejected with a misleading "Use --" usage error. v8.queryObjectsis documented Stable but still warnsExperimentalWarning.
Don't
- Don't monkey-patch modules or use
async_hooks.createHookfor tracing: use channels +bindStore. - Don't use
enterWith()for block scope (withScope()) orconsole.logedits to inspect values (--probe).
Reference
- rules/diagnostics-channel.md: bounded channels, scopes, tracePromise history, built-in channel names.
- rules/async-context.md:
withScope/RunScope, constructor options. - rules/profiling.md: handle options, output formats, near-heap-limit, workers,
queryObjects. - rules/probe-mode.md:
--probesyntax, JSON v2 schema, terminal events, exit codes. - rules/inspector.md: Network/DOMStorage CDP events and flags.