dial9 Analysis Toolkit

This skill provides the JavaScript modules for working with dial9 traces programmatically. The other dial9 skills locate these modules by content rather than by this directory's name, so the directory can be installed under any name as long as scripts/ stays intact.

What traces capture

dial9 traces capture the internal behavior of a Tokio async runtime:

• Poll events: Every time a worker thread polls a task future (start/end timestamps, task ID, spawn location)
• Worker lifecycle: Park/unpark events with CPU time and kernel scheduling wait
• Queue depth: Periodic samples of the global injection queue
• Task lifecycle: Spawn and terminate events with spawn location
• Wake events: Which task woke which other task, and on which worker
• CPU samples: Periodic stack traces from perf/eBPF, attached to the poll they occurred in
• Scheduling samples: Stack traces captured when the kernel deschedules a worker thread (shows blocking calls)
• Clock sync: Monotonic-to-wall-clock anchors for correlating with external logs
• Span events: Enter/exit events from tracing spans (#[instrument]), showing what happened inside each poll with field values and nesting

Quick start

node scripts/analyze.js <trace.bin or directory>  # full diagnostic report
node scripts/analyze.js traces/ --sample 50       # quick overview of large directories
node scripts/analyze.js trace.bin --force          # ignore cached results

Modules

Default workflow

1. Always run analyzeTraces(path) first for trace diagnosis. This automatically runs setup diagnostics first.
2. If setup diagnostics report issues (missing frame pointers, missing wake events, missing debug symbols), help the user fix those before diving into performance analysis.
3. Base initial findings on the aggregate result: long polls, worker spans, scheduling delays, CPU/off-CPU groups, queue depth, task lifecycle counts, and span summaries.
4. Then use parseTrace() or lower-level helpers only to confirm assumptions, inspect raw events, or follow a specific task/wake/span chronology.
5. When the aggregate pass flags a specific moment — a long poll, a queue spike, a latency outlier — stop averaging and zoom in: use dial9-zoom-window to reconstruct that instant, and dial9-diagnose-long-poll to root-cause why a poll was long (on-CPU work vs off-CPU wait, and who held it up even when no scheduling samples were captured).
6. When you report findings to a person, link each one to its sample in the viewer (the poll, task or span behind it) rather than describing where to look. "Linking analysis findings" in references/viewer-urls.md says which link fits which finding and how to build it.

Setup diagnostic

The setup diagnostic (diagnose_setup.js) runs automatically as part of analyze.js and checks for common configuration issues:

Run standalone:

node scripts/diagnose_setup.js <trace.bin or directory>

const { analyzeTraces } = require('./scripts/analyze.js');
const result = await analyzeTraces('/path/to/traces/');
// result.longPolls, result.workerSpans, result.schedDelayHist, result.cpuGroups, result.spanStats

analyzeTraces works on a single file or a directory. It returns a single aggregated result object with everything you need for diagnosis. See the dial9-trace-analysis skill for the full return schema.

After the aggregate pass, use the low-level parser to confirm assumptions or inspect raw details that the aggregate result points at, such as specific tasks, custom filters, wake chains, or per-file chronology:

const { parseTrace } = require('./scripts/trace_parser.js');
const trace = await parseTrace('/path/to/trace.bin');  // single file
// or iterate a directory:
for await (const trace of parseTrace('/path/to/traces/')) { ... }