This is documentation for the next version of Pyroscope. For the latest stable release, go to the latest version.
Set up eBPF profiling on Linux
To set up eBPF profiling with Grafana Alloy on Linux, you need to:
- Verify that your system meets the requirements.
- Install Alloy.
- Create an Alloy configuration file. For more information, refer to Configuration reference.
- Run Alloy.
- Finally, verify that profiles are received.
Before you begin
Before you begin, you need:
- A Pyroscope server where Alloy can send profiling data.
- Access to Grafana with the Grafana Pyroscope data source provisioned.
Note
If you don’t have a Grafana or a Pyroscope server, you can use the [Grafana Cloud][gcloud] free plan to get started.
Verify system meets the requirements
The eBPF profiler requires a Linux kernel version >= 4.9 (due to BPF_PROG_TYPE_PERF_EVENT).
BPF_PROG_TYPE_PERF_EVENT
is a type of eBPF program that can be attached to hardware or software events, such as performance monitoring counters or tracepoints, in the Linux kernel.
To print the kernel version of machine, run:
uname -r
Make sure you have a kernel version >= 4.9.
Install Alloy
Follow the installation instructions to download and install Alloy for your current Linux distribution.
Configure Alloy
To configure the Alloy eBPF profiler to profile local processes, use discovery.process component and add a default target in the pyroscope.ebpf
component.
All processes are profiled and grouped under the default target.
Create a file named alloy.config
with the following content:
discovery.process "all" {
}
discovery.relabel "alloy" {
targets = discovery.process.all.targets
// Filter needed processes
rule {
source_labels = ["__meta_process_exe"]
regex = ".*/alloy"
action = "keep"
}
}
pyroscope.ebpf "instance" {
forward_to = [pyroscope.write.endpoint.receiver]
targets = discovery.relabel.alloy.output
}
pyroscope.scrape "local" {
forward_to = [pyroscope.write.endpoint.receiver]
targets = [
{"__address__" = "localhost:12345", "service_name"="grafana/alloy"},
]
}
pyroscope.write "endpoint" {
endpoint {
basic_auth {
password = "<PASSWORD>"
username = "<USERNAME>"
}
url = "<URL>"
}
external_labels = {
"env" = "prod",
"instance" = env("HOSTNAME"),
}
}
For information about configuring Alloy, refer to Grafana Alloy on Kubernetes.
For information about the specific blocks used, refer to the Grafana Alloy Reference and discovery.process
.
Replace the <URL>
placeholder with the appropriate server URL. This could be the Grafana Cloud URL or your own custom Pyroscope server URL.
If you need to send data to Grafana Cloud, you’ll have to configure HTTP Basic authentication. Replace <User>
with your Grafana Cloud stack user and <Password>
with your Grafana Cloud API key.
For more information, refer to the Configure the Grafana Pyroscope data source documentation.
Note
If you’re using your own Pyroscope server, you can remove thebasic_auth
section altogether.
Start Alloy
Note
The eBPF profiler requires root privileges.
To start the Alloy, run:
alloy run alloy.config
If you see the following error:
level=error msg="component exited with error" component=pyroscope.ebpf.local_pods err="ebpf profiling session start: load bpf objects: field DisassociateCtty: program disassociate_ctty: map events: map create: operation not permitted (MEMLOCK may be too low, consider rlimit.RemoveMemlock)"
Make sure you’re running Alloy with root privileges which are required for the eBPF profiler to work.
Verify profiles are received
To verify that the profiles are received by the Pyroscope server, go to the Pyroscope UI or Grafana Pyroscope data source. Select a profile type and a service from the drop-down menu.