Skip to contentSkip to conversation

perf bpf-filter: Improve error messages

PATCH Applied Namhyung Kim 2 participants 4 messages Jun 4, 2025 – Jun 10, 2025 perf events

lore
Share & tools
lore

Namhyung Kim

author maintainer
#0 lore raw

PATCH v2 1/1 perf bpf-filter: Improve error messages

The BPF filter needs libbpf/BPF-skeleton support and root privilege. Add error messages to help users understand the problem easily.

When it's not build with BPF support (make BUILD_BPF_SKEL=0).

  $ sudo perf record -e cycles --filter "pid != 0" true
  Error: BPF filter is requested but perf is not built with BPF.
  	Please make sure to build with libbpf and BPF skeleton.

Usage: perf record [<options>] [<command>]
or: perf record [<options>] -- <command> [<options>]

--filter <filter>
event filter

When it supports BPF but runs without root or CAP_BPF. Note that it also checks pinned BPF filters.

  $ perf record -e cycles --filter "pid != 0" -o /dev/null true
  Error: BPF filter only works for users with the CAP_BPF capability!
  	Please run 'perf record --setup-filter pin' as root first.

Usage: perf record [<options>] [<command>]
or: perf record [<options>] -- <command> [<options>]

--filter <filter>
event filter

---
v2) change fprintf() -> pr_err() (Ian)

 tools/perf/util/bpf-filter.c | 28 ++++++++++++++++++++++++++++
 tools/perf/util/bpf-filter.h |  3 +++
 tools/perf/util/cap.c        |  1 -
 tools/perf/util/cap.h        |  5 +++++
 4 files changed, 36 insertions(+), 1 deletion(-)
tools/perf/util/bpf-filter.c +28 -0
index a4fdf6911ec1c32e..92e2f054b45e91dd 100644
@@ -52,6 +52,7 @@
 #include <internal/xyarray.h>
 #include <perf/threadmap.h>
 
+#include "util/cap.h"
 #include "util/debug.h"
 #include "util/evsel.h"
 #include "util/target.h"
@@ -618,11 +619,38 @@ struct perf_bpf_filter_expr *perf_bpf_filter_expr__new(enum perf_bpf_filter_term
 	return expr;
 }
 
