dial9-html-report

name	dial9-html-report
description	Compile dial9 trace analysis insights into a polished HTML report folder with embedded flamegraphs, timeline strips, and viewer deep-links. Use when you have findings from trace analysis and need to deliver them as something a human can open in a browser.

Building HTML Reports from Trace Insights

When to use this skill

You have already analyzed a dial9 trace (using the dial9-toolkit and dial9-trace-analysis skills) and have a set of findings. Now you need to deliver those findings as an HTML report — a folder a human can open in their browser via a tiny local server.

Viewing the report (important)

Reports are served, not opened directly. Browsers block fetch() over file://, so flamegraph iframes and viewer deep-links will fail if the user opens report.html directly from disk. Tell the user (and yourself, when verifying):

# from the dial9 CLI (recommended — also enables viewer deep-links)
dial9 report serve path/to/report-folder
# → http://localhost:8000/report.html

# or any static-file server
python3 -m http.server -d path/to/report-folder 8000

The folder is portable — zip it, attach it to a PR, drop it in Slack. The recipient just needs to serve it locally too.

The shape of a report

A report is a folder, not a single file:

report/
├── report.html
├── viewer.html              # built canonical viewer entry
├── flamegraph.html          # built canonical flamegraph entry
├── flamegraph.css
├── assets/                  # Vite bundles used by both entries
├── decode.js
├── trace_parser.js
├── trace_analysis.js
├── flamegraph.js             # root JS files support the standalone recipes
├── traces/
│   └── full.bin             # may also have sliced files
└── flamegraphs/
    └── finding-1.html       # standalone flamegraph (one per finding)

Build the UI, copy the canonical entries with their bundles, then copy the shared helpers used by the standalone flamegraph recipes below. The source HTML entries are not portable by themselves because they import TypeScript that Vite must bundle first.

(cd dial9-viewer/ui && npm ci && npm run build)
cp dial9-viewer/ui/dist/{viewer,flamegraph}.html report/
cp dial9-viewer/ui/dist/flamegraph.css report/
mkdir -p report/assets
cp -R dial9-viewer/ui/dist/assets/. report/assets/
cp dial9-viewer/ui/{decode,trace_parser,trace_analysis,flamegraph}.js report/

Slice traces into traces/ so the report is portable and small.

Writing the report HTML

Write HTML directly — no JSON, no markdown intermediate. Use this style block:

<style>
:root { --bg: #0d1117; --surface: #161b22; --border: #30363d; --text: #e6edf3; --muted: #8b949e; --accent: #58a6ff; --critical: #f85149; --warning: #d29922; --info: #58a6ff; }
* { margin: 0; padding: 0; box-sizing: border-box; }
body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif; background: var(--bg); color: var(--text); line-height: 1.6; padding: 2rem; max-width: 1100px; margin: 0 auto; }
h1 { font-size: 1.8rem; margin-bottom: 0.5rem; }
h2 { font-size: 1.4rem; margin: 2rem 0 1rem; border-bottom:  solid (--border); : ; }
 { : (--muted); : ; : ; }
 { : (--surface); :  solid (--border); : ; : ; : ; }
 { : flex; : center; : ; : ; }
 { : ; : ; : uppercase; :  ; : ; }
 { : (--critical); : ; }
 { : (--warning); : ; }
 { : (--info); : ; }
 { : , monospace; : ; : ; :  ; : ; }
 { : (--accent); : none; }
 { : underline; }

Insight card structure

<div class="finding">
  <div class="finding-header">
    <span class="severity severity-critical">Critical</span>
    <h3>Headline describing the problem</h3>
  </div>
  <p>Prose explanation of what was observed, with <span class="code-ref">source.rs:42</span> references.</p>
  <p><strong>Fix:</strong> Actionable recommendation.</p>
  <!-- Optional: standalone flamegraph for precise filtering -->
  <iframe src="flamegraphs/finding-1.html" width="100%" height="320" style="border:0"></iframe>
  <!-- Optional: link to explore the time window in the full viewer -->
  <p class="viewer-link"><a href= =>Open this 150ms window in the full viewer →

