github.com/grafana/pyroscope@v1.18.0/docs/sources/configure-client/grafana-alloy/ebpf/configuration/_index.md (about) 1 --- 2 title: "Configuration reference" 3 menuTitle: "Configuration reference" 4 description: "Grafana Alloy eBPF Profiling configuration reference" 5 weight: 30 6 --- 7 8 ## Configuration reference 9 10 Grafana Alloy supports eBPF profiling. 11 The configuration file is written in the [River](https://grafana.com/docs/agent/latest/flow/concepts/config-language/) language and is composed of components that are used to collect, transform, and send data. 12 13 The `pyroscope.ebpf` component is used to collect application performance profiles via eBPF. 14 15  16 17 The `pyroscope.ebpf` runs on the host machine and collects stack traces associated with a process running on the current host. 18 19 Using the `targets` argument, you can specify which processes and containers to profile on the machine. The `targets` can be from discovery components such as `discovery.process`, [`discovery.kubernetes`](https://grafana.com/docs/alloy/<ALLOY_VERSION>/reference/components/discovery/discovery.kubernetes/), [`discovery.docker`](https://grafana.com/docs/alloy/<ALLOY_VERSION>/reference/components/discovery/discovery.docker/), and [`discovery.dockerswarm`](https://grafana.com/docs/alloy/<ALLOY_VERSION>/reference/components/discovery/discovery.dockerswarm/). 20 21 You can use the [`discovery.relabel`](https://grafana.com/docs/alloy/<ALLOY_VERSION>/reference/components/discovery/discovery.relabel/) component to relabel discovered targets and set your own labels. 22 For more information, refer to the [Components](https://grafana.com/docs/alloy/<ALLOY_VERSION>/reference/components/) documentation. 23 24 The `forward_to` parameter should point to a `pyroscope.write` component to send the collected profiles to your Pyroscope Server or [Grafana Cloud](/products/cloud/). 25 26 | Name | Type | Description | Default | Required | 27 |---------------------------|--------------------------|--------------------------------------------------------------|---------|----------| 28 | `targets` | `list(map(string))` | List of targets to group profiles by container id | | yes | 29 | `forward_to` | `list(ProfilesReceiver)` | List of receivers to send collected profiles to. | | yes | 30 | `collect_interval` | `duration` | How frequently to collect profiles | `15s` | no | 31 | `sample_rate` | `int` | How many times per second to collect profile samples | 97 | no | 32 | `pid_cache_size` | `int` | The size of the pid -> proc symbols table LRU cache | 32 | no | 33 | `build_id_cache_size` | `int` | The size of the elf file build id -> symbols table LRU cache | 64 | no | 34 | `same_file_cache_size` | `int` | The size of the elf file -> symbols table LRU cache | 8 | no | 35 | `container_id_cache_size` | `int` | The size of the pid -> container ID table LRU cache | 1024 | no | 36 | `collect_user_profile` | `bool` | A flag to enable/disable collection of userspace profiles | true | no | 37 | `collect_kernel_profile` | `bool` | A flag to enable/disable collection of kernelspace profiles | true | no | 38 | `demangle` | `string` | C++ demangle mode. Available options are: `none`, `simplified`, `templates`, `full` | `none` | no | 39 40 ## Supported languages 41 42 The `pyroscope.ebpf` component supports the following languages: 43 44 - Go with frame pointers enabled (default) 45 - Rust with frame pointers enabled 46 - C/C++ with frame pointers enabled 47 - Python 48 49 ## Send data Grafana Cloud Profiles 50 51 When sending to Grafana Cloud Profiles, you can use the following `pyroscope.write` component configuration which makes uses of environment variables: 52 53 ```alloy 54 pyroscope.write "endpoint" { 55 endpoint { 56 basic_auth { 57 password = env("GC_PASSWORD") 58 username = env("GC_USER") 59 } 60 url = env("GC_URL") 61 } 62 } 63 ``` 64 65 Ensure that you have appropriately configured the `GC_URL`, `GC_USER`, and `GC_PASSWORD` environment variables. 66 67 ## Profile collecting behavior 68 69 The `pyroscope.ebpf` component collects stack traces associated with a process running on the current host. 70 You can use the `sample_rate` argument to define the number of stack traces collected per second. The default is 97. 71 72 The following labels are automatically injected into the collected profiles if you have not defined them. These labels 73 can help you pin down a profiling target. 74 75 | Label | Description | 76 |--------------------|----------------------------------------------------------------------------------------------------------------------------------| 77 | `service_name` | Pyroscope service name. It's automatically selected from discovery meta labels, if possible. Otherwise, it defaults to `unspecified`. | 78 | `__name__` | pyroscope metric name. Defaults to `process_cpu`. | 79 | `__container_id__` | The container ID derived from target. | 80 81 ### Privileges 82 83 You are required to run the agent as root and inside host pid namespace in order to `pyroscope.ebpf` component to work. 84 85 ### Targets 86 87 One of the following special labels _must_ be included in each target of `targets` and the label must correspond to the container or process that is profiled: 88 89 * `__container_id__`: The container ID. 90 * `__meta_docker_container_id`: The ID of the Docker container. 91 * `__meta_kubernetes_pod_container_id`: The ID of the Kubernetes pod container. 92 * `__process_pid__` : The process ID. 93 94 Each process is then associated with a specified target from the targets list, determined by a container ID or process PID. 95 96 If a process's container ID matches a target's container ID label, the stack traces are aggregated per target based on the container ID. 97 If a process's PID matches a target's process PID label, the stack traces are aggregated per target based on the process PID. 98 Otherwise, the process is not profiled. 99 100 ### Service name 101 102 The special label `service_name` is required and must always be present. If it's not specified, it is 103 attempted to be inferred from multiple sources: 104 105 - `__meta_kubernetes_pod_annotation_pyroscope_io_service_name` which is a `pyroscope.io/service_name` pod annotation. 106 - `__meta_kubernetes_namespace` and `__meta_kubernetes_pod_container_name` 107 - `__meta_docker_container_name` 108 - `__meta_dockerswarm_container_label_service_name` and `__meta_dockerswarm_service_name` 109 110 If `service_name` is not specified and could not be inferred, it is set to `unspecified`. 111 112 ## Exposed Prometheus metrics 113 114 The `pyroscope.ebpf` component exposes the following Prometheus metrics: 115 116 - `pyroscope_fanout_latency` (histogram): Write latency for sending to direct and indirect components. 117 - `pyroscope_ebpf_active_targets` (gauge): Number of active targets the component tracks. 118 - `pyroscope_ebpf_profiling_sessions_total` (counter): Number of profiling sessions completed. 119 - `pyroscope_ebpf_profiling_sessions_failing_total` (counter): Number of profiling sessions failed. 120 - `pyroscope_ebpf_pprofs_total` (counter): Number of pprof profiles collected by the ebpf component. 121 122 ## More information 123 124 Check out the following resources to learn more about eBPF profiling: 125 126 - [The pros and cons of eBPF profiling](https://pyroscope.io/blog/ebpf-profiling-pros-cons) blog post (for more context on flame graphs below) 127 - [Demo](https://play-pyroscope.grafana.org) showing breakdown of our examples cluster 128 - [Grafana Alloy](https://grafana.com/docs/alloy/<ALLOY_VERSION>/) 129 - [pyroscope.scrape](https://grafana.com/docs/alloy/<ALLOY_VERSION>/reference/components/pyroscope/pyroscope.scrape/) 130 - [pyroscope.write](https://grafana.com/docs/alloy/<ALLOY_VERSION>/reference/components/pyroscope/pyroscope.write/) 131 - [discovery.kubernetes](https://grafana.com/docs/alloy/<ALLOY_VERSION>/reference/components/discovery/discovery.kubernetes/) 132 - [discovery.docker](https://grafana.com/docs/alloy/<ALLOY_VERSION>/reference/components/discovery/discovery.docker/) 133 - [discovery.relabel](https://grafana.com/docs/alloy/<ALLOY_VERSION>/reference/components/discovery/discovery.relabel/)