pw-profiler

Profile the default instance, logging to profile.log (gnuplot files and a HTML file for result visualizing are also generated)

$ pw-profiler

$ pw-profiler [[-o|--output]] [path/to/file.log]

$ pw-profiler [[-r|--remote]] [remote_name]

$ pw-profiler [[-h|--help]]

pw-profiler [OPTIONS]

-h, --help
    Show help options and usage information.

--version
    Display the version of pw-profiler.

-i, --input FILE
    Specify the input file containing profiling data. If omitted, input is read from standard input (stdin).

-o, --output FILE
    Specify the output file to write the processed data. If omitted, output is written to standard output (stdout).

-m, --mode MODE
    Set the output mode for analysis. Possible modes are 'graph' (default), 'dump', and 'stats'.

graph: Visualizes the execution flow as a call graph.
dump: Provides a raw, chronological dump of profiling events.
stats: Shows aggregated statistics of events.

-j, --json
    Output the results in JSON format. This option overrides the --mode setting.

-p, --pretty
    Pretty print the JSON output, making it more readable with indentation.

-t, --time-unit UNIT
    Specify the time unit for 'stats' mode. Options: 'ns' (nanoseconds), 'us' (microseconds, default), 'ms' (milliseconds), 's' (seconds).

-f, --format FORMAT
    Set the format for 'dump' mode. Options: 'text' (default) and 'csv' (comma-separated values).

-s, --sort FIELD
    Specify the field to sort by in 'stats' mode. Options: 'time', 'count', 'avg' (average time).

-r, --reverse
    Reverse the sort order in 'stats' mode (descending instead of ascending).

-n, --limit N
    Limit the number of entries displayed in 'stats' mode to the top N entries.

pw-profiler is a PipeWire utility for analyzing performance and timing data generated by PipeWire components. It can read profiling dumps, typically captured from pw-top or other PipeWire tools, and present them in various formats like call graphs, detailed event dumps, or aggregated statistics. This tool is invaluable for debugging performance issues, identifying bottlenecks, and understanding the execution flow within the PipeWire graph, helping developers and system administrators optimize multimedia processing and ensure low-latency multimedia operations.

• pw-profiler analyzes pre-recorded profiling data; it does not profile live PipeWire sessions directly.
• The quality and usefulness of the output depend heavily on the verbosity and type of profiling data collected by the source (e.g., pw-top's dump).
• Interpreting the output, especially call graphs and detailed dumps, often requires a good understanding of PipeWire's internal architecture and component interactions.

Profiling data for pw-profiler can often be captured from pw-top, PipeWire's top-like graph and performance monitor. You can redirect pw-top's output or use its profiling dump feature (if available) to a file, then feed that file into pw-profiler.
Example: pw-top --dump-profile > profile.txt followed by pw-profiler -i profile.txt -m graph.

The --mode option provides different perspectives on the profiling data:

Graph Mode: Generates a hierarchical view of function calls and their timings, useful for identifying call paths and latencies within the PipeWire processing flow.

Dump Mode: Provides a raw chronological list of profiling events, valuable for detailed event sequence analysis and debugging specific timing issues.

Stats Mode: Aggregates profiling data, showing total time spent, call counts, and average times for each profiled function or component, excellent for quick performance overviews and identifying top bottlenecks.

pw-profiler is an integral part of the PipeWire project, which was initially developed by Wim Taymans at Red Hat and publicly announced in 2017. Designed as a modern low-latency, high-performance multimedia server for Linux, PipeWire aims to handle audio, video, and hardware access seamlessly. The pw-profiler utility was introduced as an essential debugging and optimization tool, evolving with the PipeWire framework itself, to help developers understand and fine-tune its complex graph processing and performance characteristics.

pw-top(1), pw-dump(1), perf(1), ftrace(1)