HTML escaping: Always escape <, >, &, and " in any agent-generated text inserted into HTML attributes or element content.

Linking to the full viewer

The report folder includes the built viewer.html and its assets/. This lets you deep-link into the full interactive viewer for any time window, served from the same folder.

Canonical link template

<a href="viewer.html?trace=traces/full.bin&amp;start=<absolute_ns>&amp;end=<absolute_ns>"
   target="_blank">Open in dial9 viewer</a>

The trace path is relative — it resolves from the same origin because viewer.html and traces/ live in the same served folder.

Computing start/end values

start and end are ABSOLUTE monotonic nanoseconds — the same values found in event.ts from TraceParser.parseTrace(). They are NOT relative offsets from trace start.

To compute an absolute timestamp from a relative offset:

// trace.minTs is the earliest timestamp in the trace, as a Number (ns).
// All trace timestamps (event.timestamp, poll.start/end, cpuSample.timestamp)
// are Numbers, NOT BigInts. Use plain arithmetic, no `n` suffix.
const minTs = trace.minTs; // e.g., 150439548276
// "3.9 seconds into the trace" → absolute ns:
const start = minTs + 3_900_000_000; // 154339548276
const end   = minTs + 4_050_000_000; // 154489548276

Foot-gun: do NOT use BigInt suffix (3_900_000_000n) when adding to trace.minTs. Number + BigInt throws at runtime, producing a silent blank flamegraph because the script aborts before rendering. Same goes for filter predicates: comparing cpuSample.timestamp to poll.start and similar — keep both as plain Numbers.

Available viewer URL params

These are part of the viewer's stability-promised URL contract (dial9-viewer/ui/README.md, section "URL contract (stable deep-link API)"): old params stay valid forever, evolution is additive-only, so links baked into a report keep resolving.

Param	Description
trace	Relative path or URL to a .bin trace file (fetched via fetch()); repeatable, N values parse as one trace
start	Visible viewport start (absolute monotonic ns)
end	Visible viewport end (absolute monotonic ns)
data-start	Optional parse-time lower bound (absolute monotonic ns)
data-end	Optional parse-time upper bound (absolute monotonic ns)
task	Selected task id (integer or 0x hex)
svc	Service name (display label)
host	Host name (display label)
from	Human-readable wall-clock start (display only)
to	Human-readable wall-clock end (display only)
segs	Segment COUNT as an integer string (display only) - NOT a list of segment keys

?worker= and ?source= do NOT exist. Do not invent them — they will be silently ignored. The viewer supports additional selection and analysis fields; use the authoritative URL contract instead of guessing their names.

Deep-linking the standalone flamegraph page

flamegraph.html (also copied into the report folder) honors the same trace/start/end/svc/host/segs/from/to params, plus a pre-zoom: worker-zoom (and offworker-zoom) carry a TAB-joined (%09-encoded) frame-name path from root to the target subtree, exactly what the flamegraph page writes to the URL when a user zooms. The reliable way to produce one is to zoom in the flamegraph and copy the URL rather than hand-assembling the path; zoom restore requires the same start/end window the zoomed view had (or none).

<a href="flamegraph.html?trace=traces/full.bin&amp;start=150439548276&amp;end=150439698276"
   target="_blank">CPU flamegraph for this window</a>

The same zoom state can travel in the URL hash as #v=1&fg.w=<path>; emit the stable worker-zoom query form in reports for compatibility with existing links.

Limitation

The viewer needs the trace served via HTTP. Use dial9 report serve <report-folder> (or any static server). file:// URLs will not work.

Worked example: viewer link in an insight card

<div class="finding">
  <div class="finding-header">
    <span class="severity severity-warning">Warning</span>
    <h3>Connection burst saturates workers (23ms scheduling delay)</h3>
  </div>
  <p>~80 tasks woken simultaneously at t≈3.9s cause wake-to-poll delays up to 23ms.</p>
  <p><strong>Fix:</strong> Increase worker count or add connection backpressure.</p>
  <p class="viewer-link"><a href="viewer.html?trace=traces/full.bin&amp;start=150439548276&amp;end=150439698276" target="_blank">Open this 150ms burst window in the full viewer →</a></p>
