[PATCH 0/2] perf python: Add an example for sampling

[PATCH 0/2] perf python: Add an example for sampling

[Gautam Menghani]

Add an example for sampling events with python. Patch 1 adds support for
record_opts struct and patch 2 adds an example for sampling. The example
also demonstrates usage of the record_opts struct to customize the evsel
initialization from python.

Gautam Menghani (2):
  perf python: Add support for record_opts struct
  perf python: Add sampling.py as example for sampling

 tools/perf/python/sampling.py |  49 +++++++++
 tools/perf/util/python.c      | 186 +++++++++++++++++++++++++++++++++-
 2 files changed, 232 insertions(+), 3 deletions(-)
 create mode 100755 tools/perf/python/sampling.py

-- 
2.49.0

[PATCH 1/2] perf python: Add support for record_opts struct

[Gautam Menghani]

Add support for record_opts struct to allow python to control the
initialization of the evsels instead of using the current default
options.

Signed-off-by: Gautam Menghani <gautam@linux.ibm.com>
---
 tools/perf/util/python.c | 186 ++++++++++++++++++++++++++++++++++++++-
 1 file changed, 183 insertions(+), 3 deletions(-)

diff --git a/tools/perf/util/python.c b/tools/perf/util/python.c
index 2f28f71325a8..8537edbb3b0b 100644
--- a/tools/perf/util/python.c
+++ b/tools/perf/util/python.c
@@ -1045,6 +1045,169 @@ static int pyrf_evsel__setup_types(void)
 	return PyType_Ready(&pyrf_evsel__type);
 }
 
