---
title: "Setup eBPF Profiling on Docker | Grafana Pyroscope documentation"
description: "Setting up eBPF Profiling with Grafana Alloy on Docker"
---

# Setup eBPF Profiling on Docker

To set up eBPF profiling with Grafana Alloy on Linux, you need to:

- Verify that your system meets the requirements.
- Create an Alloy configuration file. For more information, refer to the [Configuration reference](../configuration/).
- Run 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](/blog/2024/04/09/grafana-alloy-opentelemetry-collector-with-prometheus-pipelines/).

## 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](/docs/grafana/latest/datasources/pyroscope/) provisioned.
- [Docker Engine](https://docs.docker.com/engine/install/) installed.

> 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 requirements

The eBPF profiler requires a Linux kernel version >= 4.9 due to [BPF\_PROG\_TYPE\_PERF\_EVENT](https://lkml.org/lkml/2016/9/1/831).

`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:

shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```shell
docker info | grep Kernel
```

The kernel version must be 4.9 or later.

## Configure Alloy

You can configure Alloy eBPF profiler to profile local containers. To do so, use the [`discovery.docker` component](/docs/alloy/next/reference/components/discovery/discovery.docker/) to discover local containers and the [`pyroscope.ebpf` component](/docs/alloy/next/reference/components/pyroscope/pyroscope.ebpf/) to profile them

For more information about the Alloy configuration, refer to the [Alloy Components reference](/docs/alloy/next/reference/components/).

Create a file named `alloy.config` with the following content:

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
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.

For more information, refer to the [Configure the Grafana Pyroscope data source documentation](/docs/grafana-cloud/connect-externally-hosted/data-sources/pyroscope/configure-pyroscope-data-source/).

> Note
> 
> If you’re using your own Pyroscope server, you can remove the `basic_auth` section altogether.

## Start Alloy

To start Alloy with Docker, run:

shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```shell
docker run \
  -v $PWD/alloy.config:/etc/alloy/alloy.config \
  -v /var/run/docker.sock:/var/run/docker.sock \
  --pid=host \
  --privileged \
  -p 12345:12345 \
  grafana/alloy:latest \
    run --server.http.listen-addr=0.0.0.0:12345 /etc/alloy/alloy.config
```

> 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 data source](/docs/grafana/latest/datasources/pyroscope/). Then select a profile type and a service from the dropdown menu.