</div>

Flamegraphs: precise filtering via standalone HTML

When to use this vs. a viewer deep-link

Use a viewer deep-link when you want the user to explore the full interactive timeline + flamegraph for a time window.

Use a standalone HTML file when you need a precisely-filtered flamegraph embedded directly in the report:

• A specific task's CPU profile
• Only polls exceeding a duration threshold
• Off-CPU (scheduling) samples only
• Leaf-frame search (e.g., "where does load_native_certs appear?")
• Multi-trace union flamegraph
• Any combination of the above

Skeleton (copy and fill in your filter)

Place standalone flamegraph files in report/flamegraphs/<name>.html. They load the same JS modules and give you full control over filtering.

<!DOCTYPE html>
<html><head><link rel="stylesheet" href="../flamegraph.css"></head><body>
  <div id="fg" style="height:100vh"></div>
  <script src="../decode.js"></script>
  <script src="../trace_parser.js"></script>
  <script src="../trace_analysis.js"></script>
  <script src="../flamegraph.js"></script>
  <script>(async () => {
    const buf = await fetch('../traces/full.bin').then(r => r.arrayBuffer());
    const trace = await .(buf);
     workerIds = [... (trace..( e. != ).( e.))];
     ws = .(trace., workerIds, trace., trace.);
    .(trace., ws.);

    
     samples = trace..( s. === );

     el = .();
     (samples. === ) {
       total = trace..;
       onCpu = trace..( s. === ).;
       offCpu = trace..( s. === ).;
       locs =  ();
      trace..( {  (s.) locs.(s., (locs.(s.)||)+); });
       top3 = [...locs.()].( b[]-a[]).(,).( l.().()++c+).();
      el. = +total++onCpu++offCpu++top3+;
      ;
    }
    .(el,  {}).(samples, trace.);
  })();

Key points:

• buildWorkerSpans + attachCpuSamples decorates each sample with .spawnLoc (the source location where the task was spawned). This is required for any recipe that filters by spawn location.
• Polls in ws.workerSpans[workerId].polls have .taskId, .start, .end. Use these to filter samples by task or by poll duration.
• trace.callframeSymbols is a Map<string, entry|entry[]> where each entry is {symbol, location}. Array entries are inlined frames (index 0 = outermost).

Recipes

Recipe: Total on-CPU flamegraph

Question it answers: "What is the application spending CPU on?"

const samples = trace.cpuSamples.filter(s => s.source === 0);

When NOT to use: When you want off-CPU / scheduling delay analysis. Use source === 1 instead.

---

Recipe: Off-CPU (scheduling) samples only

Question it answers: "What code was running when the kernel moved my worker thread off-CPU?" Useful for diagnosing blocking calls in async code.

const samples = trace.cpuSamples.filter(s => s.source === 1);

When NOT to use: When diagnosing high CPU usage — those are on-CPU samples (source === 0).

---

Recipe: Just task X

Question it answers: "What does this specific task's CPU profile look like?"

// Collect poll time ranges for the target task
const TARGET_TASK_ID = 3;
const taskPolls = [];
for (const wid of Object.keys(ws.workerSpans)) {
  for (const p of ws.workerSpans[wid].polls) {
    if (p.taskId === TARGET_TASK_ID) taskPolls.push(p);
  }
}
const samples = trace.cpuSamples.filter(s =>
  s.source === 0 && taskPolls.some(p => s.timestamp >= p.start && s.timestamp <= p.end)
);

When NOT to use: When the task has very few polls — you'll get too few samples for a useful flamegraph. Check taskPolls.length first.

---

Recipe: Just polls > N ms

Question it answers: "What code paths cause long polls?"

const THRESHOLD_NS = 5_000_000; // 5ms
const longPolls = [];
for (const wid of Object.keys(ws.workerSpans)) {
  for (const p of ws.workerSpans[wid].polls) {
    if ((p.end - p.start) > THRESHOLD_NS) longPolls.push(p);
  }
}
const samples = trace.cpuSamples.filter(s =>
  s.source === 0 && longPolls.some(p => s.timestamp >= p.start && s.timestamp <= p.end)
);