+struct pyrf_target {
+	PyObject_HEAD
+
+	struct target target;
+};
+
+static int pyrf_target__init(struct pyrf_target *target,
+				PyObject *args, PyObject *kwargs)
+{
+	static char *kwlist[] = { "pid", "tid", "cpu_list", "bpf_str", "system_wide", "uses_mmap",
+				"default_per_cpu", "per_thread", "use_bpf", "inherit",
+				"initial_delay", "attr_map", NULL };
+
+	if (!PyArg_ParseTupleAndKeywords(args, kwargs, "|ssssppppppis",
+					 kwlist, &(target->target.pid), &(target->target.tid),
+					 &(target->target.cpu_list), &(target->target.bpf_str),
+					 &(target->target.system_wide),
+					 &(target->target.uses_mmap),
+					 &(target->target.default_per_cpu),
+					 &(target->target.per_thread), &(target->target.use_bpf),
+					 &(target->target.inherit), &(target->target.initial_delay),
+					 &(target->target.attr_map)))
+		return -1;
+
+	return 0;
+}
+
+static void pyrf_target__delete(struct pyrf_target *target)
+{
+	Py_TYPE(target)->tp_free((PyObject *)target);
+}
+
+static const char pyrf_target__doc[] = PyDoc_STR("target object.");
+
+static PyTypeObject pyrf_target__type = {
+	PyVarObject_HEAD_INIT(NULL, 0)
+	.tp_name	= "perf.target",
+	.tp_basicsize	= sizeof(struct pyrf_target),
+	.tp_dealloc	= (destructor)pyrf_target__delete,
+	.tp_flags	= Py_TPFLAGS_DEFAULT|Py_TPFLAGS_BASETYPE,
+	.tp_doc		= pyrf_target__doc,
+	.tp_init	= (initproc)pyrf_target__init,
+};
+
+static int pyrf_target__setup_types(void)
+{
+	pyrf_target__type.tp_new = PyType_GenericNew;
+	return PyType_Ready(&pyrf_target__type);
+}
+
+struct pyrf_record_opts {
+	PyObject_HEAD
+
+	struct record_opts opts;
+};
+
+static int pyrf_record_opts__init(struct pyrf_record_opts *popts,
+				 PyObject *args, PyObject *kwargs)
+{
+	static char *kwlist[] = { "target", "inherit_stat", "no_buffering", "no_inherit",
+				"no_inherit_set", "no_samples", "raw_samples",
+				"sample_address", "sample_phys_addr", "sample_data_page_size",
+				"sample_code_page_size", "sample_weight", "sample_time",
+				"sample_time_set", "sample_cpu", "sample_identifier",
+				"sample_data_src", "period", "period_set", "running_time",
+				"full_auxtrace", "auxtrace_snapshot_mode",
+				"auxtrace_snapshot_on_exit", "auxtrace_sample_mode",
+				"record_namespaces", "record_cgroup", "record_switch_events",
+				"record_switch_events_set", "all_kernel", "all_user",
+				"kernel_callchains", "user_callchains", "tail_synthesize",
+				"overwrite", "ignore_missing_thread", "strict_freq", "sample_id",
+				"no_bpf_event", "kcore", "text_poke", "build_id", "freq",
+				"mmap_pages", "auxtrace_mmap_pages", "user_freq", "branch_stack",
+				"sample_intr_regs", "sample_user_regs", "default_interval",
+				"user_interval", "auxtrace_snapshot_size", "auxtrace_snapshot_opts",
+				"auxtrace_sample_opts", "sample_transaction", "use_clockid",
+				"clockid", "clockid_res_ns", "nr_cblocks", "affinity", "mmap_flush",
+				"comp_level", "nr_threads_synthesize", "ctl_fd", "ctl_fd_ack",
+				"ctl_fd_close", "synth", "threads_spec", "threads_user_spec",
+				"off_cpu_thresh_ns",  NULL };
+
+	if (!PyArg_ParseTupleAndKeywords(args, kwargs,
+					"|OppppppppppppppppppppppppppppppppppppppppIIIIIIIIIIssppiIiiiIIiipiisI",
+					 kwlist, &(popts->opts.target), &(popts->opts.inherit_stat),
+					 &(popts->opts.no_buffering), &(popts->opts.no_inherit),
+					 &(popts->opts.no_inherit_set), &(popts->opts.no_samples),
+					 &(popts->opts.raw_samples), &(popts->opts.sample_address),
+					 &(popts->opts.sample_phys_addr),
+					 &(popts->opts.sample_data_page_size),
+					 &(popts->opts.sample_code_page_size),
+					 &(popts->opts.sample_weight),
+					 &(popts->opts.sample_time), &(popts->opts.sample_time_set),
+					 &(popts->opts.sample_cpu),
+					 &(popts->opts.sample_identifier),
+					 &(popts->opts.sample_data_src), &(popts->opts.period),
+					 &(popts->opts.period_set), &(popts->opts.running_time),
+					 &(popts->opts.full_auxtrace),
+					 &(popts->opts.auxtrace_snapshot_mode),
+					 &(popts->opts.auxtrace_snapshot_on_exit),
+					 &(popts->opts.auxtrace_sample_mode),
+					 &(popts->opts.record_namespaces),
+					 &(popts->opts.record_cgroup),
+					 &(popts->opts.record_switch_events),
+					 &(popts->opts.record_switch_events_set),
+					 &(popts->opts.all_kernel), &(popts->opts.all_user),
+					 &(popts->opts.kernel_callchains),
+					 &(popts->opts.user_callchains),
+					 &(popts->opts.tail_synthesize),
+					 &(popts->opts.overwrite),
+					 &(popts->opts.ignore_missing_thread),
+					 &(popts->opts.strict_freq), &(popts->opts.sample_id),
+					 &(popts->opts.no_bpf_event), &(popts->opts.kcore),
+					 &(popts->opts.text_poke), &(popts->opts.build_id),
+					 &(popts->opts.freq), &(popts->opts.mmap_pages),
+					 &(popts->opts.auxtrace_mmap_pages),
+					 &(popts->opts.user_freq),
+					 &(popts->opts.branch_stack),
+					 &(popts->opts.sample_intr_regs),
+					 &(popts->opts.sample_user_regs),
+					 &(popts->opts.default_interval),
+					 &(popts->opts.user_interval),
+					 &(popts->opts.auxtrace_snapshot_size),
+					 &(popts->opts.auxtrace_snapshot_opts),
+					 &(popts->opts.auxtrace_sample_opts),
+					 &(popts->opts.sample_transaction),
+					 &(popts->opts.use_clockid),
+					 &(popts->opts.clockid), &(popts->opts.clockid_res_ns),
+					 &(popts->opts.nr_cblocks), &(popts->opts.affinity),
+					 &(popts->opts.mmap_flush), &(popts->opts.comp_level),
+					 &(popts->opts.nr_threads_synthesize),
+					 &(popts->opts.ctl_fd),
+					 &(popts->opts.ctl_fd_ack), &(popts->opts.ctl_fd_close),
+					 &(popts->opts.synth), &(popts->opts.threads_spec),
+					 &(popts->opts.threads_user_spec),
+					 &(popts->opts.off_cpu_thresh_ns)))
+		return -1;
+
+	return 0;
+}
+
+static const char pyrf_record_opts__doc[] = PyDoc_STR("perf record_opts object.");
+
+static void pyrf_record_opts__delete(struct pyrf_record_opts *perf_record_opts)
+{
+	Py_TYPE(perf_record_opts)->tp_free((PyObject *)perf_record_opts);
+}
+
+static PyTypeObject pyrf_record_opts__type = {
+	PyVarObject_HEAD_INIT(NULL, 0)
+	.tp_name	= "perf.record_opts",
+	.tp_basicsize	= sizeof(struct pyrf_record_opts),
+	.tp_dealloc	= (destructor)pyrf_record_opts__delete,
+	.tp_flags	= Py_TPFLAGS_DEFAULT|Py_TPFLAGS_BASETYPE,
+	.tp_doc		= pyrf_record_opts__doc,
+	.tp_init	= (initproc)pyrf_record_opts__init,
+};
+
+static int pyrf_record_opts__setup_types(void)
+{
+	pyrf_record_opts__type.tp_new = PyType_GenericNew;
+	return PyType_Ready(&pyrf_record_opts__type);
+}
+
 struct pyrf_evlist {
 	PyObject_HEAD
 
@@ -1263,7 +1426,7 @@ static PyObject *pyrf_evlist__close(struct pyrf_evlist *pevlist)
 	return Py_None;
 }
 
