DocumentationGrafana PyroscopeConfigure the clientGrafana AgentProfiling with eBPFSetting up on Kubernetes

Setup eBPF Profiling on Kubernetes

To set up eBPF profiling with Grafana Agent on Kubernetes, you need to:

• Verify that your cluster meets the prerequisites.
• Add the Grafana helm repository.
• Create a Grafana Agent configuration file. For more information, refer to Configuration reference.
• Install Grafana Agent.
• Verify that profiles are received.

Prerequisites

Before you begin, you need:

• helm and kubectl installed with access to your Kubernetes cluster.
• A Pyroscope server where the agent will send profiling data.
• Access to Grafana with the Grafana Pyroscope datasource provisioned.

Verify that your cluster 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 each node in your cluster, run:

shell Copy

kubectl get nodes -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.nodeInfo.kernelVersion}{"\n"}{end}'

Make sure all nodes have a kernel version >= 4.9.

Add the Grafana Helm repository

We recommend using Helm to install Grafana Agent. To add the Grafana Helm repository, run:

shell Copy

helm repo add grafana https://grafana.github.io/helm-charts
helm repo update

You can verify that the repository was added successfully by running:

shell Copy

helm search repo grafana/grafana-agent

It should return a list of available versions of Grafana Agent.

Create a Grafana Agent configuration file

Create a file named values.yaml with the following content:

yaml Copy

agent:
  mode: 'flow'
  configMap:
    create: true
    content: |
      discovery.kubernetes "local_pods" {
        selectors {
          field = "spec.nodeName=" + env("HOSTNAME")
          role = "pod"
        }
        role = "pod"
      }
      pyroscope.ebpf "instance" {
        forward_to = [pyroscope.write.endpoint.receiver]
        targets = discovery.kubernetes.local_pods.targets
      }
      pyroscope.write "endpoint" {
        endpoint {
          basic_auth {
            password = "<PASSWORD>"
            username = "<USERNAME>"
          }
          url = "<URL>"
        }
      }

  securityContext:
    privileged: true
    runAsGroup: 0
    runAsUser: 0

controller:
  hostPID: true

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.

Install the Grafana Agent

To install the Grafana Agent, run:

shell Copy

helm install pyroscope-ebpf grafana/grafana-agent -f values.yaml

Once configured, the Agent will start collecting eBPF profiles and send them to the Pyroscope server.

Verify profiles are received

To verify that the profiles are received by the Pyroscope server, go to the Pyroscope UI or Grafana Pyroscope datasource. Select a profile type and a service from the drop-down menu.