perfetto

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, that is, 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=/absolute_filepath/<path1>&trace=/absolute_filepath/<path2>

Pass one or more trace= params, each naming a trace file the way the file-server skill writes a file link.

Single trace

<base_url>/perfetto?trace=/absolute_filepath/<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=/absolute_filepath/path/to/traces/trace_rank000_step100.json
Two time windows of rank 0	generate two separate links, one per window, rather than one combined ?dir=

Rules

1. ?dir= is for cross-rank merging only. Multiple time-window traces of the same rank belong in separate links, one URL per window, rather than bundled in one ?dir=
2. 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
3. Only JSON traces can be merged; a protobuf trace shows only the first file