-static PyObject *pyrf_evlist__config(struct pyrf_evlist *pevlist)
+static PyObject *pyrf_evlist__config(struct pyrf_evlist *pevlist, PyObject *args, PyObject *kwargs)
 {
 	struct record_opts opts = {
 		.sample_time	     = true,
@@ -1281,8 +1444,17 @@ static PyObject *pyrf_evlist__config(struct pyrf_evlist *pevlist)
 		.no_buffering        = true,
 		.no_inherit          = true,
 	};
+	PyObject *popts = NULL;
+	static char *kwlist[] = { "record_opts", NULL };
 	struct evlist *evlist = &pevlist->evlist;
 
+	if (!PyArg_ParseTupleAndKeywords(args, kwargs, "|O", kwlist,
+					 &popts))
+		return NULL;
+
+	if (popts)
+		opts = ((struct pyrf_record_opts *) popts)->opts;
+
 	evlist__config(evlist, &opts, &callchain_param);
 	Py_INCREF(Py_None);
 	return Py_None;
@@ -1354,7 +1526,7 @@ static PyMethodDef pyrf_evlist__methods[] = {
 	{
 		.ml_name  = "config",
 		.ml_meth  = (PyCFunction)pyrf_evlist__config,
-		.ml_flags = METH_NOARGS,
+		.ml_flags = METH_VARARGS | METH_KEYWORDS,
 		.ml_doc	  = PyDoc_STR("Apply default record options to the evlist.")
 	},
 	{
@@ -1718,7 +1890,9 @@ PyMODINIT_FUNC PyInit_perf(void)
 	    pyrf_evsel__setup_types() < 0 ||
 	    pyrf_thread_map__setup_types() < 0 ||
 	    pyrf_cpu_map__setup_types() < 0 ||
-	    pyrf_counts_values__setup_types() < 0)
+	    pyrf_counts_values__setup_types() < 0 ||
+	    pyrf_target__setup_types() < 0 ||
+	    pyrf_record_opts__setup_types() < 0)
 		return module;
 
 	/* The page_size is placed in util object. */
@@ -1766,6 +1940,12 @@ PyMODINIT_FUNC PyInit_perf(void)
 	Py_INCREF(&pyrf_counts_values__type);
 	PyModule_AddObject(module, "counts_values", (PyObject *)&pyrf_counts_values__type);
 
+	Py_INCREF(&pyrf_target__type);
+	PyModule_AddObject(module, "target", (PyObject *)&pyrf_target__type);
+
+	Py_INCREF(&pyrf_record_opts__type);
+	PyModule_AddObject(module, "record_opts", (PyObject *)&pyrf_record_opts__type);
+
 	dict = PyModule_GetDict(module);
 	if (dict == NULL)
 		goto error;
-- 
2.49.0

[PATCH 2/2] perf python: Add sampling.py as example for sampling

[Gautam Menghani]

Add sampling.py - a python version of sampling.c to demonstrate sampling
events.

Sample output:
```
$ sudo ./sampling.py
libperf: mmap_per_cpu: nr cpu values 8 nr threads 1
libperf: idx 0: mmapping fd 3
libperf: idx 1: mmapping fd 4
libperf: idx 2: mmapping fd 5
libperf: idx 3: mmapping fd 6
libperf: idx 4: mmapping fd 7
libperf: idx 5: mmapping fd 8
libperf: idx 6: mmapping fd 9
libperf: idx 7: mmapping fd 10
cpu: 0   pid: 4168   tid: 4168   ip: 0x7fb274150c15       period: 345012
cpu: 1   pid: 57137  tid: 57137  ip: 0xffffffffc0745a2c   period: 286666
cpu: 2   pid: 6247   tid: 6247   ip: 0x7fe10a883988       period: 391180
cpu: 3   pid: 0      tid: 0      ip: 0xffffffffa5413e67   period: 245301
cpu: 4   pid: 4168   tid: 4194   ip: 0xffffffffc086a1cc   period: 269605
cpu: 5   pid: 0      tid: 0      ip: 0xffffffffa53bfcb1   period: 90978
cpu: 6   pid: 0      tid: 0      ip: 0xffffffffa6469333   period: 309112
```

Signed-off-by: Gautam Menghani <gautam@linux.ibm.com>
---
 tools/perf/python/sampling.py | 49 +++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)
 create mode 100755 tools/perf/python/sampling.py

diff --git a/tools/perf/python/sampling.py b/tools/perf/python/sampling.py
new file mode 100755
index 000000000000..b5f4e1362c63
--- /dev/null
+++ b/tools/perf/python/sampling.py
@@ -0,0 +1,49 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: GPL-2.0
+# -*- python -*-
+# -*- coding: utf-8 -*-
+
+import perf
+import time
+
+def main():
+    cpus    = perf.cpu_map()
+    threads = perf.thread_map(-1)
+
+    evlist = perf.parse_events('cpu-cycles', cpus, threads)
+
+    tgt = perf.target(uses_mmap = True, default_per_cpu = True)
+    opts = perf.record_opts(freq=1000, target=tgt, sample_time=True,
+                            sample_cpu=True, no_buffering=True, no_inherit=True)
+    for ev in evlist:
+        ev.tracking = False
+        ev.read_format = 0
+        ev.sample_type = perf.SAMPLE_IP|perf.SAMPLE_TID|perf.SAMPLE_CPU|perf.SAMPLE_PERIOD
+    evlist.config(opts)
+
+    evlist.open()
+    evlist.mmap()
+
+    evlist.enable()
+    time.sleep(2)
+    evlist.disable()
+
+    done = False
+    while done is False:
+        for cpu in cpus:
+            event = evlist.read_on_cpu(cpu)
+            if event is None:
+                done = True
+                break
+
+            if not isinstance(event, perf.sample_event):
+                continue
+
+            print(f"cpu: {event.sample_cpu:<3} pid: {event.sample_pid:<6} "
+                    f"tid: {event.sample_tid:<6} ip: {hex(event.sample_ip):<20} "
+                    f"period: {event.sample_period:<20}")
+
+    evlist.close()
+
+if __name__ == '__main__':
+    main()
-- 
2.49.0

Re: [PATCH 0/2] perf python: Add an example for sampling

[Gautam Menghani]

Hello,

Please do review this series and let me know if any changes are needed.

Thanks,
Gautam

Re: [PATCH 0/2] perf python: Add an example for sampling

[Gautam Menghani]

Hi,
Gentle ping. Please review this series and let me know if any changes
are needed.

Thanks,
Gautam

Re: [PATCH 0/2] perf python: Add an example for sampling

[Gautam Menghani]

Hi Ian/Arnaldo,

Can you please review this series and let me know if any changes are
needed?