When NOT to use: When the long polls are idle waits (off-CPU). Switch to source === 1 if the on-CPU flamegraph looks thin.

---

Recipe: One specific poll instance

Question it answers: "What happened during the single worst poll of task X?"

const TARGET_TASK_ID = 3;
let worstPoll = null;
for (const wid of Object.keys(ws.workerSpans)) {
  for (const p of ws.workerSpans[wid].polls) {
    if (p.taskId === TARGET_TASK_ID) {
      if (!worstPoll || (p.end - p.start) > (worstPoll.end - worstPoll.start)) worstPoll = p;
    }
  }
}
const samples = trace.cpuSamples.filter(s =>
  s.source === 0 && s.timestamp >= worstPoll.start && s.timestamp <= worstPoll.end
);

When NOT to use: When the worst poll has < 3 samples — the flamegraph won't be statistically meaningful. Show the raw sample stacks instead.

---

Recipe: Leaf-frame search

Question it answers: "Which samples have a specific function at the leaf (i.e., the function was actually on-CPU)?"

const SEARCH = 'load_native_certs';
const samples = trace.cpuSamples.filter(s => {
  const leaf = s.callchain[s.callchain.length - 1];
  const sym = trace.callframeSymbols.get(leaf);
  if (!sym) return false;
  // Handle both plain entries and inlined-frame arrays
  const name = Array.isArray(sym) ? sym[0].symbol : sym.symbol;
  return name && name.includes(SEARCH);
});

When NOT to use: When you want to find a function anywhere in the stack (not just at the leaf). Remove the [s.callchain.length - 1] indexing and iterate all frames with .some() instead.

---

Recipe: Filter by spawn location

Question it answers: "What does the CPU profile look like for all tasks spawned from a specific call site?"

const SPAWN_LOC = 'src/main.rs:260:14'; // substring match
const samples = trace.cpuSamples.filter(s =>
  s.source === 0 && s.spawnLoc && s.spawnLoc.includes(SPAWN_LOC)
);

When NOT to use: When you want a single task instance, not all tasks from a spawn site. Use the task-ID recipe instead.

---

Recipe: Multi-trace union

Question it answers: "What does the aggregate CPU profile look like across multiple trace files?" Useful for comparing before/after or aggregating across replicas.

const traceFiles = ['../traces/trace-a.bin', '../traces/trace-b.bin'];
const allSamples = [];
const mergedSymbols = new Map();

for (const url of traceFiles) {
  const buf = await fetch(url).then(r => r.arrayBuffer());
  const t = await TraceParser.parseTrace(buf);
  // Merge symbols (first-writer-wins per address)
  for (const [k, v] of t.callframeSymbols) {
    if (!mergedSymbols.has(k)) mergedSymbols.set(k, v);
  }
  allSamples.push(...t.cpuSamples.filter(s => s.source === 0));
}
const samples = allSamples;
// Use mergedSymbols instead of trace.callframeSymbols for setData()
FlamegraphRenderer.createFlamegraph(el, () => {}).setData(samples, mergedSymbols);

Warning: Timestamps come from different monotonic clocks across traces. Do NOT use time-based predicates (e.g., s.timestamp >= X) across traces in a union — the timestamps are incomparable. Cross-trace flamegraphs work because they aggregate by callchain, not time.

When NOT to use: When you need to compare traces side-by-side (differences). Use two separate flamegraphs instead.

Slicing traces with slice.js

Slice traces to keep report folders small and embed loading fast.

Important: --start/--end are ABSOLUTE monotonic ns by default (matching event.ts from parseTrace — typically 10-15 digit numbers). Pass --relative if your numbers are offsets from trace start (typically 9-10 digit numbers like 3900000000 for 3.9s).

# slice the burst window (3.9s–4.05s into the trace):
node /path/to/dial9-trace-format/js/slice.js \
  --input /path/to/trace.bin \
  --output report/traces/burst.bin \
  --relative \
  --start 3900000000 \
  --end 4050000000

