Re: [PATCH v1 57/58] perf Documentation: Update for standalone Python scripts and remove obsolete data

sashiko-bot
2026-04-20T00:45:01Z

Sashiko AI review found 2 potential issue(s):
- [High] The documented standalone Python script model breaks all standard `perf script` command-line filtering options (e.g., `--cpu`, `--time`, `--pid`).
- [Medium] The commit message claims to remove the link to perf-script-python in perf-script.txt, but it was retained.
--

commit acb52943132d8618b045a0dd53ad8a5d4cdff814
Author: Ian Rogers <irogers@google.com>

perf Documentation: Update for standalone Python scripts and remove obsolete data

This commit removes obsolete documentation for perf-script-perl and updates
perf-script-python.txt to describe the new standalone Python script usage
with the perf module. It also removes documentation for options that no
longer apply.

> - Remove links to perf-script-perl and perf-script-python in
> perf-script.txt.

This isn't a bug, but does this commit message accurately reflect the changes?
The diff shows that while the link to perf-script-perl was removed, the link
to perf-script-python was retained in the SEE ALSO section of perf-script.txt.

> diff --git a/tools/perf/Documentation/perf-script.txt b/tools/perf/Documentation/perf-script.txt
> index 200ea25891d88..93ed1ea704c95 100644
> --- a/tools/perf/Documentation/perf-script.txt
> +++ b/tools/perf/Documentation/perf-script.txt
> @@ -9,10 +9,7 @@ SYNOPSIS
> --------
> [verse]
> 'perf script' [<options>]
> -'perf script' [<options>] record [<record-options>] <command>
> -'perf script' [<options>] report [script-args]
> -'perf script' [<options>] <required-script-args> [<record-options>] <command>
> -'perf script' [<options>] <top-script> [script-args]
> +'perf script' [<options>] [script-args]

Under the new standalone script architecture, how are standard command-line
filtering options (such as --cpu, --time, or --pid) applied to the trace
processing?

While this limitation appears to have been introduced by the previous patch
in the series that refactored the script execution model, this commit
documents the new behavior.

Since perf script spawns the Python script as a separate process, it
doesn't appear to pass these parsed filters to the spawned process through
arguments or environment variables.

Looking at the new perf.session Python API, it initializes a fresh
perf_session and processes all events directly from perf.data without
native support or parameters for applying these filters.

Will users executing a command like 'perf script --cpu 0 myscript.py' have
their filters silently ignored, causing the script to process the entire
trace instead of the requested subset?

[ ... ]

> @@ -543,6 +486,5 @@ include::guest-files.txt[]
>
> SEE ALSO
> --------
> -linkperf:perf-record[1], linkperf:perf-script-perl[1],
> -linkperf:perf-script-python[1], linkperf:perf-intel-pt[1],
> -linkperf:perf-dlfilter[1]
> +linkperf:perf-record[1], linkperf:perf-script-python[1],
> +linkperf:perf-intel-pt[1], linkperf:perf-dlfilter[1]

This is the section where linkperf:perf-script-python[1] remains, contrary
to the commit message.

--
Sashiko AI review · https://sashiko.dev/#/patchset/20260419235911.2186050-1-irogers@google.com?part=57