github.com/grafana/pyroscope@v1.18.0/docs/sources/configure-client/grafana-alloy/ebpf/setup-docker.md (about)

     1  ---
     2  title: "Setup eBPF Profiling on Docker"
     3  menuTitle: "Setting up on Docker"
     4  description: "Setting up eBPF Profiling with Grafana Alloy on Docker"
     5  weight: 20
     6  ---
     7  
     8  # Setup eBPF Profiling on Docker
     9  
    10  To set up eBPF profiling with Grafana Alloy on Linux, you need to:
    11  
    12  - Verify that your system meets the requirements.
    13  - Create an Alloy configuration file. For more information, refer to the [Configuration reference][config-reference].
    14  - Run Alloy.
    15  - Verify that profiles are received.
    16  
    17  {{< docs/shared lookup="agent-deprecation.md" source="alloy" version="next" >}}
    18  
    19  ## Before you begin
    20  
    21  Before you begin, you need:
    22  
    23  - A Pyroscope server where Alloy can send profiling data.
    24  - Access to Grafana with the [Grafana Pyroscope data source][pyroscope-ds] provisioned.
    25  - [Docker Engine](https://docs.docker.com/engine/install/) installed.
    26  
    27  {{% admonition type="note" %}}
    28  If you don't have a Grafana or a Pyroscope server, you can use the [Grafana Cloud][gcloud] free plan to get started.
    29  {{% /admonition %}}
    30  
    31  ## Verify system requirements
    32  
    33  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).
    34  
    35  `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.
    36  
    37  To print the kernel version of your docker host, run:
    38  
    39  ```shell
    40  docker info | grep Kernel
    41  ```
    42  
    43  The kernel version must be 4.9 or later.
    44  
    45  ## Configure Alloy
    46  
    47  You can configure Alloy eBPF profiler to profile local containers.
    48  To do so, use the [`discovery.docker` component](https://grafana.com/docs/alloy/<ALLOY_VERSION>/reference/components/discovery/discovery.docker/) to discover local containers and the [`pyroscope.ebpf` component](https://grafana.com/docs/alloy/<ALLOY_VERSION>/reference/components/pyroscope/pyroscope.ebpf/) to profile them
    49  
    50  For more information about the Alloy configuration, refer to the [Alloy Components reference](https://grafana.com/docs/alloy/<ALLOY_VERSION>/reference/components/).
    51  
    52  Create a file named `alloy.config` with the following content:
    53  
    54  ```alloy
    55  discovery.docker "local_containers" {
    56   host = "unix:///var/run/docker.sock"
    57  }
    58  
    59  pyroscope.ebpf "instance" {
    60   forward_to     = [pyroscope.write.endpoint.receiver]
    61   targets = discovery.docker.local_containers.targets
    62  }
    63  
    64  pyroscope.write "endpoint" {
    65   endpoint {
    66    basic_auth {
    67     password = "<PASSWORD>"
    68     username = "<USERNAME>"
    69    }
    70    url = "<URL>"
    71   }
    72   external_labels = {
    73    "env"      = "testing",
    74    "instance" = env("HOSTNAME"),
    75   }
    76  }
    77  ```
    78  
    79  Replace the `<URL>` placeholder with the appropriate server URL.
    80  This could be the Grafana Cloud URL or your own custom Pyroscope server URL.
    81  
    82  If you need to send data to Grafana Cloud, you'll have to configure HTTP Basic authentication.
    83  Replace `<User>` with your Grafana Cloud stack user and `<Password>` with your Grafana Cloud API key.
    84  
    85  For more information, refer to the [Configure the Grafana Pyroscope data source documentation](https://grafana.com/docs/grafana-cloud/connect-externally-hosted/data-sources/pyroscope/configure-pyroscope-data-source/).
    86  
    87  {{% admonition type="note" %}}
    88  If you're using your own Pyroscope server, you can remove the `basic_auth` section altogether.
    89  {{% /admonition %}}
    90  
    91  ## Start Alloy
    92  
    93  To start Alloy with Docker, run:
    94  
    95  ```shell
    96  docker run \
    97    -v $PWD/alloy.config:/etc/alloy/alloy.config \
    98    -v /var/run/docker.sock:/var/run/docker.sock \
    99    --pid=host \
   100    --privileged \
   101    -p 12345:12345 \
   102    grafana/alloy:latest \
   103      run --server.http.listen-addr=0.0.0.0:12345 /etc/alloy/alloy.config
   104  ```
   105  
   106  {{< admonition type="note" >}}
   107  The `--pid=host` and `--privileged` flags are required to profile local containers with eBPF.
   108  {{< /admonition >}}
   109  
   110  ## Verify profiles are received
   111  
   112  To verify that the profiles are received by the Pyroscope server, go to the Pyroscope UI or [Grafana Pyroscope data source][pyroscope-ds]. Then select a profile type and a service from the dropdown menu.
   113  
   114  [pyroscope-ds]: /docs/grafana/<GRAFANA_VERSION>/datasources/pyroscope/
   115  [config-reference]: ../configuration/
   116  [gcloud]: /products/cloud/