Thanks,
Gautam

Re: [PATCH 0/2] perf python: Add an example for sampling

[Arnaldo Carvalho de Melo]

On Tue, Sep 16, 2025 at 07:00:48PM +0530, Gautam Menghani wrote:
> Hi Ian/Arnaldo,
> 
> Can you please review this series and let me know if any changes are
> needed?

Looking at it now, sry for the delay,

- Arnaldo

Re: [PATCH 0/2] perf python: Add an example for sampling

[Ian Rogers]

On Tue, Sep 16, 2025 at 12:25 PM Arnaldo Carvalho de Melo
<acme@kernel.org> wrote:
>
> On Tue, Sep 16, 2025 at 07:00:48PM +0530, Gautam Menghani wrote:
> > Hi Ian/Arnaldo,
> >
> > Can you please review this series and let me know if any changes are
> > needed?
>
> Looking at it now, sry for the delay,

I think the patches look good. I'm a little concerned that the python
APIs are a chance to do something better than the C APIs that have
evolved. For example, we removed UID out of target recently [1] as the
BPF alternative was better. Had this patch come earlier then it seems
likely we'd have had target with UIDs. I wonder rather than having a
kwlist of:

+ static char *kwlist[] = { "target", "inherit_stat", "no_buffering",
"no_inherit",
+ "no_inherit_set", "no_samples", "raw_samples",
+ "sample_address", "sample_phys_addr", "sample_data_page_size",
+ "sample_code_page_size", "sample_weight", "sample_time",
+ "sample_time_set", "sample_cpu", "sample_identifier",
+ "sample_data_src", "period", "period_set", "running_time",
+ "full_auxtrace", "auxtrace_snapshot_mode",
+ "auxtrace_snapshot_on_exit", "auxtrace_sample_mode",
+ "record_namespaces", "record_cgroup", "record_switch_events",
+ "record_switch_events_set", "all_kernel", "all_user",
+ "kernel_callchains", "user_callchains", "tail_synthesize",
+ "overwrite", "ignore_missing_thread", "strict_freq", "sample_id",
+ "no_bpf_event", "kcore", "text_poke", "build_id", "freq",
+ "mmap_pages", "auxtrace_mmap_pages", "user_freq", "branch_stack",
+ "sample_intr_regs", "sample_user_regs", "default_interval",
+ "user_interval", "auxtrace_snapshot_size", "auxtrace_snapshot_opts",
+ "auxtrace_sample_opts", "sample_transaction", "use_clockid",
+ "clockid", "clockid_res_ns", "nr_cblocks", "affinity", "mmap_flush",
+ "comp_level", "nr_threads_synthesize", "ctl_fd", "ctl_fd_ack",
+ "ctl_fd_close", "synth", "threads_spec", "threads_user_spec",
+ "off_cpu_thresh_ns",  NULL };

but then just using this subset:

+    opts = perf.record_opts(freq=1000, target=tgt, sample_time=True,
+                            sample_cpu=True, no_buffering=True,
no_inherit=True)

The kwlist should be kept to just those necessary values for the
example to work? I kind of see this as Arnaldo's baby, so he may just
want everything, so this needn't be a blocker.

Bigger picture I wonder about migrating the `perf script` code to just
being regular python programs like the example here. I sent out
deprecating the libperl code to this ends (looking for reviews):
https://lore.kernel.org/linux-perf-users/20250908181918.3533480-1-irogers@google.com/
The issue is that `perf script` being the main thread inhibits things
like textual running until trace_end. This means we can't do things
like incremental loading support. We may want to make the perf events
support something like an asyncio interface for that.

Refactoring that support will likely raise backward compatibility
concerns. It'd be a really nice thing to do as the API has some fairly
major overheads like turning everything in a sample into a Dict
whether needed or not:
https://web.git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/perf/util/scripting-engines/trace-event-python.c#n838
I mention this just to say why I'd like to minimize the API when possible.

Thanks,
Ian

[1] https://lore.kernel.org/r/20250604174545.2853620-10-irogers@google.com

Re: [PATCH 0/2] perf python: Add an example for sampling

[Arnaldo Carvalho de Melo]

On Tue, Sep 16, 2025 at 01:07:43PM -0700, Ian Rogers wrote:
> On Tue, Sep 16, 2025 at 12:25 PM Arnaldo Carvalho de Melo
> <acme@kernel.org> wrote:
> >
> > On Tue, Sep 16, 2025 at 07:00:48PM +0530, Gautam Menghani wrote:
> > > Hi Ian/Arnaldo,
> > >
> > > Can you please review this series and let me know if any changes are
> > > needed?
> >
> > Looking at it now, sry for the delay,
> 
> I think the patches look good. I'm a little concerned that the python
> APIs are a chance to do something better than the C APIs that have
> evolved. For example, we removed UID out of target recently [1] as the
> BPF alternative was better. Had this patch come earlier then it seems
> likely we'd have had target with UIDs. I wonder rather than having a
> kwlist of:
> 
> + static char *kwlist[] = { "target", "inherit_stat", "no_buffering",
> "no_inherit",
> + "no_inherit_set", "no_samples", "raw_samples",
> + "sample_address", "sample_phys_addr", "sample_data_page_size",
> + "sample_code_page_size", "sample_weight", "sample_time",
> + "sample_time_set", "sample_cpu", "sample_identifier",
> + "sample_data_src", "period", "period_set", "running_time",
> + "full_auxtrace", "auxtrace_snapshot_mode",
> + "auxtrace_snapshot_on_exit", "auxtrace_sample_mode",
> + "record_namespaces", "record_cgroup", "record_switch_events",
> + "record_switch_events_set", "all_kernel", "all_user",
> + "kernel_callchains", "user_callchains", "tail_synthesize",
> + "overwrite", "ignore_missing_thread", "strict_freq", "sample_id",
> + "no_bpf_event", "kcore", "text_poke", "build_id", "freq",
> + "mmap_pages", "auxtrace_mmap_pages", "user_freq", "branch_stack",
> + "sample_intr_regs", "sample_user_regs", "default_interval",
> + "user_interval", "auxtrace_snapshot_size", "auxtrace_snapshot_opts",
> + "auxtrace_sample_opts", "sample_transaction", "use_clockid",
> + "clockid", "clockid_res_ns", "nr_cblocks", "affinity", "mmap_flush",
> + "comp_level", "nr_threads_synthesize", "ctl_fd", "ctl_fd_ack",
> + "ctl_fd_close", "synth", "threads_spec", "threads_user_spec",
> + "off_cpu_thresh_ns",  NULL };
> 
> but then just using this subset:
> 
> +    opts = perf.record_opts(freq=1000, target=tgt, sample_time=True,
> +                            sample_cpu=True, no_buffering=True,
> no_inherit=True)
> 
> The kwlist should be kept to just those necessary values for the
> example to work? I kind of see this as Arnaldo's baby, so he may just
> want everything, so this needn't be a blocker.
> 
> Bigger picture I wonder about migrating the `perf script` code to just
> being regular python programs like the example here.