Or programmatically:

const { sliceTrace } = require('/path/to/dial9-trace-format/js/slice.js');
const fs = require('fs');

const input = fs.readFileSync('/path/to/trace.bin');
const sliced = sliceTrace(input, {
  timeRange: { startNs: '3900000000', endNs: '4050000000' },
  relative: true,
});
fs.writeFileSync('report/traces/burst.bin', sliced);

Why slice? A full trace can be 100+ MB. Slicing to the relevant window (typically a few seconds) produces files of 100 KB–2 MB, making the report folder portable and embeds load instantly. The slicer preserves symbol table entries, segment metadata, and clock sync events regardless of the time range, so flamegraphs in sliced traces render with full function names.

Note: slice.js v1 supports timeRange filtering only. Event-type filtering is planned for a future release.

Source-code links

For public crates, link to docs.rs:

https://docs.rs/hyper/latest/hyper/proto/h1/io/struct.Buffered.html

The trace_parser.js module exports a _docsRsUrl(location) helper that can generate docs.rs URLs from source locations like hyper-0.14.28/src/proto/h1/dispatch.rs:174.

For private code, ask the user for an example source link (e.g., https://gitlab.acme.corp/team/repo/-/blob/main/src/foo.rs#L42) and derive the URL template from it.

Complete worked example

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>dial9 Trace Report — my-service</title>
<style>
:root { --bg: #0d1117; --surface: #161b22; --border: #30363d; --text: #e6edf3; --muted: #8b949e; --accent: #58a6ff; --critical: #f85149; --warning: #d29922; --info: #58a6ff; }
* { margin: 0; padding: 0; box-sizing: border-box; }
body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif; background: var(--bg); color: var(--text); line-height: 1.6; padding: 2rem; max-width: 1100px; margin:  auto; }
 { : ; : ; }
 { : ; :   ; :  solid (--border); : ; }
 { : (--muted); : ; : ; }
 { : (--surface); :  solid (--border); : ; : ; : ; }
 { : flex; : center; : ; : ; }
 { : ; : ; : uppercase; :  ; : ; }
 { : (--critical); : ; }
 { : (--warning); : ; }
 { : (--info); : ; }
 { : , monospace; : ; : ; :  ; : ; }
 { : (--accent); : none; }
 { : underline; }
 { : ; : ; }




dial9 Trace Report
Service: my-service | Duration: 4.2s | Workers: 2

Findings


  
    Critical
    Blocking file I/O on async worker at startup
  
  Task 3 performs a synchronous file read that blocks worker 1 for 17.7ms at t=350µs.
     Source: main.rs:260:14
  Fix: Move config loading to spawn_blocking.
  



  
    Warning
    Connection burst saturates workers (23ms scheduling delay)
  
  ~80 tasks woken simultaneously at t≈3.9s cause wake-to-poll delays up to 23ms.
  Fix: Increase worker count or add connection backpressure.
  
  Open this 150ms burst window in the full viewer →



  
    Info
    Memory allocation dominated by hyper read buffers
  
  728 sampled allocations (~403 MB throughput). Dominant site:
     hyper::proto::h1::io::Buffered::poll_read_from_io.
     6 allocations not freed — likely one-time startup allocs, not leaks.

What NOT to do

• Don't inline trace bytes as base64. Traces are megabytes; use sliced .bin files in traces/.
• Don't render flamegraphs from scratch with CSS bars. Use the standalone HTML flamegraph pattern — it produces real interactive flamegraphs.
• Don't invent viewer URL params. There is no ?worker= or ?source=. The authoritative list, including task and analysis selection fields, is the URL contract in dial9-viewer/ui/README.md.
• Don't copy the full multi-MB trace into the report folder. Slice it to the relevant time window.
• Don't rely on file://. Reports fetch trace files via HTTP. Tell users to view via dial9 report serve <folder> (or python3 -m http.server).
• Don't omit the built viewer.html + assets/ from the report folder if you include viewer deep-links — the page will not load.