This is documentation for the next version of Pyroscope. For the latest stable release, go to the latest version.
Setup eBPF Profiling on Docker
To set up eBPF profiling with Grafana Agent on Linux, you need to:
- Verify that your system meets the requirements.
- Create a Grafana Agent configuration file. For more information, refer to the Configuration reference.
- Run Grafana Agent or Grafana Alloy.
- Verify that profiles are received.
Caution
Grafana Alloy is the new name for our distribution of the OTel collector. Grafana Agent has been deprecated and is in Long-Term Support (LTS) through October 31, 2025. Grafana Agent will reach an End-of-Life (EOL) on November 1, 2025. Read more about why we recommend migrating to Grafana Alloy.
Prerequisites
Before you begin, you need:
- A Pyroscope server where the agent will send profiling data.
- Access to Grafana with the Grafana Pyroscope datasource provisioned.
- Docker Engine installed.
Note
If you don’t have a Grafana and/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 your docker host, run:
docker info | grep Kernel
Make sure you have a kernel version >= 4.9.
Configure Grafana Agent
You can configure the Grafana Agent eBPF profiler to profile local containers.
To do so, use the discovery.docker
component to discover local containers and the pyroscope.ebpf
component to profile them.
Create a file named agent.river
with the following content:
discovery.docker "local_containers" {
host = "unix:///var/run/docker.sock"
}
pyroscope.ebpf "instance" {
forward_to = [pyroscope.write.endpoint.receiver]
targets = discovery.docker.local_containers.targets
}
pyroscope.write "endpoint" {
endpoint {
basic_auth {
password = "<PASSWORD>"
username = "<USERNAME>"
}
url = "<URL>"
}
external_labels = {
"env" = "testing",
"instance" = env("HOSTNAME"),
}
}
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.
Note
If you’re using your own Pyroscope server, you can remove thebasic_auth
section altogether.
For more information, refer to the Configure the Grafana Pyroscope data source documentation.
Start Grafana Agent
To start Grafana Agent with Docker, run:
docker run \
-e AGENT_MODE=flow \
-v $PWD/agent.river:/etc/agent/config.river \
-v /var/run/docker.sock:/var/run/docker.sock \
--pid=host \
--privileged \
-p 12345:12345 \
grafana/agent:latest \
run --server.http.listen-addr=0.0.0.0:12345 /etc/agent/config.river
Note: The
--pid=host
and--privileged
flags are required to profile local containers with ebpf.
Verify profiles are received
To verify that the profiles are received by the Pyroscope server, go to the Pyroscope UI or Grafana Pyroscope datasource. Then select a profile type and a service from the dropdown menu.