[PATCH 0/2] perf script flamegraph: Fix input file name errors

[PATCH 0/2] perf script flamegraph: Fix input file name errors

[Stephen Brennan]

The flamegraph.py script has a "-i" option which it uses in an attempt to
know the input file name for the data it is processing. But perf itself is
using that flag and not forwarding its value to the script, so the entire
strategy won't work. It's further complicated by how the option processing
is handled in the flamegraph-report script -- details in patch 2.

This series introduces a helper to allow python scripts to see the input
file name, and then fixes flamegraph.py. Testing with a variety of options
like below shows that it is using the correct input files in most use cases
I can think of:

$ export PERF_EXEC_PATH=$(pwd)/tools/perf

$ sudo -E tools/perf/perf script flamegraph -a -F999 -- sleep 1
dumping data to flamegraph.html

$ sudo -E tools/perf/perf script record flamegraph \
                          -o myfile.data -a -F999 -- sleep 1
[ perf record: Woken up 1 times to write data ]
[ perf record: Captured and wrote 2.891 MB myfile.data (1832 samples) ]

$ sudo -E tools/perf/perf script report flamegraph -i myfile.data \
                                 -- -o myfile.html
dumping data to myfile.html

$ sudo -E tools/perf/perf script \
       -s tools/perf/scripts/python/flamegraph.py -i myfile.data
dumping data to flamegraph.html

$ sudo -E tools/perf/perf script record flamegraph \
       -o - -a -F999 -- sleep 1 \
    | tools/perf/perf script report flamegraph -i - -- -o manual.html
[ perf record: Woken up 1 times to write data ]
[ perf record: Captured and wrote 2.936 MB - ]
dumping data to manual.html


Stephen Brennan (2):
  tools: perf: add perf_input_name() helper
  tools: perf: flamegraph.py: fix "Error reading report header"

 .../perf/Documentation/perf-script-python.txt |  1 +
 .../scripts/python/Perf-Trace-Util/Context.c  | 16 ++++++++++++++
 tools/perf/scripts/python/flamegraph.py       | 22 +++++++++----------
 3 files changed, 27 insertions(+), 12 deletions(-)

-- 
2.52.0

[PATCH 1/2] tools: perf: add perf_input_name() helper

[Stephen Brennan]

The perf scripting API does not expose the name of the input file being
processed. Some scripts, like flamegraph.py, assume that the "-i" option
will be passed through, but when perf actually processes "-i", it does
not keep it on the command line for the script. (This could break some
scripts which do not expect it.)

To allow scripts to know what file they're processing, add a new helper
perf_input_name(), which returns either the filename being processed, or
None for an unnamed pipe.

Signed-off-by: Stephen Brennan <stephen.s.brennan@oracle.com>
---
 tools/perf/Documentation/perf-script-python.txt  |  1 +
 .../scripts/python/Perf-Trace-Util/Context.c     | 16 ++++++++++++++++
 2 files changed, 17 insertions(+)

diff --git a/tools/perf/Documentation/perf-script-python.txt b/tools/perf/Documentation/perf-script-python.txt
index 27a1cac6fe763..3f127024f640d 100644
--- a/tools/perf/Documentation/perf-script-python.txt
+++ b/tools/perf/Documentation/perf-script-python.txt
@@ -622,6 +622,7 @@ as perf_trace_context.perf_script_context .
  common_lock_depth(context) - returns common_lock_depth for the current event
  perf_sample_insn(context) - returns the machine code instruction
  perf_set_itrace_options(context, itrace_options) - set --itrace options if they have not been set already
+ perf_input_name(context) - returns the input file name (or None for an unnamed pipe)
  perf_sample_srcline(context) - returns source_file_name, line_number
  perf_sample_srccode(context) - returns source_file_name, line_number, source_line
  perf_config_get(config_name) - returns the value of the named config item, or None if unset
diff --git a/tools/perf/scripts/python/Perf-Trace-Util/Context.c b/tools/perf/scripts/python/Perf-Trace-Util/Context.c
index c19f446109831..c50c2432c1f60 100644
--- a/tools/perf/scripts/python/Perf-Trace-Util/Context.c
+++ b/tools/perf/scripts/python/Perf-Trace-Util/Context.c
@@ -20,6 +20,7 @@
 #include "../../../util/map.h"
 #include "../../../util/maps.h"
 #include "../../../util/auxtrace.h"
+#include "../../../util/data.h"
 #include "../../../util/session.h"
 #include "../../../util/srcline.h"
 #include "../../../util/srccode.h"