You mean:

acme@number:~/git/perf-tools-next$ ls -la tools/perf/scripts/python/
total 452
drwxr-xr-x. 1 acme acme    902 Aug 20 14:18 .
drwxr-xr-x. 1 acme acme     30 Sep 17 09:27 ..
-rwxr-xr-x. 1 acme acme  11865 Aug 20 14:06 arm-cs-trace-disasm.py
drwxr-xr-x. 1 acme acme   1640 Aug 20 14:18 bin
-rw-r--r--. 1 acme acme   2461 Apr 16 10:06 check-perf-trace.py
-rw-r--r--. 1 acme acme   7923 Apr 16 10:06 compaction-times.py
-rw-r--r--. 1 acme acme   7497 Apr 16 10:06 event_analyzing_sample.py
-rwxr-xr-x. 1 acme acme 157369 Aug 20 14:18 exported-sql-viewer.py
-rw-r--r--. 1 acme acme  39845 Apr 16 10:06 export-to-postgresql.py
-rw-r--r--. 1 acme acme  24671 Apr 16 10:06 export-to-sqlite.py
-rw-r--r--. 1 acme acme   2173 Apr 16 10:06 failed-syscalls-by-pid.py
-rwxr-xr-x. 1 acme acme  10377 Aug 20 14:18 flamegraph.py
-rw-r--r--. 1 acme acme   1717 Apr 16 10:06 futex-contention.py
-rw-r--r--. 1 acme acme  13302 Apr 16 10:06 gecko.py
-rw-r--r--. 1 acme acme  14636 Apr 16 10:06 intel-pt-events.py
-rw-r--r--. 1 acme acme   3395 Apr 16 10:06 libxed.py
-rw-r--r--. 1 acme acme   4230 Aug 20 14:13 mem-phys-addr.py
-rw-r--r--. 1 acme acme  15420 Aug 20 14:05 netdev-times.py
-rwxr-xr-x. 1 acme acme   1833 Apr 16 10:06 net_dropmonitor.py
-rwxr-xr-x. 1 acme acme  30683 Aug 20 14:05 parallel-perf.py
drwxr-xr-x. 1 acme acme     34 Sep 17 09:27 Perf-Trace-Util
-rw-r--r--. 1 acme acme   4509 Apr 16 10:06 powerpc-hcalls.py
-rw-r--r--. 1 acme acme  12095 Apr 16 10:06 sched-migration.py
-rw-r--r--. 1 acme acme   2183 Apr 16 10:06 sctop.py
-rwxr-xr-x. 1 acme acme   4408 Apr 16 10:06 stackcollapse.py
-rw-r--r--. 1 acme acme   2444 Apr 16 10:06 stat-cpi.py
-rw-r--r--. 1 acme acme   2055 Apr 16 10:06 syscall-counts-by-pid.py
-rw-r--r--. 1 acme acme   1673 Apr 16 10:06 syscall-counts.py
-rwxr-xr-x. 1 acme acme  34014 Apr 16 10:06 task-analyzer.py
acme@number:~/git/perf-tools-next$

And then make:

acme@number:~/git/perf-tools-next$ perf script -l
List of available trace scripts:
  compaction-times [-h] [-u] [-p|-pv] [-t | [-m] [-fs] [-ms]] [pid|pid-range|comm-regex] display time taken by mm compaction
  event_analyzing_sample               analyze all perf samples
  export-to-postgresql [database name] [columns] [calls] export perf data to a postgresql database
  export-to-sqlite [database name] [columns] [calls] export perf data to a sqlite3 database
  failed-syscalls-by-pid [comm]        system-wide failed syscalls, by pid
  flamegraph                           create flame graphs
  futex-contention                     futext contention measurement
  gecko                                create firefox gecko profile json format from perf.data
  intel-pt-events                      print Intel PT Events including Power Events and PTWRITE
  mem-phys-addr                        resolve physical address samples
  net_dropmonitor                      display a table of dropped frames
  netdev-times [tx] [rx] [dev=] [debug] display a process of packet and processing time
  powerpc-hcalls                       
  sched-migration                      sched migration overview
  sctop [comm] [interval]              syscall top
  stackcollapse                        produce callgraphs in short form for scripting use
  syscall-counts-by-pid [comm]         system-wide syscall counts, by pid
  syscall-counts [comm]                system-wide syscall counts
  task-analyzer                        analyze timings of tasks
  failed-syscalls [comm]               system-wide failed syscalls
  rw-by-file <comm>                    r/w activity for a program, by file
  rw-by-pid                            system-wide r/w activity
  rwtop [interval]                     system-wide r/w top
  wakeup-latency                       system-wide min/max/avg wakeup latency
