timetrace

perf timetrace [options]

-i, --input file
    Specifies the input perf.data file to analyze (default: perf.data).

--kallsyms file
    Provides a path to the kallsyms file for kernel symbol resolution.

--vmlinux file
    Specifies the path to the vmlinux file for enhanced kernel symbol resolution and debugging information.

--objdump path
    Specifies the path to the objdump utility for disassembling binaries.

--no-browser
    Prevents the command from launching the graphical browser, often used in conjunction with --stdio for text-based output.

--full-path
    Shows the full path of object files in the trace.

--cpu-utilization
    Displays a graph of overall CPU utilization over time.

--cpu-frequency
    Displays a graph of CPU frequency changes over time.

--perf-clock-output
    Displays output related to the perf clock.

--event-graph event
    Displays a graph for a specific event (e.g., sched:sched_switch).

--per-cpu-graph event
    Displays per-CPU graphs for a specified event type.

--hide-browser-stats
    Hides statistical information in the browser interface.

--stdio
    Outputs the timetrace information in text format to standard output instead of launching the GUI.

--output file
    Specifies an output file name when --stdio is used, storing the text-based trace.

perf timetrace is a subcommand of the Linux perf utility, designed for graphical visualization and analysis of performance trace data. It processes perf.data files, typically generated by perf record, to display a timeline of system events. This includes CPU activity, context switches, system calls, and function calls across various processes and threads. By presenting a time-ordered view, perf timetrace helps developers and system administrators identify performance bottlenecks, analyze execution flows, and understand system behavior over time. It often utilizes a Python-based graphical user interface to render the trace data, providing an interactive way to explore the captured events. It's an indispensable tool for in-depth performance debugging and optimization on Linux systems.

perf timetrace relies heavily on the perf utility and its underlying infrastructure.
It often requires Python with specific graphical libraries (like Tkinter or GTK) to launch its interactive browser interface.
For accurate symbol resolution, especially for kernel functions, proper kallsyms or vmlinux files are crucial.
Analyzing large perf.data files can be resource-intensive and generate extensive output.
Running perf commands typically requires elevated privileges (e.g., sudo or CAP_PERFMON capability).

To use perf timetrace, you typically first record performance data using perf record. For instance, to record system-wide data for 5 seconds including callgraphs:
perf record -a -g sleep 5
After recording, you can visualize the data with:
perf timetrace
This will usually launch an interactive graphical browser displaying the events.

The perf timetrace browser presents events on a timeline, allowing users to zoom in/out, pan, and select specific regions or events. It often shows different event types (e.g., sched_switch, syscalls, CPU samples) on separate tracks, along with aggregated graphs for CPU utilization or frequency. Details of selected events, including call stacks, are typically shown in a separate pane.

The graphical interface of perf timetrace is often implemented in Python. This means that for the interactive browser to function, your system needs to have Python installed along with specific libraries (like python-perf bindings and a GUI toolkit such as Tkinter or GTK). If these dependencies are not met, you might need to use the --stdio option for text-based output.

The perf tool, which timetrace is a part of, was introduced into the Linux kernel in version 2.6.31, evolving from earlier profiling tools. The timetrace subcommand specifically emerged to address the need for a more intuitive, graphical representation of complex, time-ordered performance events captured by perf record. Its development has focused on enhancing visualization capabilities, often leveraging Python for its interactive browser interface. It represents a significant step towards making detailed performance analysis more accessible and understandable than purely text-based reports, continuously being refined within the Linux kernel development cycle.

perf(1): The primary Linux perf utility suite., perf-record(1): Used to collect performance data that perf timetrace visualizes., perf-report(1): Generates textual reports and summary statistics from perf.data files., perf-script(1): Allows scripting and detailed analysis of perf.data for custom reports., ftrace(1): The underlying kernel tracing framework used by perf., strace(1): Traces system calls and signals for a process.