@@ -181,6 +182,19 @@ static PyObject *__perf_config_get(PyObject *obj, PyObject *args)
 	return Py_BuildValue("s", perf_config_get(config_name));
 }
 
+static PyObject *perf_input_name(PyObject *obj, PyObject *args)
+{
+	struct scripting_context *c = get_scripting_context(args);
+
+	if (!c)
+		return NULL;
+
+	if (!c->session || !c->session->data || !c->session->data->path)
+		Py_RETURN_NONE;
+
+	return PyUnicode_DecodeFSDefault(c->session->data->path);
+}
+
 static PyMethodDef ContextMethods[] = {
 #ifdef HAVE_LIBTRACEEVENT
 	{ "common_pc", perf_trace_context_common_pc, METH_VARARGS,
@@ -199,6 +213,8 @@ static PyMethodDef ContextMethods[] = {
 	{ "perf_sample_srccode", perf_sample_srccode,
 	  METH_VARARGS,	"Get source file name, line number and line."},
 	{ "perf_config_get", __perf_config_get, METH_VARARGS, "Get perf config entry"},
+	{ "perf_input_name",	perf_input_name,
+	  METH_VARARGS,	"Get the input file name, or None for a pipe"},
 	{ NULL, NULL, 0, NULL}
 };
 
-- 
2.52.0

[PATCH 2/2] tools: perf: flamegraph.py: fix "Error reading report header"

[Stephen Brennan]

When running "perf script flamegraph" in a directory without perf.data,
the script succeeds but prints out the following error:

    # perf script flamegraph -ag -F999 -- sleep 5
    failed to open perf.data: No such file or directory  (try 'perf record' first)
    Error reading report header: Command '['perf', 'report', '--header-only']' returned non-zero exit status 255.
    dumping data to flamegraph.html

If a "perf.data" file were present in the working directory, then the
error would not occur, but flamegraph.py would silently include an
incorrect header as the context for the flamegraph.

The issue is with the "-i" option and how it interacts with option
parsing in the flamegraph-report shell script. Below are the different
flamegraph-report script calls in recent git history:

[1]: perf script [...] -- "$@"
[2]: perf script [...] -i - -- "$@"
[3]: perf script [...] "$@"

[1] is prior to commit 23e0a63c6dd3f ("perf script: force stdin for
flamegraph in live mode"), [2] is after the same commit, and [3] is
after commit 29bab85418efd ("perf script: Fix hangup in offline
flamegraph report"). As noted in the latter commit, for the "perf script
flamegraph" invocation, the parent perf process which sets up the pipe
will set the appropriate "-i -" option when it invokes
flamegraph-report. Thus, the third form is the correct way to ensure
perf itself processes the "-i" option and thus processes the correct
input file.

As a result, for cases 1 and 2, there was an input file string passed to
flamegraph.py -- though it did not necessarily match the one that perf
was processing. For the current case (#3), the script doesn't receive an
input file string and thus assumes that "perf.data" is the input, even
when stdin is being processed.

All of this is fragile and works around what we really want: to know
what input file perf is processing. The previous commit implements a
helper for this, so drop the "-i" option entirely and use the helper to
properly detect the filename.

Signed-off-by: Stephen Brennan <stephen.s.brennan@oracle.com>
---
 tools/perf/scripts/python/flamegraph.py | 22 ++++++++++------------
 1 file changed, 10 insertions(+), 12 deletions(-)

diff --git a/tools/perf/scripts/python/flamegraph.py b/tools/perf/scripts/python/flamegraph.py
index ad735990c5bec..d49b96a324a6f 100755
--- a/tools/perf/scripts/python/flamegraph.py
+++ b/tools/perf/scripts/python/flamegraph.py
@@ -28,6 +28,8 @@ import sys
 from typing import Dict, Optional, Union
 import urllib.request
 
+from perf_trace_context import perf_input_name, perf_script_context
+
 MINIMAL_HTML = """<head>
   <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/d3-flame-graph@4.1.3/dist/d3-flamegraph.css">
 </head>
@@ -122,20 +124,14 @@ class FlameGraphCLI:
         node.value += 1
 
     def get_report_header(self) -> str:
-        if self.args.input == "-":
+        if self.input_file_name == "-":
             # when this script is invoked with "perf script flamegraph",
             # no perf.data is created and we cannot read the header of it
             return ""
 
         try:
-            # if the file name other than perf.data is given,
-            # we read the header of that file
-            if self.args.input:
-                output = subprocess.check_output(["perf", "report", "--header-only",
-                                                  "-i", self.args.input])
-            else:
-                output = subprocess.check_output(["perf", "report", "--header-only"])
-
+            output = subprocess.check_output(["perf", "report", "--header-only",
+                                              "-i", self.input_file_name])
             result = output.decode("utf-8")
             if self.args.event_name:
                 result += "\nFocused event: " + self.args.event_name
@@ -144,6 +140,9 @@ class FlameGraphCLI:
             print(f"Error reading report header: {err}", file=sys.stderr)
             return ""
 
+    def trace_begin(self) -> None:
+        self.input_file_name = perf_input_name(perf_script_context) or "-"
+
     def trace_end(self) -> None:
         stacks_json = json.dumps(self.stack, default=lambda x: x.to_json())
 
@@ -167,7 +166,7 @@ js-d3-flame-graph or libjs-d3-flame-graph, specify an existing flame
 graph template (--template PATH) or use another output format (--format
 FORMAT).""",
                               file=sys.stderr)
-                        if self.args.input == "-":
+                        if self.input_file_name == "-":
                             print(
 """Not attempting to download Flame Graph template as script command line
 input is disabled due to using live mode. If you want to download the
@@ -248,8 +247,6 @@ if __name__ == "__main__":
                         default="blue-green",
                         help="flame graph color scheme",
                         choices=["blue-green", "orange"])
-    parser.add_argument("-i", "--input",
-                        help=argparse.SUPPRESS)
     parser.add_argument("--allow-download",
                         default=False,
                         action="store_true",
@@ -265,3 +262,4 @@ if __name__ == "__main__":
 
     process_event = cli.process_event
     trace_end = cli.trace_end
+    trace_begin = cli.trace_begin
-- 
2.52.0

Re: [PATCH 0/2] perf script flamegraph: Fix input file name errors

[Ian Rogers]

On Thu, Oct 1, 2026 at 11:20 AM Stephen Brennan
<stephen.s.brennan@oracle.com> wrote:
>
> The flamegraph.py script has a "-i" option which it uses in an attempt to
> know the input file name for the data it is processing. But perf itself is
> using that flag and not forwarding its value to the script, so the entire
> strategy won't work. It's further complicated by how the option processing
> is handled in the flamegraph-report script -- details in patch 2.
>
> This series introduces a helper to allow python scripts to see the input
> file name, and then fixes flamegraph.py. Testing with a variety of options
> like below shows that it is using the correct input files in most use cases
> I can think of:
>
> $ export PERF_EXEC_PATH=$(pwd)/tools/perf
>
> $ sudo -E tools/perf/perf script flamegraph -a -F999 -- sleep 1
> dumping data to flamegraph.html
>
> $ sudo -E tools/perf/perf script record flamegraph \
>                           -o myfile.data -a -F999 -- sleep 1
> [ perf record: Woken up 1 times to write data ]
> [ perf record: Captured and wrote 2.891 MB myfile.data (1832 samples) ]
>
> $ sudo -E tools/perf/perf script report flamegraph -i myfile.data \
>                                  -- -o myfile.html
> dumping data to myfile.html
>
> $ sudo -E tools/perf/perf script \
>        -s tools/perf/scripts/python/flamegraph.py -i myfile.data
> dumping data to flamegraph.html
>
> $ sudo -E tools/perf/perf script record flamegraph \
>        -o - -a -F999 -- sleep 1 \
>     | tools/perf/perf script report flamegraph -i - -- -o manual.html
> [ perf record: Woken up 1 times to write data ]
> [ perf record: Captured and wrote 2.936 MB - ]
> dumping data to manual.html

Hi Stephen,

Thank you for the contribution! Unfortunately we recently deleted all
of this code in this series:
https://lore.kernel.org/linux-perf-users/20260926062029.800743-1-irogers@google.com/
You can find the latest code in the perf-tools-next branch:
https://web.git.kernel.org/pub/scm/linux/kernel/git/perf/perf-tools-next.git/
The flamegraph code that now uses perf's python module is here:
https://web.git.kernel.org/pub/scm/linux/kernel/git/perf/perf-tools-next.git/tree/tools/perf/python/flamegraph.py?h=perf-tools-next
and we even have some tests now:
https://web.git.kernel.org/pub/scm/linux/kernel/git/perf/perf-tools-next.git/tree/tools/perf/tests/shell/test_flamegraph_python.sh?h=perf-tools-next

You may also like to play with the console flamegraph that is part of treport:
https://web.git.kernel.org/pub/scm/linux/kernel/git/perf/perf-tools-next.git/tree/tools/perf/python/treport.py?h=perf-tools-next

Thanks,
Ian


> Stephen Brennan (2):
>   tools: perf: add perf_input_name() helper
>   tools: perf: flamegraph.py: fix "Error reading report header"
>
>  .../perf/Documentation/perf-script-python.txt |  1 +
>  .../scripts/python/Perf-Trace-Util/Context.c  | 16 ++++++++++++++
>  tools/perf/scripts/python/flamegraph.py       | 22 +++++++++----------
>  3 files changed, 27 insertions(+), 12 deletions(-)
>
> --
> 2.52.0
>

Re: [PATCH 0/2] perf script flamegraph: Fix input file name errors

[Stephen Brennan]

Ian Rogers <irogers@google.com> writes:
> On Thu, Oct 1, 2026 at 11:20 AM Stephen Brennan
> <stephen.s.brennan@oracle.com> wrote:
>>
>> The flamegraph.py script has a "-i" option which it uses in an attempt to
>> know the input file name for the data it is processing. But perf itself is
>> using that flag and not forwarding its value to the script, so the entire
>> strategy won't work. It's further complicated by how the option processing
>> is handled in the flamegraph-report script -- details in patch 2.
>>
>> This series introduces a helper to allow python scripts to see the input
>> file name, and then fixes flamegraph.py. Testing with a variety of options
>> like below shows that it is using the correct input files in most use cases
>> I can think of:
>>
>> $ export PERF_EXEC_PATH=$(pwd)/tools/perf
>>
>> $ sudo -E tools/perf/perf script flamegraph -a -F999 -- sleep 1
>> dumping data to flamegraph.html
>>
>> $ sudo -E tools/perf/perf script record flamegraph \
>>                           -o myfile.data -a -F999 -- sleep 1
>> [ perf record: Woken up 1 times to write data ]
>> [ perf record: Captured and wrote 2.891 MB myfile.data (1832 samples) ]
>>
>> $ sudo -E tools/perf/perf script report flamegraph -i myfile.data \
>>                                  -- -o myfile.html
>> dumping data to myfile.html
>>
>> $ sudo -E tools/perf/perf script \
>>        -s tools/perf/scripts/python/flamegraph.py -i myfile.data
>> dumping data to flamegraph.html
>>
>> $ sudo -E tools/perf/perf script record flamegraph \
>>        -o - -a -F999 -- sleep 1 \
>>     | tools/perf/perf script report flamegraph -i - -- -o manual.html
>> [ perf record: Woken up 1 times to write data ]
>> [ perf record: Captured and wrote 2.936 MB - ]
>> dumping data to manual.html
>
> Hi Stephen,
>
> Thank you for the contribution! Unfortunately we recently deleted all
> of this code in this series:
> https://lore.kernel.org/linux-perf-users/20260926062029.800743-1-irogers@google.com/
> You can find the latest code in the perf-tools-next branch:
> https://web.git.kernel.org/pub/scm/linux/kernel/git/perf/perf-tools-next.git/

Hi Ian,
Thanks, I should have checked there first.

> The flamegraph code that now uses perf's python module is here:
> https://web.git.kernel.org/pub/scm/linux/kernel/git/perf/perf-tools-next.git/tree/tools/perf/python/flamegraph.py?h=perf-tools-next

That looks exciting! It makes things a lot easier to have perf as a
regular Python module rather than wrapping the interpreter. It will be
tricky for Oracle Linux which allows parallel installation of perf
versions, but I guess we made our own bed there :)

> and we even have some tests now:
> https://web.git.kernel.org/pub/scm/linux/kernel/git/perf/perf-tools-next.git/tree/tools/perf/tests/shell/test_flamegraph_python.sh?h=perf-tools-next
>
> You may also like to play with the console flamegraph that is part of treport:
> https://web.git.kernel.org/pub/scm/linux/kernel/git/perf/perf-tools-next.git/tree/tools/perf/python/treport.py?h=perf-tools-next

This is quite slick! I'll definitely be playing more with the python
module.

Thanks,
Stephen

> Thanks,
> Ian
>
>
>> Stephen Brennan (2):
>>   tools: perf: add perf_input_name() helper
>>   tools: perf: flamegraph.py: fix "Error reading report header"
>>
>>  .../perf/Documentation/perf-script-python.txt |  1 +
>>  .../scripts/python/Perf-Trace-Util/Context.c  | 16 ++++++++++++++
>>  tools/perf/scripts/python/flamegraph.py       | 22 +++++++++----------
>>  3 files changed, 27 insertions(+), 12 deletions(-)
>>
>> --
>> 2.52.0
>>