acme@number:~/git/perf-tools-next$

And make:

perf script rwtop

Just call 'python PATH_TO_PYTHON_SCRIPTS/rwtop.py' transparently?

That looks interesting indeed, that way we would stop linking with
libpython, etc.

I wonder if there are out of tree scripts using the current tools/perf/util/scripting-engines/trace-event-python.c
mechanism...

But even that can fallback to a python based mechanism, right?

Import the script, if it has a given structure, use the new way, if not,
call a glue that reads the events and feed to the old style code.

Seems doable and would save code on the main perf binary and headaches
with the libpython and libperl build processes.

- Arnaldo

> I sent out
> deprecating the libperl code to this ends (looking for reviews):
> https://lore.kernel.org/linux-perf-users/20250908181918.3533480-1-irogers@google.com/
> The issue is that `perf script` being the main thread inhibits things
> like textual running until trace_end. This means we can't do things
> like incremental loading support. We may want to make the perf events
> support something like an asyncio interface for that.
> 
> Refactoring that support will likely raise backward compatibility
> concerns. It'd be a really nice thing to do as the API has some fairly
> major overheads like turning everything in a sample into a Dict
> whether needed or not:
> https://web.git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/perf/util/scripting-engines/trace-event-python.c#n838
> I mention this just to say why I'd like to minimize the API when possible.
> 
> Thanks,
> Ian
> 
> [1] https://lore.kernel.org/r/20250604174545.2853620-10-irogers@google.com

Re: [PATCH 0/2] perf python: Add an example for sampling

[Ian Rogers]