+static bool check_bpf_filter_capable(void)
+{
+	bool used_root;
+
+	if (perf_cap__capable(CAP_BPF, &used_root))
+		return true;
+
+	if (!used_root) {
+		/* Check if root already pinned the filter programs and maps */
+		int fd = get_pinned_fd("filters");
+
+		if (fd >= 0) {
+			close(fd);
+			return true;
+		}
+	}
+
+	pr_err("Error: BPF filter only works for %s!\n"
+	       "\tPlease run 'perf record --setup-filter pin' as root first.\n",
+	       used_root ? "root" : "users with the CAP_BPF capability");
+
+	return false;
+}
+
 int perf_bpf_filter__parse(struct list_head *expr_head, const char *str)
 {
 	YY_BUFFER_STATE buffer;
 	int ret;
 
+	if (!check_bpf_filter_capable())
+		return -EPERM;
+
 	buffer = perf_bpf_filter__scan_string(str);
 
 	ret = perf_bpf_filter_parse(expr_head);
tools/perf/util/bpf-filter.h +3 -0
index 916ed7770b734f15..122477f2de44bb60 100644
@@ -5,6 +5,7 @@
 #include <linux/list.h>
 
 #include "bpf_skel/sample-filter.h"
+#include "util/debug.h"
 
 struct perf_bpf_filter_expr {
 	struct list_head list;
@@ -38,6 +39,8 @@ int perf_bpf_filter__unpin(void);
 static inline int perf_bpf_filter__parse(struct list_head *expr_head __maybe_unused,
 					 const char *str __maybe_unused)
 {
+	pr_err("Error: BPF filter is requested but perf is not built with BPF.\n"
+		"\tPlease make sure to build with libbpf and BPF skeleton.\n");
 	return -EOPNOTSUPP;
 }
 static inline int perf_bpf_filter__prepare(struct evsel *evsel __maybe_unused,
tools/perf/util/cap.c +0 -1
index 69d9a2bcd40bfdd1..24a0ea7e6d97749b 100644
@@ -7,7 +7,6 @@
 #include "debug.h"
 #include <errno.h>
 #include <string.h>
-#include <linux/capability.h>
 #include <sys/syscall.h>
 #include <unistd.h>
 
tools/perf/util/cap.h +5 -0
index 0c6a1ff55f07340a..c1b8ac033ccc5826 100644
@@ -3,6 +3,7 @@
 #define __PERF_CAP_H
 
 #include <stdbool.h>
+#include <linux/capability.h>
 
 /* For older systems */
 #ifndef CAP_SYSLOG
@@ -13,6 +14,10 @@
 #define CAP_PERFMON	38
 #endif
 
+#ifndef CAP_BPF
+#define CAP_BPF		39
+#endif
+
 /* Query if a capability is supported, used_root is set if the fallback root check was used. */
 bool perf_cap__capable(int cap, bool *used_root);
 
Signature · 1 line
2.49.0.1266.g31b7d2e469-goog
reviewer Reviewed-by on v2 1/1
#1 lore raw
Quoted 23 lines · Namhyung Kim

The BPF filter needs libbpf/BPF-skeleton support and root privilege. Add error messages to help users understand the problem easily.

When it's not build with BPF support (make BUILD_BPF_SKEL=0).

  $ sudo perf record -e cycles --filter "pid != 0" true
  Error: BPF filter is requested but perf is not built with BPF.
        Please make sure to build with libbpf and BPF skeleton.

Usage: perf record [<options>] [<command>]
or: perf record [<options>] -- <command> [<options>]

--filter <filter>
event filter

When it supports BPF but runs without root or CAP_BPF. Note that it also checks pinned BPF filters.

  $ perf record -e cycles --filter "pid != 0" -o /dev/null true
  Error: BPF filter only works for users with the CAP_BPF capability!
        Please run 'perf record --setup-filter pin' as root first.
Quoted 7 lines

Usage: perf record [<options>] [<command>]
or: perf record [<options>] -- <command> [<options>]

--filter <filter>
event filter

Quoted 65 lines

---
v2) change fprintf() -> pr_err() (Ian)

 tools/perf/util/bpf-filter.c | 28 ++++++++++++++++++++++++++++
 tools/perf/util/bpf-filter.h |  3 +++
 tools/perf/util/cap.c        |  1 -
 tools/perf/util/cap.h        |  5 +++++
 4 files changed, 36 insertions(+), 1 deletion(-)
tools/perf/util/bpf-filter.c +28 -0
index a4fdf6911ec1c32e..92e2f054b45e91dd 100644
@@ -52,6 +52,7 @@
 #include <internal/xyarray.h>
 #include <perf/threadmap.h>
 
+#include "util/cap.h"
 #include "util/debug.h"
 #include "util/evsel.h"
 #include "util/target.h"
@@ -618,11 +619,38 @@ struct perf_bpf_filter_expr *perf_bpf_filter_expr__new(enum perf_bpf_filter_term
        return expr;
 }
 
+static bool check_bpf_filter_capable(void)
+{
+       bool used_root;
+
+       if (perf_cap__capable(CAP_BPF, &used_root))
+               return true;
+
+       if (!used_root) {
+               /* Check if root already pinned the filter programs and maps */
+               int fd = get_pinned_fd("filters");
+
+               if (fd >= 0) {
+                       close(fd);
+                       return true;
+               }
+       }
+
+       pr_err("Error: BPF filter only works for %s!\n"
+              "\tPlease run 'perf record --setup-filter pin' as root first.\n",
+              used_root ? "root" : "users with the CAP_BPF capability");
+
+       return false;
+}
+
 int perf_bpf_filter__parse(struct list_head *expr_head, const char *str)
 {
        YY_BUFFER_STATE buffer;
        int ret;
 
+       if (!check_bpf_filter_capable())
+               return -EPERM;
+
        buffer = perf_bpf_filter__scan_string(str);
 
        ret = perf_bpf_filter_parse(expr_head);
tools/perf/util/bpf-filter.h +0 -0
index 916ed7770b734f15..122477f2de44bb60 100644

tools/perf/util/bpf-filter.h line 8

Quoted 4 lines
tools/perf/util/bpf-filter.h +1 -0
@@ -5,6 +5,7 @@
 #include <linux/list.h>
 
 #include "bpf_skel/sample-filter.h"
+#include "util/debug.h"

nit: I'd generally avoid the util/ prefix here as bpf-filter.h and debug.h are in the same directory. The compiler first looks in the same directory before using include paths:
https://gcc.gnu.org/onlinedocs/cpp/Search-Path.html
So including this way is saying please search using the include paths which is weird when the files are in the same directory. I know the style in the code base is inconsistent with this, but I wish it wasn't.

Thanks,
Ian

Quoted 50 lines
tools/perf/util/bpf-filter.h +2 -0
 struct perf_bpf_filter_expr {
        struct list_head list;
@@ -38,6 +39,8 @@ int perf_bpf_filter__unpin(void);
 static inline int perf_bpf_filter__parse(struct list_head *expr_head __maybe_unused,
                                         const char *str __maybe_unused)
 {
+       pr_err("Error: BPF filter is requested but perf is not built with BPF.\n"
+               "\tPlease make sure to build with libbpf and BPF skeleton.\n");
        return -EOPNOTSUPP;
 }
 static inline int perf_bpf_filter__prepare(struct evsel *evsel __maybe_unused,
tools/perf/util/cap.c +0 -1
index 69d9a2bcd40bfdd1..24a0ea7e6d97749b 100644
@@ -7,7 +7,6 @@
 #include "debug.h"
 #include <errno.h>
 #include <string.h>
-#include <linux/capability.h>
 #include <sys/syscall.h>
 #include <unistd.h>
 
tools/perf/util/cap.h +5 -1
index 0c6a1ff55f07340a..c1b8ac033ccc5826 100644
@@ -3,6 +3,7 @@
 #define __PERF_CAP_H
 
 #include <stdbool.h>
+#include <linux/capability.h>
 
 /* For older systems */
 #ifndef CAP_SYSLOG
@@ -13,6 +14,10 @@
 #define CAP_PERFMON    38
 #endif
 
+#ifndef CAP_BPF
+#define CAP_BPF                39
+#endif
+
 /* Query if a capability is supported, used_root is set if the fallback root check was used. */
 bool perf_cap__capable(int cap, bool *used_root);
 
--

2.49.0.1266.g31b7d2e469-goog

author maintainer
#2 lore raw
Quoted 27 lines · Ian Rogers
Quoted 26 lines · Namhyung Kim

The BPF filter needs libbpf/BPF-skeleton support and root privilege. Add error messages to help users understand the problem easily.

When it's not build with BPF support (make BUILD_BPF_SKEL=0).

  $ sudo perf record -e cycles --filter "pid != 0" true
  Error: BPF filter is requested but perf is not built with BPF.
        Please make sure to build with libbpf and BPF skeleton.

Usage: perf record [<options>] [<command>]
or: perf record [<options>] -- <command> [<options>]

--filter <filter>
event filter

When it supports BPF but runs without root or CAP_BPF. Note that it also checks pinned BPF filters.

  $ perf record -e cycles --filter "pid != 0" -o /dev/null true
  Error: BPF filter only works for users with the CAP_BPF capability!
        Please run 'perf record --setup-filter pin' as root first.

Usage: perf record [<options>] [<command>]
or: perf record [<options>] -- <command> [<options>]

Quoted 6 lines
Quoted 4 lines

--filter <filter>
event filter

Thanks for your review!

Quoted 68 lines
Quoted 68 lines

---
v2) change fprintf() -> pr_err() (Ian)

 tools/perf/util/bpf-filter.c | 28 ++++++++++++++++++++++++++++
 tools/perf/util/bpf-filter.h |  3 +++
 tools/perf/util/cap.c        |  1 -
 tools/perf/util/cap.h        |  5 +++++
 4 files changed, 36 insertions(+), 1 deletion(-)
tools/perf/util/bpf-filter.c +28 -0
index a4fdf6911ec1c32e..92e2f054b45e91dd 100644
@@ -52,6 +52,7 @@
 #include <internal/xyarray.h>
 #include <perf/threadmap.h>
 
+#include "util/cap.h"
 #include "util/debug.h"
 #include "util/evsel.h"
 #include "util/target.h"
@@ -618,11 +619,38 @@ struct perf_bpf_filter_expr *perf_bpf_filter_expr__new(enum perf_bpf_filter_term
        return expr;
 }
 
+static bool check_bpf_filter_capable(void)
+{
+       bool used_root;
+
+       if (perf_cap__capable(CAP_BPF, &used_root))
+               return true;
+
+       if (!used_root) {
+               /* Check if root already pinned the filter programs and maps */
+               int fd = get_pinned_fd("filters");
+
+               if (fd >= 0) {
+                       close(fd);
+                       return true;
+               }
+       }
+
+       pr_err("Error: BPF filter only works for %s!\n"
+              "\tPlease run 'perf record --setup-filter pin' as root first.\n",
+              used_root ? "root" : "users with the CAP_BPF capability");
+
+       return false;
+}
+
 int perf_bpf_filter__parse(struct list_head *expr_head, const char *str)
 {
        YY_BUFFER_STATE buffer;
        int ret;
 
+       if (!check_bpf_filter_capable())
+               return -EPERM;
+
        buffer = perf_bpf_filter__scan_string(str);
 
        ret = perf_bpf_filter_parse(expr_head);
tools/perf/util/bpf-filter.h +0 -0
index 916ed7770b734f15..122477f2de44bb60 100644
@@ -5,6 +5,7 @@
 #include <linux/list.h>
 
Quoted 11 lines

tools/perf/util/bpf-filter.h line 8

Quoted 2 lines
tools/perf/util/bpf-filter.h +1 -0
 #include "bpf_skel/sample-filter.h"
+#include "util/debug.h"

nit: I'd generally avoid the util/ prefix here as bpf-filter.h and debug.h are in the same directory. The compiler first looks in the same directory before using include paths:
https://gcc.gnu.org/onlinedocs/cpp/Search-Path.html
So including this way is saying please search using the include paths which is weird when the files are in the same directory. I know the style in the code base is inconsistent with this, but I wish it wasn't.

I see your point. But I thought it's more flexible to file move and for people to find out where the file is.

Thanks,
Namhyung

Quoted 50 lines
Quoted 50 lines
tools/perf/util/bpf-filter.h +2 -0
 struct perf_bpf_filter_expr {
        struct list_head list;
@@ -38,6 +39,8 @@ int perf_bpf_filter__unpin(void);
 static inline int perf_bpf_filter__parse(struct list_head *expr_head __maybe_unused,
                                         const char *str __maybe_unused)
 {
+       pr_err("Error: BPF filter is requested but perf is not built with BPF.\n"
+               "\tPlease make sure to build with libbpf and BPF skeleton.\n");
        return -EOPNOTSUPP;
 }
 static inline int perf_bpf_filter__prepare(struct evsel *evsel __maybe_unused,
tools/perf/util/cap.c +0 -1
index 69d9a2bcd40bfdd1..24a0ea7e6d97749b 100644
@@ -7,7 +7,6 @@
 #include "debug.h"
 #include <errno.h>
 #include <string.h>
-#include <linux/capability.h>
 #include <sys/syscall.h>
 #include <unistd.h>
 
tools/perf/util/cap.h +5 -1
index 0c6a1ff55f07340a..c1b8ac033ccc5826 100644
@@ -3,6 +3,7 @@
 #define __PERF_CAP_H
 
 #include <stdbool.h>
+#include <linux/capability.h>
 
 /* For older systems */
 #ifndef CAP_SYSLOG
@@ -13,6 +14,10 @@
 #define CAP_PERFMON    38
 #endif
 
+#ifndef CAP_BPF
+#define CAP_BPF                39
+#endif
+
 /* Query if a capability is supported, used_root is set if the fallback root check was used. */
 bool perf_cap__capable(int cap, bool *used_root);
 
--

2.49.0.1266.g31b7d2e469-goog

author maintainer Applied
#3 lore raw
In reply to Namhyung Kim
Quoted 10 lines · Namhyung Kim

The BPF filter needs libbpf/BPF-skeleton support and root privilege. Add error messages to help users understand the problem easily.

When it's not build with BPF support (make BUILD_BPF_SKEL=0).

  $ sudo perf record -e cycles --filter "pid != 0" true
  Error: BPF filter is requested but perf is not built with BPF.
  	Please make sure to build with libbpf and BPF skeleton.

[...]

Applied to perf-tools-next, thanks!

Best regards,
Namhyung