This is documentation for the next version of Grafana Beyla documentation. For the latest stable release, go to the latest version.
Deploy Beyla with the Grafana Alloy Helm chart
Grafana Alloy is a vendor-neutral distribution of the OpenTelemetry Collector, and the Alloy Helm chart deploys Alloy in Kubernetes.
Alloy includes Grafana Beyla as the beyla.ebpf component, which runs Beyla as a child process inside the Alloy container.
Alloy scrapes the Beyla metrics through the targets export of the component, and receives the Beyla traces through its output block.
You can then process and route the Beyla telemetry with other Alloy components.
You configure Beyla in Alloy syntax, not with the Beyla YAML configuration file.
Each Alloy release includes a specific Beyla version, which the beyla.ebpf component reference lists.
Use this option to process the Beyla telemetry in Alloy pipelines.
The beyla.ebpf component needs elevated privileges, so the Alloy documentation recommends a dedicated Alloy instance for it.
To deploy Beyla on its own, refer to Deploy Beyla with the Beyla Helm chart.
To deploy Beyla with Kubernetes cluster monitoring, refer to Deploy Beyla with the Kubernetes Monitoring Helm chart.
Before you begin
Before you deploy Beyla, make sure you have the following:
- A Kubernetes cluster whose nodes meet the Beyla requirements and limitations. For a local cluster, you can use kind.
- Helm and
kubectl, configured for the cluster - Permission to create cluster-scoped resources and privileged Pods
- A Grafana Cloud stack
Prepare the Alloy environment
Add the Grafana Helm chart repository, update it, and create the alloy-beyla namespace for a dedicated Alloy instance:
helm repo add grafana https://grafana.github.io/helm-charts
helm repo update
kubectl create namespace alloy-beylaYou install the Alloy Helm chart in this namespace after you create the credentials and the Alloy configuration.
Configure credentials
Alloy sends the Beyla metrics to Grafana Cloud Metrics through its Prometheus remote write endpoint. It sends the Beyla traces to Grafana Cloud Traces through its Tempo OTLP endpoint. To use another backend, replace these endpoints and credentials with your own.
Find the URL, user, and password for each endpoint:
- Prometheus: In the Cloud Portal, click Details in the Prometheus card. For more information, refer to Send metrics data from Prometheus.
- Tempo: Follow the procedure in Locate your stack’s URL, user, and password.
Save the following Secret as secrets.yml, and create it with kubectl apply -f secrets.yml:
apiVersion: v1
kind: Secret
metadata:
namespace: alloy-beyla
name: grafana-credentials
type: Opaque
stringData:
prometheus-rw-user: "<PROMETHEUS_USER>"
prometheus-rw-pwd: "<PROMETHEUS_PASSWORD>"
tempo-user: "<TEMPO_USER>"
tempo-pwd: "<TEMPO_PASSWORD>"Replace the following:
<PROMETHEUS_USER>: The Prometheus user, which is the Metrics instance ID of your Grafana Cloud stack<PROMETHEUS_PASSWORD>: A Cloud Access Policy token for the Prometheus endpoint<TEMPO_USER>: The User value from the Tempo section of your Grafana Cloud stack<TEMPO_PASSWORD>: The Password value from the Tempo section of your Grafana Cloud stack
Create the Alloy configuration
Save the following Alloy configuration as config.alloy:
beyla.ebpf "default" {
attributes {
kubernetes {
enable = "true"
}
}
discovery {
instrument {
kubernetes {
namespace = "<NAMESPACE>"
}
}
}
metrics {
features = [
"application",
]
}
output {
traces = [otelcol.exporter.otlp.grafana_cloud_tempo.input]
}
}
prometheus.scrape "beyla" {
targets = beyla.ebpf.default.targets
honor_labels = true
forward_to = [prometheus.remote_write.rw.receiver]
}
prometheus.remote_write "rw" {
endpoint {
url = "<PROMETHEUS_REMOTE_WRITE_URL>"
basic_auth {
username = sys.env("PROMETHEUS_REMOTE_WRITE_USERNAME")
password = sys.env("PROMETHEUS_REMOTE_WRITE_PASSWORD")
}
}
}
otelcol.exporter.otlp "grafana_cloud_tempo" {
client {
endpoint = "<TEMPO_ENDPOINT>"
auth = otelcol.auth.basic.grafana_cloud_tempo.handler
}
}
otelcol.auth.basic "grafana_cloud_tempo" {
username = sys.env("TEMPO_USERNAME")
password = sys.env("TEMPO_PASSWORD")
}Replace the following:
<NAMESPACE>: The Kubernetes namespace of the applications to instrument<PROMETHEUS_REMOTE_WRITE_URL>: The Prometheus remote write URL of your Grafana Cloud stack, which ends in/api/prom/push<TEMPO_ENDPOINT>: The Tempo endpoint of your Grafana Cloud stack, including the:443port
Create a ConfigMap from the file:
kubectl create configmap --namespace alloy-beyla alloy-config "--from-file=config.alloy=./config.alloy"With this configuration, Beyla instruments the applications in the <NAMESPACE> namespace, and Alloy sends the metrics to Grafana Cloud Metrics and the traces to Grafana Cloud Traces.
The configuration sets the following:
attributes.kubernetes.enableadds Kubernetes metadata, such as the namespace and Pod name, to the metrics and traces of the instrumented applications.discovery.instrument.kubernetesselects the applications to instrument by their Kubernetes metadata, with glob patterns.metrics.featuressets which metrics Beyla exports. Theapplicationfeature, which is the default, exports application-level request rate, error, and duration (RED) metrics.- The
prometheus.scrapecomponent collects the Beyla metrics. Itshonor_labels = truesetting keeps the per-processinstanceandjoblabels that Beyla sets. - The
prometheus.remote_writecomponent sends the metrics to Grafana Cloud Metrics. output.tracessends the Beyla traces to theotelcol.exporter.otlpcomponent, the OTLP exporter, which sends them to Grafana Cloud Traces.- The
otelcol.auth.basiccomponent authenticates the requests to Grafana Cloud Traces.
For more information about the configuration options, refer to the beyla.ebpf component reference.
Install the Alloy Helm chart
Save the following Alloy Helm chart values as values.yaml:
alloy:
configMap:
create: false
name: alloy-config
key: config.alloy
securityContext:
privileged: true
extraEnv:
- name: PROMETHEUS_REMOTE_WRITE_USERNAME
valueFrom:
secretKeyRef:
name: grafana-credentials
key: prometheus-rw-user
- name: PROMETHEUS_REMOTE_WRITE_PASSWORD
valueFrom:
secretKeyRef:
name: grafana-credentials
key: prometheus-rw-pwd
- name: TEMPO_USERNAME
valueFrom:
secretKeyRef:
name: grafana-credentials
key: tempo-user
- name: TEMPO_PASSWORD
valueFrom:
secretKeyRef:
name: grafana-credentials
key: tempo-pwd
controller:
type: daemonset
hostPID: trueInstall Alloy with the command:
helm upgrade --install --namespace alloy-beyla alloy-beyla grafana/alloy -f values.yamlThe values file sets the following:
alloy.configMapuses thealloy-configConfigMap that you created, and itsconfig.alloykey, instead of a ConfigMap that the chart creates.alloy.securityContext.privileged: truegrants all capabilities to the Alloy container. The Alloy container runs Beyla as a child process, and Beyla loads eBPF programs, so the Alloy container needs elevated privileges. For production, the Alloy documentation recommends that you run Alloy withoutprivileged: trueand grant only the capabilities that Beyla needs, as described in Kubernetes: unprivileged, root user.alloy.extraEnvsets environment variables from thegrafana-credentialsSecret, and the Alloy configuration reads them withsys.env.controller.type: daemonsetruns one Alloy Pod on each node, so Beyla instruments the applications on every node.controller.hostPID: trueruns the Alloy Pods in the host process ID (PID) namespace, so Beyla can find the processes on each node.
Check that Beyla is running
To check the deployment, complete the following steps:
Check that the Alloy Pods are running:
kubectl get pods --namespace alloy-beylaCheck the logs of an Alloy Pod for the
Beyla subprocess startedmessage:kubectl logs --namespace alloy-beyla <POD_NAME>Replace
<POD_NAME>with a Pod name from the previous command. Alloy writes the Beyla logs to its own log, with thesource=beyla-subprocessattribute.
After the applications in the <NAMESPACE> namespace receive requests, their metrics and traces appear in your Grafana Cloud stack.
To query the metrics, open Explore and select the grafanacloud-<STACK_NAME>-prom data source.
To query the traces, select the grafanacloud-<STACK_NAME>-traces data source.
Replace <STACK_NAME> with the name of your Grafana Cloud stack.
For more information, refer to Manage data sources in Grafana Cloud.