On Wed, Sep 17, 2025 at 5:37 AM Arnaldo Carvalho de Melo
<acme@kernel.org> wrote:
>
> On Tue, Sep 16, 2025 at 01:07:43PM -0700, Ian Rogers wrote:
> > On Tue, Sep 16, 2025 at 12:25 PM Arnaldo Carvalho de Melo
> > <acme@kernel.org> wrote:
> > >
> > > On Tue, Sep 16, 2025 at 07:00:48PM +0530, Gautam Menghani wrote:
> > > > Hi Ian/Arnaldo,
> > > >
> > > > Can you please review this series and let me know if any changes are
> > > > needed?
> > >
> > > Looking at it now, sry for the delay,
> >
> > I think the patches look good. I'm a little concerned that the python
> > APIs are a chance to do something better than the C APIs that have
> > evolved. For example, we removed UID out of target recently [1] as the
> > BPF alternative was better. Had this patch come earlier then it seems
> > likely we'd have had target with UIDs. I wonder rather than having a
> > kwlist of:
> >
> > + static char *kwlist[] = { "target", "inherit_stat", "no_buffering",
> > "no_inherit",
> > + "no_inherit_set", "no_samples", "raw_samples",
> > + "sample_address", "sample_phys_addr", "sample_data_page_size",
> > + "sample_code_page_size", "sample_weight", "sample_time",
> > + "sample_time_set", "sample_cpu", "sample_identifier",
> > + "sample_data_src", "period", "period_set", "running_time",
> > + "full_auxtrace", "auxtrace_snapshot_mode",
> > + "auxtrace_snapshot_on_exit", "auxtrace_sample_mode",
> > + "record_namespaces", "record_cgroup", "record_switch_events",
> > + "record_switch_events_set", "all_kernel", "all_user",
> > + "kernel_callchains", "user_callchains", "tail_synthesize",
> > + "overwrite", "ignore_missing_thread", "strict_freq", "sample_id",
> > + "no_bpf_event", "kcore", "text_poke", "build_id", "freq",
> > + "mmap_pages", "auxtrace_mmap_pages", "user_freq", "branch_stack",
> > + "sample_intr_regs", "sample_user_regs", "default_interval",
> > + "user_interval", "auxtrace_snapshot_size", "auxtrace_snapshot_opts",
> > + "auxtrace_sample_opts", "sample_transaction", "use_clockid",
> > + "clockid", "clockid_res_ns", "nr_cblocks", "affinity", "mmap_flush",
> > + "comp_level", "nr_threads_synthesize", "ctl_fd", "ctl_fd_ack",
> > + "ctl_fd_close", "synth", "threads_spec", "threads_user_spec",
> > + "off_cpu_thresh_ns",  NULL };
> >
> > but then just using this subset:
> >
> > +    opts = perf.record_opts(freq=1000, target=tgt, sample_time=True,
> > +                            sample_cpu=True, no_buffering=True,
> > no_inherit=True)
> >
> > The kwlist should be kept to just those necessary values for the
> > example to work? I kind of see this as Arnaldo's baby, so he may just
> > want everything, so this needn't be a blocker.
> >
> > Bigger picture I wonder about migrating the `perf script` code to just
> > being regular python programs like the example here.
>
> You mean:
>
> acme@number:~/git/perf-tools-next$ ls -la tools/perf/scripts/python/
> total 452
> drwxr-xr-x. 1 acme acme    902 Aug 20 14:18 .
> drwxr-xr-x. 1 acme acme     30 Sep 17 09:27 ..
> -rwxr-xr-x. 1 acme acme  11865 Aug 20 14:06 arm-cs-trace-disasm.py
> drwxr-xr-x. 1 acme acme   1640 Aug 20 14:18 bin
> -rw-r--r--. 1 acme acme   2461 Apr 16 10:06 check-perf-trace.py
> -rw-r--r--. 1 acme acme   7923 Apr 16 10:06 compaction-times.py
> -rw-r--r--. 1 acme acme   7497 Apr 16 10:06 event_analyzing_sample.py
> -rwxr-xr-x. 1 acme acme 157369 Aug 20 14:18 exported-sql-viewer.py
> -rw-r--r--. 1 acme acme  39845 Apr 16 10:06 export-to-postgresql.py
> -rw-r--r--. 1 acme acme  24671 Apr 16 10:06 export-to-sqlite.py
> -rw-r--r--. 1 acme acme   2173 Apr 16 10:06 failed-syscalls-by-pid.py
> -rwxr-xr-x. 1 acme acme  10377 Aug 20 14:18 flamegraph.py
> -rw-r--r--. 1 acme acme   1717 Apr 16 10:06 futex-contention.py
> -rw-r--r--. 1 acme acme  13302 Apr 16 10:06 gecko.py
> -rw-r--r--. 1 acme acme  14636 Apr 16 10:06 intel-pt-events.py
> -rw-r--r--. 1 acme acme   3395 Apr 16 10:06 libxed.py
> -rw-r--r--. 1 acme acme   4230 Aug 20 14:13 mem-phys-addr.py
> -rw-r--r--. 1 acme acme  15420 Aug 20 14:05 netdev-times.py
> -rwxr-xr-x. 1 acme acme   1833 Apr 16 10:06 net_dropmonitor.py
> -rwxr-xr-x. 1 acme acme  30683 Aug 20 14:05 parallel-perf.py
> drwxr-xr-x. 1 acme acme     34 Sep 17 09:27 Perf-Trace-Util
> -rw-r--r--. 1 acme acme   4509 Apr 16 10:06 powerpc-hcalls.py
> -rw-r--r--. 1 acme acme  12095 Apr 16 10:06 sched-migration.py
> -rw-r--r--. 1 acme acme   2183 Apr 16 10:06 sctop.py
> -rwxr-xr-x. 1 acme acme   4408 Apr 16 10:06 stackcollapse.py
> -rw-r--r--. 1 acme acme   2444 Apr 16 10:06 stat-cpi.py
> -rw-r--r--. 1 acme acme   2055 Apr 16 10:06 syscall-counts-by-pid.py
> -rw-r--r--. 1 acme acme   1673 Apr 16 10:06 syscall-counts.py
> -rwxr-xr-x. 1 acme acme  34014 Apr 16 10:06 task-analyzer.py
> acme@number:~/git/perf-tools-next$
>
> And then make:
>
> acme@number:~/git/perf-tools-next$ perf script -l
> List of available trace scripts:
>   compaction-times [-h] [-u] [-p|-pv] [-t | [-m] [-fs] [-ms]] [pid|pid-range|comm-regex] display time taken by mm compaction
>   event_analyzing_sample               analyze all perf samples
>   export-to-postgresql [database name] [columns] [calls] export perf data to a postgresql database
>   export-to-sqlite [database name] [columns] [calls] export perf data to a sqlite3 database
>   failed-syscalls-by-pid [comm]        system-wide failed syscalls, by pid
>   flamegraph                           create flame graphs
>   futex-contention                     futext contention measurement
>   gecko                                create firefox gecko profile json format from perf.data
>   intel-pt-events                      print Intel PT Events including Power Events and PTWRITE
>   mem-phys-addr                        resolve physical address samples
>   net_dropmonitor                      display a table of dropped frames
>   netdev-times [tx] [rx] [dev=] [debug] display a process of packet and processing time
>   powerpc-hcalls
>   sched-migration                      sched migration overview
>   sctop [comm] [interval]              syscall top
>   stackcollapse                        produce callgraphs in short form for scripting use
>   syscall-counts-by-pid [comm]         system-wide syscall counts, by pid
>   syscall-counts [comm]                system-wide syscall counts
>   task-analyzer                        analyze timings of tasks
>   failed-syscalls [comm]               system-wide failed syscalls
>   rw-by-file <comm>                    r/w activity for a program, by file
>   rw-by-pid                            system-wide r/w activity
>   rwtop [interval]                     system-wide r/w top
>   wakeup-latency                       system-wide min/max/avg wakeup latency
> acme@number:~/git/perf-tools-next$
>
> And make:
>
> perf script rwtop
>
> Just call 'python PATH_TO_PYTHON_SCRIPTS/rwtop.py' transparently?

Yeah, that's it. The perf script libpython stuff is just providing
trace_begin, process_event and trace_end. Using the sampling
mechanism, as shown in Gautum's patches, it is pretty easy to migrate
them to being stand alone bits of python.

> That looks interesting indeed, that way we would stop linking with
> libpython, etc.
>
> I wonder if there are out of tree scripts using the current tools/perf/util/scripting-engines/trace-event-python.c
> mechanism...
>
> But even that can fallback to a python based mechanism, right?

I think so. Like I said about the use of a Dict for process_event, we
may want to streamline things so there is a tension with what the API
should be and compatibility. We can always have 2 APIs and try to
deprecate one of them.

> Import the script, if it has a given structure, use the new way, if not,
> call a glue that reads the events and feed to the old style code.
>
> Seems doable and would save code on the main perf binary and headaches
> with the libpython and libperl build processes.

So I see this for libpython, and I think it'd be pretty cool if we
could have things work like this for say "perf script ilist" and
Alice's textual flamegraph work. I worry what the work for libperl
would be like and whether it is worth it (hence sending the patch to
at least start to make it opt-in rather than opt-out).

