Turn a perf Trace into a Readable SVG Timechart

perf timechart turns a workload trace into an actual picture of what the system was doing, instead of a scrollback full of numbers. In this guide you record a command, render its scheduler and CPU activity as output.svg, then repeat the capture with disk and network I/O when that is the detail you need. Examples use the installed linux-tools-common package, version 6.8.0-142.142, and the behaviour described by its local manpage dated 1 September 2026.

Allow about 10 minutes for a first capture and inspection. You need the perf command, a workload you can safely repeat, and an SVG viewer such as a browser or Inkscape.

Recording a command normally needs no elevated privilege. A system-wide capture may be restricted by the kernel or by local perf policy, so have an administrator available if the command reports a permissions failure.

1. Choose a bounded workload

Pick a command with a clear beginning and end. A bounded workload makes the chart easier to read and avoids collecting unrelated activity for an open-ended service. Replace the example below with a command that is safe to run on your machine.

mkdir -p "$HOME/perf-timechart-run"
cd "$HOME/perf-timechart-run"
perf timechart record -- sh -c 'for n in 1 2 3 4 5; do sha256sum /usr/share/dict/words 2>/dev/null || true; done'

The workload is only an example: if that file does not exist, the loop still finishes, but it will not represent useful application work. Substitute a test command or a real repeatable operation. The -- separates perf's own arguments from the command being measured, so a workload option is never mistaken for a perf option.

ls -lh perf.data

2. Render the scheduler and CPU chart

Run the second form of the command with the trace as input. By default it reads perf.data and writes output.svg. The default capture contains scheduler and CPU events, including task switches, running time and CPU power states; it does not automatically become an I/O chart.

perf timechart --output=workload.svg
ls -lh workload.svg

Open workload.svg in an SVG-capable viewer. The message should say a trace was written, followed by its duration.

3. Capture I/O when waiting is the question

Repeat the workload with -I when you need disk or network activity. This option belongs to the record form, not the rendering form. Keep this capture separate so you can compare it with the scheduler-only run.

perf timechart record -I -- sh -c 'for n in 1 2 3 4 5; do sha256sum /usr/share/dict/words 2>/dev/null || true; done'
perf timechart --input=perf.data --output=io-workload.svg
ls -lh io-workload.svg

In I/O mode each activity bar has an incoming and outgoing part: reads and ingress packets show above the bar, writes and egress packets below it. The chart can also show time spent in poll, epoll or select system calls.

A visually quiet chart is not proof that no I/O happened: very short events can be hard to see at the chosen scale.

4. Make a crowded chart useful

Start with one filter rather than changing several settings at once. These options mean different things depending on whether you use them when recording or when rendering:

• --process shows only a named task; the manpage allows a process name or PID.
• --power-only draws only CPU power information.
• --tasks-only omits processor state transitions.

On recording they select what gets collected; on rendering they select what gets drawn.

perf timechart --input=perf.data --output=worker.svg --process worker
perf timechart --input=perf.data --output=power.svg --power-only
perf timechart --input=perf.data --output=tasks.svg --tasks-only

Use --highlight=gcc to emphasise tasks with that name. A numeric value instead means a duration in nanoseconds, so a value such as 1000000 highlights tasks running for more than one millisecond. Do not add a unit suffix to that value: the documented interpretation is numeric nanoseconds or a non-numeric task name.

For I/O charts, --io-min-time=5ms makes very short events draw as though they lasted at least five milliseconds, and --io-merge-dist=10us merges events within ten microseconds of one another to reduce the number of figures in the SVG. These are display choices, not changes to the recorded events, and increasing them can make the picture clearer while hiding fine timing differences.

5. Adjust width and CPU ordering

The default SVG width is 1000. If labels overlap or the chart is being printed, choose a larger width. With --topology, CPUs are sorted according to topology rather than the default ordering.

perf timechart --input=perf.data --output=wide.svg --width=1800 --topology

If the chart has too many tasks, --proc-num=20 asks perf to print task information for at least 20 tasks. That is a minimum, not a strict maximum, so it will not guarantee a chart with exactly 20 entries. Keep the original perf.data while experimenting: rendering options can be changed without recording the workload again.

6. Diagnose the common traps

If perf cannot record, first check that you are measuring the intended command and that the current directory is writable.

sudo perf timechart record
# Stop the bounded observation with Ctrl-C, then render as root or copy perf.data safely.
sudo perf timechart --input=perf.data --output=system.svg

Do not run a privileged capture if the workload can be run unprivileged. The trace may contain system-wide activity and task names that should not be shared: store it with appropriate permissions and remove it once the investigation is complete. If you only need a new chart, do not delete the trace; render it to a new filename instead.

If rendering reports that perf.data is absent, pass the actual path with --input=/path/to/perf.data. If symbols are not found, --symfs=<directory> tells perf to look for symbol files relative to that directory. Symbol lookup affects labels, not whether the trace exists. A trace recorded on a different system may also have different symbol files and task names.