beyla（beyla 搜索）

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

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

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

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