| name | perfetto |
| description | Use when the user wants to view, inspect, or share Perfetto/Chrome trace files -- triggered by words like "trace", "perf", "perfetto", "profiling", "trace viewer", or when dealing with trace JSON files from training runs. |
| version | 1.0.0 |
Perfetto Trace Viewer
Generate links to the CharlieBot built-in Perfetto trace viewer, which can merge cross-rank traces of the same time window into a single view.
Endpoints
All URLs use <base_url> where <base_url> is the CharlieBot URL resolved from HOST MEMORY (look for the CharlieBot URL entry).
Merge cross-rank traces from a directory
<base_url>/perfetto?dir=<absolute-path>
Auto-discovers all *.json trace files in the directory, merges them client-side (labeling by rank), and loads into an embedded Perfetto UI.
Use ?dir= only for cross-rank merging — i.e. when every file in the directory is a different rank's trace of the same time window/step. The merger labels tracks by rank and assumes one trace per rank; mixing multiple time windows of the same rank into one ?dir= link will produce a confusing/overlapping view.
If a directory contains multiple time windows (or multiple steps) for the same rank(s), generate separate links — one per time window — each pointing at just that window's files. Use ?pattern= to scope a ?dir= link to a single window, or list the per-rank files explicitly with repeated ?trace= params.
Optional params:
&pattern=<glob> -- file pattern to match (default: *.json); use this to isolate one time window in a mixed directory&title=<text> -- custom page title
View specific trace files
<base_url>/perfetto?trace=/files/<path1>&trace=/files/<path2>
Pass one or more trace= params with /files/-prefixed absolute paths.
Single trace
<base_url>/perfetto?trace=/files/<absolute-path>
Examples
| Scenario | URL |
|---|
| Cross-rank merge for one step | <base_url>/perfetto?dir=/path/to/traces/step100 |
Scope ?dir= to one time window | <base_url>/perfetto?dir=/path/to/traces&pattern=trace_rank*_step100.json |
| Only rank 0 | <base_url>/perfetto?trace=/files/path/to/traces/trace_rank000_step100.json |
| Two time windows of rank 0 | generate two separate links, one per window — do not combine in a single ?dir= |
Rules
- Always verify the trace directory/files exist before sharing the link (use
ls or Glob)
- Resolve base URL from HOST MEMORY — never hardcode hostnames or ports
?dir= is for cross-rank merging only. Multiple time-window traces of the same rank must be linked separately (one URL per window), not bundled in one ?dir=- Before using
?dir=, confirm the directory holds at most one trace per rank for a single time window; otherwise narrow it with &pattern= or switch to explicit ?trace= params
- Present the link in markdown format:
[descriptive text](url)
- Note: only JSON traces can be merged; protobuf traces will show only the first file