Do you need my tags for these changes or wdyt about making the
kwlist/API surface smaller?

Thanks!
Ian

> - Arnaldo
>
> > I sent out
> > deprecating the libperl code to this ends (looking for reviews):
> > https://lore.kernel.org/linux-perf-users/20250908181918.3533480-1-irogers@google.com/
> > The issue is that `perf script` being the main thread inhibits things
> > like textual running until trace_end. This means we can't do things
> > like incremental loading support. We may want to make the perf events
> > support something like an asyncio interface for that.
> >
> > Refactoring that support will likely raise backward compatibility
> > concerns. It'd be a really nice thing to do as the API has some fairly
> > major overheads like turning everything in a sample into a Dict
> > whether needed or not:
> > https://web.git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/perf/util/scripting-engines/trace-event-python.c#n838
> > I mention this just to say why I'd like to minimize the API when possible.
> >
> > Thanks,
> > Ian
> >
> > [1] https://lore.kernel.org/r/20250604174545.2853620-10-irogers@google.com

Re: [PATCH 0/2] perf python: Add an example for sampling

[Arnaldo Carvalho de Melo]

On Wed, Sep 17, 2025 at 08:29:24AM -0700, Ian Rogers wrote:
> On Wed, Sep 17, 2025 at 5:37 AM Arnaldo Carvalho de Melo <acme@kernel.org> wrote:
> > And make:

> > perf script rwtop

> > Just call 'python PATH_TO_PYTHON_SCRIPTS/rwtop.py' transparently?
 
> Yeah, that's it. The perf script libpython stuff is just providing
> trace_begin, process_event and trace_end. Using the sampling
> mechanism, as shown in Gautum's patches, it is pretty easy to migrate
> them to being stand alone bits of python.
 
> > That looks interesting indeed, that way we would stop linking with
> > libpython, etc.

> > I wonder if there are out of tree scripts using the current tools/perf/util/scripting-engines/trace-event-python.c
> > mechanism...

> > But even that can fallback to a python based mechanism, right?

> I think so. Like I said about the use of a Dict for process_event, we
> may want to streamline things so there is a tension with what the API
> should be and compatibility. We can always have 2 APIs and try to
> deprecate one of them.

> > Import the script, if it has a given structure, use the new way, if not,
> > call a glue that reads the events and feed to the old style code.

> > Seems doable and would save code on the main perf binary and headaches
> > with the libpython and libperl build processes.

> So I see this for libpython, and I think it'd be pretty cool if we
> could have things work like this for say "perf script ilist" and

I think we could even try to, not having a builtin-ilist.c convert
'perf ilist' to 'perf script ilist' automagically.

> Alice's textual flamegraph work. I worry what the work for libperl
> would be like and whether it is worth it (hence sending the patch to
> at least start to make it opt-in rather than opt-out).

Maybe we should be a tad more cautious and start with emitting a warning
that "libperl is deprecated (holler if you disagree if you use it!)" and
then make it opt-in, and then remove it.

> Do you need my tags for these changes or wdyt about making the
> kwlist/API surface smaller?

Lemme look at the original post...

- Arnaldo

Re: [PATCH 0/2] perf python: Add an example for sampling

[Ian Rogers]

On Wed, Sep 17, 2025 at 9:41 AM Arnaldo Carvalho de Melo
<acme@kernel.org> wrote:
>
> On Wed, Sep 17, 2025 at 08:29:24AM -0700, Ian Rogers wrote:
> > On Wed, Sep 17, 2025 at 5:37 AM Arnaldo Carvalho de Melo <acme@kernel.org> wrote:
> > > And make:
>
> > > perf script rwtop
>
> > > Just call 'python PATH_TO_PYTHON_SCRIPTS/rwtop.py' transparently?
>
> > Yeah, that's it. The perf script libpython stuff is just providing
> > trace_begin, process_event and trace_end. Using the sampling
> > mechanism, as shown in Gautum's patches, it is pretty easy to migrate
> > them to being stand alone bits of python.
>
> > > That looks interesting indeed, that way we would stop linking with
> > > libpython, etc.
>
> > > I wonder if there are out of tree scripts using the current tools/perf/util/scripting-engines/trace-event-python.c
> > > mechanism...
>
> > > But even that can fallback to a python based mechanism, right?
>
> > I think so. Like I said about the use of a Dict for process_event, we
> > may want to streamline things so there is a tension with what the API
> > should be and compatibility. We can always have 2 APIs and try to
> > deprecate one of them.
>
> > > Import the script, if it has a given structure, use the new way, if not,
> > > call a glue that reads the events and feed to the old style code.
>
> > > Seems doable and would save code on the main perf binary and headaches
> > > with the libpython and libperl build processes.
>
> > So I see this for libpython, and I think it'd be pretty cool if we
> > could have things work like this for say "perf script ilist" and
>
> I think we could even try to, not having a builtin-ilist.c convert
> 'perf ilist' to 'perf script ilist' automagically.
>
> > Alice's textual flamegraph work. I worry what the work for libperl
> > would be like and whether it is worth it (hence sending the patch to
> > at least start to make it opt-in rather than opt-out).
>
> Maybe we should be a tad more cautious and start with emitting a warning
> that "libperl is deprecated (holler if you disagree if you use it!)" and
> then make it opt-in, and then remove it.

Not sure I follow, let's move the conversation to that patch.

> > Do you need my tags for these changes or wdyt about making the
> > kwlist/API surface smaller?
>
> Lemme look at the original post...

Thanks,
Ian

> - Arnaldo