[PATCH 4/4] perf python: Compress the traces of the perfetto script

From: Lalit Maganti

Date: Sat Nov 14 2026 - 19:39:59 EST


Perfetto reads zstd and gzip traces directly, so compress the output by
default. Add a -c/--compression option:
- auto (default): zstd if Python has compression.zstd (3.14+), else
gzip, so only the standard library is needed
- zstd: level 9
- gzip: level 6, with no time or file name in the header so the output
is reproducible
- none

Without -o, the output file gets a matching extension: perf.pftrace.zst,
perf.pftrace.gz or perf.pftrace.

For 4496 samples of a two-thread workload, the trace is 127KB
uncompressed, 37KB with gzip and 30KB with zstd. Compressing takes a few
milliseconds.

The shell test now checks every compression the Python running it
supports.

Assisted-by: LLM
Signed-off-by: Lalit Maganti <lalitmaganti@xxxxxxxxx>
---
tools/perf/python/perfetto.py | 64 ++++++++++++++++++++---
tools/perf/tests/shell/script_perfetto.sh | 58 ++++++++++++++------
2 files changed, 99 insertions(+), 23 deletions(-)

diff --git a/tools/perf/python/perfetto.py b/tools/perf/python/perfetto.py
index e168b146e538..3fd3857bde13 100755
--- a/tools/perf/python/perfetto.py
+++ b/tools/perf/python/perfetto.py
@@ -10,12 +10,18 @@ The protobuf wire format is simple enough that the few messages needed are
encoded by hand below, which avoids a dependency on the protobuf package and
generated bindings. The field numbers in this file are taken from the .proto
files under protos/perfetto/trace/ in the Perfetto repository and are stable.
+
+Perfetto reads zstd and gzip compressed traces natively, so the trace is
+compressed with whichever the Python standard library has (zstd since 3.14).
"""
from __future__ import annotations

import argparse
+import gzip
import http
import http.server
+import importlib
+import io
import os
import sys
import time
@@ -24,10 +30,26 @@ import webbrowser
from collections.abc import Hashable
from dataclasses import dataclass, field
from enum import IntEnum
-from typing import BinaryIO, Dict, Optional, Tuple
+from types import ModuleType
+from typing import Dict, Optional, Tuple

import perf

+# zstd in the standard library, available since Python 3.14. Imported by name so
+# that the script also type checks with older versions.
+try:
+ ZSTD: Optional[ModuleType] = importlib.import_module('compression.zstd')
+except ImportError:
+ ZSTD = None
+
+# Levels that compress traces close to the maximum at a fraction of its cost.
+ZSTD_LEVEL = 9
+GZIP_LEVEL = 6
+
+# The default trace file name, extended with the compression's file extension.
+DEFAULT_OUTPUT = 'perf.pftrace'
+COMPRESSION_EXTENSIONS = {'zstd': '.zst', 'gzip': '.gz', 'none': ''}
+
# The only port that the Content Security Policy of ui.perfetto.dev allows
# fetching traces from.
UI_FETCH_PORT = 9001
@@ -388,7 +410,7 @@ class Sequence:
class PerfettoWriter:
"""Writes perf samples to a Perfetto trace file."""

- def __init__(self, out: BinaryIO) -> None:
+ def __init__(self, out: io.BufferedIOBase) -> None:
self.out = out
self.session: Optional[perf.session] = None
self.sequences: Dict[str, Sequence] = {}
@@ -523,9 +545,22 @@ class PerfettoWriter:
varint_field(TracePacketField.TIMESTAMP_CLOCK_ID, clock))


-def convert(input_path: str, output_path: str) -> PerfettoWriter:
+def open_output(raw: io.BufferedIOBase, compression: str) -> io.BufferedIOBase:
+ """Returns a file that compresses what is written to it into raw."""
+ if compression == 'zstd':
+ assert ZSTD is not None
+ out: io.BufferedIOBase = ZSTD.ZstdFile(raw, mode='wb', level=ZSTD_LEVEL)
+ return out
+ if compression == 'gzip':
+ # No file name or time in the header, so the output is reproducible.
+ return gzip.GzipFile(filename='', mode='wb', fileobj=raw,
+ compresslevel=GZIP_LEVEL, mtime=0)
+ return raw
+
+
+def convert(input_path: str, output_path: str, compression: str) -> PerfettoWriter:
"""Converts a perf.data file to a Perfetto trace file."""
- with open(output_path, 'wb') as out:
+ with open(output_path, 'wb') as raw, open_output(raw, compression) as out:
writer = PerfettoWriter(out)
session = perf.session(perf.data(input_path), sample=writer.process_sample)
writer.session = session
@@ -593,16 +628,31 @@ def main() -> int:
description='Convert perf.data to a Perfetto trace and open it in the Perfetto UI')
parser.add_argument('-i', '--input', default='perf.data',
help='perf.data file to read (default: perf.data)')
- parser.add_argument('-o', '--output', default='perf.pftrace',
- help='Perfetto trace file to write (default: perf.pftrace)')
+ parser.add_argument('-o', '--output',
+ help=f'Perfetto trace file to write (default: {DEFAULT_OUTPUT} '
+ 'with the extension of the compression)')
+ parser.add_argument('-c', '--compression', default='auto',
+ choices=['auto', *COMPRESSION_EXTENSIONS],
+ help='compression of the trace; auto is zstd if Python has it '
+ '(3.14 or later), else gzip (default: auto)')
parser.add_argument('-n', '--no-open', action='store_true',
help='only write the trace, do not open it in the Perfetto UI')
parser.add_argument('--origin', default='https://ui.perfetto.dev',
help='Perfetto UI to open the trace in (default: https://ui.perfetto.dev)')
args = parser.parse_args()

+ compression = args.compression
+ if compression == 'auto':
+ compression = 'zstd' if ZSTD is not None else 'gzip'
+ elif compression == 'zstd' and ZSTD is None:
+ print('zstd compression needs Python 3.14 or later, use --compression gzip',
+ file=sys.stderr)
+ return 1
+ if args.output is None:
+ args.output = DEFAULT_OUTPUT + COMPRESSION_EXTENSIONS[compression]
+
try:
- writer = convert(args.input, args.output)
+ writer = convert(args.input, args.output, compression)
except (OSError, TypeError, ValueError) as err:
# The perf module reports events it cannot handle as TypeError or
# ValueError. Do not leave a truncated trace behind.
diff --git a/tools/perf/tests/shell/script_perfetto.sh b/tools/perf/tests/shell/script_perfetto.sh
index 87797b377922..503563d77982 100755
--- a/tools/perf/tests/shell/script_perfetto.sh
+++ b/tools/perf/tests/shell/script_perfetto.sh
@@ -47,25 +47,51 @@ if ! perf record -o "${perfdata}" -e cpu-clock -g -- perf test -w noploop > /dev
fi
nr_samples=$(perf script -i "${perfdata}" -F tid | wc -l)

-echo "Converting ${nr_samples} samples"
-if ! output=$("${PYTHON}" "${script}" --no-open -i "${perfdata}" -o "${trace}"); then
- echo "perf script perfetto test [Failed: conversion]"
- exit 1
-fi
-echo "${output}"
+# Writes a trace of any compression the script supports, decompressed, to stdout.
+decompress() {
+ "${PYTHON}" - "$1" <<'PYEOF'
+import gzip, importlib, sys
+data = open(sys.argv[1], 'rb').read()
+if data[:2] == b'\x1f\x8b':
+ data = gzip.decompress(data)
+elif data[:4] == b'\x28\xb5\x2f\xfd':
+ data = importlib.import_module('compression.zstd').decompress(data)
+sys.stdout.buffer.write(data)
+PYEOF
+}

-if ! echo "${output}" | grep -q "Wrote ${nr_samples} samples"; then
- echo "perf script perfetto test [Failed: expected ${nr_samples} samples]"
- exit 1
-fi
+test_compression() {
+ local compression=$1

-# Interned strings are stored as is in the trace, so the source of the samples,
-# the event and the symbol of the workload must all be in there.
-for expected in linux.perf cpu-clock noploop; do
- if ! grep -q "${expected}" "${trace}"; then
- echo "perf script perfetto test [Failed: no ${expected} in trace]"
- exit 1
+ echo "Converting ${nr_samples} samples with ${compression} compression"
+ if ! output=$("${PYTHON}" "${script}" --no-open --compression "${compression}" \
+ -i "${perfdata}" -o "${trace}"); then
+ echo "perf script perfetto test [Failed: ${compression} conversion]"
+ return 1
fi
+ echo "${output}"
+
+ if ! echo "${output}" | grep -q "Wrote ${nr_samples} samples"; then
+ echo "perf script perfetto test [Failed: expected ${nr_samples} samples]"
+ return 1
+ fi
+
+ # Interned strings are stored as is in the trace, so the source of the
+ # samples, the event and the symbol of the workload must all be in there.
+ for expected in linux.perf cpu-clock noploop; do
+ if ! decompress "${trace}" | grep -qa "${expected}"; then
+ echo "perf script perfetto test [Failed: no ${expected} in ${compression} trace]"
+ return 1
+ fi
+ done
+}
+
+compressions="none gzip auto"
+if "${PYTHON}" -c "import compression.zstd" 2> /dev/null; then
+ compressions="${compressions} zstd"
+fi
+for compression in ${compressions}; do
+ test_compression "${compression}" || exit 1
done

echo "perf script perfetto test [Success]"
--
2.56.0