Grafana Beyla

Docs: https://grafana.com/docs/beyla/latest/

Beyla is a Grafana eBPF auto-instrumentation tool that captures HTTP/gRPC traffic and generates traces

and metrics without modifying application code.

Requirements

• Linux kernel: 5.8+ with BTF (BPF Type Format) enabled

• Privileges: root or CAP_SYS_ADMIN; in Kubernetes must run in host PID namespace

• Architectures: x86_64, ARM64

Check BTF support:

ls /sys/kernel/btf/vmlinux  # must exist

Supported Languages / Runtimes

Language

HTTP

gRPC

DB queries

Go

✅

✅

✅

Java (JVM)

✅

✅

✅

Python

✅

✅

-

Ruby

✅

-

-

Node.js

✅

-

-

.NET

✅

✅

-

Rust

✅

✅

-

C/C++

✅

-

-

PHP

✅

-

-

Installation

# Docker

docker run --privileged --pid=host \

  -v /sys/kernel/debug:/sys/kernel/debug:ro \

  -e BEYLA_OPEN_PORT=8080 \

  -e OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318 \

  grafana/beyla

# Kubernetes (Helm)

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

helm install beyla grafana/beyla \

  --set discovery.services[0].open_port=8080 \

  --set otelTraces.endpoint=http://tempo:4318

Configuration File

# beyla-config.yml

log_level: INFO

discovery:

  services:

    - name: my-app

      open_port: 8080

      # or by process name:

      # exe_path: /usr/bin/myapp

      # or by K8s pod metadata (auto-detected in K8s)

ebpf:

  wakeup_len: 100           # batch size for events

  track_request_headers: false  # enable to capture HTTP headers (high cardinality risk)

  high_request_volume: false    # optimize for high-traffic services

# Distributed tracing output (OTLP)

otel_traces_export:

  endpoint: http://tempo:4318  # HTTP OTLP endpoint

  # Or gRPC:

  # endpoint: tempo:4317

  # protocol: grpc

# Metrics output (Prometheus)

prometheus_export:

  port: 9090

  path: /metrics

# Or metrics via OTLP

otel_metrics_export:

  endpoint: http://prometheus-otlp:9090

Kubernetes Deployment

DaemonSet (recommended for cluster-wide)

apiVersion: apps/v1

kind: DaemonSet

metadata:

  name: beyla

  namespace: monitoring

spec:

  selector:

    matchLabels:

      app: beyla

  template:

    metadata:

      labels:

        app: beyla

    spec:

      hostPID: true          # required for eBPF

      serviceAccountName: beyla

      containers:

        - name: beyla

          image: grafana/beyla:latest

          securityContext:

            privileged: true   # or use specific capabilities

            # Alternative (non-privileged):

            # capabilities:

            #   add: [SYS_ADMIN, SYS_PTRACE, NET_ADMIN]

          env:

            - name: BEYLA_OPEN_PORT

              value: "8080"

            - name: OTEL_EXPORTER_OTLP_ENDPOINT

              value: "http://alloy:4318"

          volumeMounts:

            - name: sys-kernel-debug

              mountPath: /sys/kernel/debug

              readOnly: true

      volumes:

        - name: sys-kernel-debug

          hostPath:

            path: /sys/kernel/debug

Network Policies and RBAC

apiVersion: v1

kind: ServiceAccount

metadata:

  name: beyla

  namespace: monitoring

---

apiVersion: rbac.authorization.k8s.io/v1

kind: ClusterRole

metadata:

  name: beyla

rules:

  - apiGroups: [""]

    resources: [nodes, pods, services, endpoints, namespaces]

    verbs: [get, list, watch]

Environment Variables

Variable

Description

BEYLA_OPEN_PORT

Port(s) to instrument (e.g., 8080, 8080-8090)

BEYLA_EXECUTABLE_NAME

Process name pattern to instrument

OTEL_EXPORTER_OTLP_ENDPOINT

OTLP endpoint for traces and metrics

OTEL_EXPORTER_OTLP_PROTOCOL

grpc or http/protobuf (default)

OTEL_SERVICE_NAME

Override service name in spans

BEYLA_LOG_LEVEL

DEBUG, INFO, WARN, ERROR

BEYLA_PROMETHEUS_PORT

Port for Prometheus metrics scrape

BEYLA_PROMETHEUS_PATH

Path for Prometheus metrics (default /metrics)

Grafana Cloud Integration

# Using Alloy as the OTLP receiver

otel_traces_export:

  endpoint: http://alloy:4318   # Alloy forwards to Grafana Cloud Tempo

otel_metrics_export:

  endpoint: http://alloy:4318   # Alloy forwards to Grafana Cloud Prometheus

Via Alloy config:

otelcol.receiver.otlp "beyla" {

  http { endpoint = "0.0.0.0:4318" }

  output {

    traces  = [otelcol.exporter.otlp.grafana_cloud.input]

    metrics = [otelcol.exporter.prometheus.local.input]

  }

}

Routes Decorator (Cardinality Control)

Critical for production — prevents HTTP path cardinality explosion:

routes:

  patterns:

    - /user/{id}

    - /api/v1/resources/{resource_id}

  ignored_patterns:

    - /health

    - /metrics

  ignore_mode: traces    # or: metrics, both

  unmatched: heuristic   # or: path, wildcard, low-cardinality

unmatched strategies: heuristic (replaces numeric IDs, best default), low-cardinality (threshold-based collapsing), wildcard (/**), path (actual path — risk of explosion).

Trace Sampling

otel_traces_export:

  sampler:

    name: "parentbased_traceidratio"  # parent-aware fraction sampling

    arg: "0.1"    # 10% sampling — arg is a quoted string

Samplers: always_on, always_off, traceidratio, parentbased_always_on (default), parentbased_traceidratio.

Generated Metrics

Metric

Type

Description

http.server.request.duration

Histogram

Inbound HTTP request duration

http.client.request.duration

Histogram

Outbound HTTP request duration

rpc.server.duration

Histogram

gRPC server call duration

rpc.client.duration

Histogram

gRPC client call duration

db.client.operation.duration

Histogram

DB query duration

Labels: http.method, http.route, http.response.status_code, service.name, service.namespace

Kubernetes Auto-Discovery

In Kubernetes, Beyla auto-discovers pods and enriches telemetry with K8s metadata:

discovery:

  services:

    - k8s_namespace: "production"     # instrument all pods in namespace

    - k8s_pod_name: "frontend.*"      # by pod name regex

    - k8s_deployment_name: "api"      # by deployment name

    - open_port: 8080                 # or by port (any pod)

Auto-enriched span attributes: k8s.namespace.name, k8s.pod.name, k8s.node.name, k8s.deployment.name