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

     1  ---
     2  title: "Set up eBPF profiling on Linux"
     3  menuTitle: "Set up on Linux"
     4  description: "Set up eBPF profiling with Grafana Alloy on Linux machines."
     5  weight: 20
     6  ---
     7  
     8  # Set up eBPF profiling on Linux
     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  - Install [Alloy](https://grafana.com/docs/alloy/<ALLOY_VERSION>/set-up/install/linux/).
    14  - Create an [Alloy configuration file](https://grafana.com/docs/alloy/<ALLOY_VERSION>/configure/linux/). For more information, refer to [Configuration reference](https://grafana.com/docs/alloy/<ALLOY_VERSION>/reference/).
    15  - Run Alloy.
    16  - Finally, verify that profiles are received.
    17  
    18  ## Before you begin
    19  
    20  Before you begin, you need:
    21  
    22  - A Pyroscope server where Alloy can send profiling data.
    23  - Access to Grafana with the [Grafana Pyroscope data source](/docs/grafana/<GRAFANA_VERSION>/datasources/pyroscope/) provisioned.
    24  
    25  {{% admonition type="note" %}}
    26  If you don't have a Grafana or a Pyroscope server, you can use the [Grafana Cloud](https://grafana.com/auth/sign-up/create-user?pg=pricing&plcmt=free&cta=create-free-account) free plan to get started.
    27  {{% /admonition %}}
    28  
    29  ## Verify system meets the requirements
    30  
    31  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)).
    32  
    33  `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.
    34  
    35  To print the kernel version of machine, run:
    36  
    37  ```shell
    38  uname -r
    39  ```
    40  
    41  Make sure you have a kernel version >= 4.9.
    42  
    43  ## Install Alloy
    44  
    45  Follow the [installation instructions](https://grafana.com/docs/alloy/<ALLOY_VERSION>/set-up/install/linux/) to download and install Alloy for your current Linux distribution.
    46  
    47  ## Configure Alloy
    48  
    49  To configure the Alloy eBPF profiler to profile local processes, use [discovery.process component](https://grafana.com/docs/alloy/<ALLOY_VERSION>/reference/components/discovery/discovery.process/) and add a default target in the [`pyroscope.ebpf` component](https://grafana.com/docs/alloy/<ALLOY_VERSION>/reference/components/pyroscope/pyroscope.ebpf/).
    50  All processes are profiled and grouped under the default target.
    51  
    52  Create a file named `alloy.config` with the following content:
    53  
    54  ```alloy
    55  discovery.process "all" {
    56  
    57  }
    58  
    59  discovery.relabel "alloy" {
    60      targets = discovery.process.all.targets
    61      // Filter needed processes
    62      rule {
    63          source_labels = ["__meta_process_exe"]
    64          regex = ".*/alloy"
    65          action = "keep"
    66      }
    67  }
    68  
    69  pyroscope.ebpf "instance" {
    70   forward_to     = [pyroscope.write.endpoint.receiver]
    71   targets = discovery.relabel.alloy.output
    72  }
    73  
    74  pyroscope.scrape "local" {
    75    forward_to     = [pyroscope.write.endpoint.receiver]
    76    targets    = [
    77      {"__address__" = "localhost:12345", "service_name"="grafana/alloy"},
    78    ]
    79  }
    80  
    81  pyroscope.write "endpoint" {
    82   endpoint {
    83    basic_auth {
    84     password = "<PASSWORD>"
    85     username = "<USERNAME>"
    86    }
    87    url = "<URL>"
    88   }
    89   external_labels = {
    90    "env"      = "prod",
    91    "instance" = env("HOSTNAME"),
    92   }
    93  }
    94  ```
    95  
    96  For information about configuring Alloy, refer to [Grafana Alloy on Kubernetes](https://grafana.com/docs/alloy/<ALLOY_VERSION>/configure/kubernetes/).
    97  
    98  For information about the specific blocks used, refer to the [Grafana Alloy Reference](https://grafana.com/docs/alloy/<ALLOY_VERSION>/reference/) and [`discovery.process`](https://grafana.com/docs/alloy/<AlLOY_VERSION>/reference/components/discovery/discovery.process/).
    99  
   100  Replace the `<URL>` placeholder with the appropriate server URL. This could be the Grafana Cloud URL or your own custom Pyroscope server URL.
   101  
   102  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.
   103  
   104  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/).
   105  
   106  {{% admonition type="note" %}}
   107  If you're using your own Pyroscope server, you can remove the `basic_auth` section altogether.
   108  {{% /admonition %}}
   109  
   110  ## Start Alloy
   111  
   112  {{< admonition type="note">}}
   113  The eBPF profiler requires root privileges.
   114  {{< /admonition >}}
   115  
   116  To start the Alloy, run:
   117  
   118  ```shell
   119  alloy run alloy.config
   120  ```
   121  
   122  If you see the following error:
   123  
   124  ```shell
   125  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)"
   126  ```
   127  
   128  Make sure you're running Alloy with root privileges which are required for the eBPF profiler to work.
   129  
   130  ## Verify profiles are received
   131  
   132  To verify that the profiles are received by the Pyroscope server, go to the Pyroscope UI or [Grafana Pyroscope data source](/docs/grafana/<GRAFANA_VERSION>/datasources/pyroscope/). Select a profile type and a service from the drop-down menu.