Set up Beyla on Grafana Labs

Run Beyla as a standalone process

Sat, 11 Apr 2026 18:21:38 +0000

Run Beyla as a standalone process

Beyla can run as a standalone Linux OS process with elevated privileges that can inspect other running processes.

For a complete introduction tutorial on how to collect and visualize the instrumented data, follow the quick start tutorial.

Download and install

You can download the Beyla executable from the Beyla releases page.

Alternatively, download the Beyla executable with the go install command:

go install github.com/grafana/beyla/cmd/beyla@latest

Configure

Beyla can be configured via:

environment variables
a YAML configuration file, supplied with the -config CLI argument

If the same configuration property is defined in both the YAML file and the environment variables, the value specified in the environment variables takes precedence over the configuration file.

For a complete list of configuration options, see the Beyla configuration options documentation.

Run

Beyla requires at least two configuration options to run:

the executable to instrument, specified with the command line name or port
a metrics exporter, either OpenTelemetry or Prometheus

Beyla requires administrative (sudo) privileges, or at least it needs to be granted the CAP_SYS_ADMIN capability.

Examples

Let’s instrument the process that owns the port 443, and expose the metrics as a Prometheus endpoint listening on the port 8999. In this example, the configuration is passed exclusively through environment variables:

BEYLA_PROMETHEUS_PORT=8999 BEYLA_OPEN_PORT=443 sudo -E beyla

The equivalent execution, but configured via a YAML file would look like:

cat > config.yml <<EOF
open_port: 443
prometheus_export:
  port: 8999
EOF
sudo beyla -config config.yml

In the following example, the previous YAML configuration option for the Prometheus port is overridden by an environment variable:

BEYLA_PROMETHEUS_PORT=8888 sudo -E beyla -config config.yml

Run Beyla as a Docker container

Sat, 11 Apr 2026 18:21:38 +0000

Run Beyla as a Docker container

Beyla can run a standalone Docker container that can instrument a process running in another container.

Find the latest image of Beyla on Docker Hub with the following name:

grafana/beyla:latest

The Beyla container must be configured in following way:

run as a privileged container, or as a container with the SYS_ADMIN capability
share the PID space with the container that is being instrumented

Docker CLI example

For this example you need a container running an HTTP/S or GRPC service. If you don’t have one, you can use this simple blog engine service written in Go:

docker run -p 18443:8443 --name goblog mariomac/goblog:dev

The above command runs a simple HTTPS application. The process opens the container’s internal port 8443, which is then exposed at the host level as the port 18443.

Set environment variables to configure Beyla to print to stdout and listen to a port (container) to inspect the executable:

export BEYLA_PRINT_TRACES=true
export BEYLA_OPEN_PORT=8443

Beyla needs to be run with the following settings:

in --privileged mode, or with SYS_ADMIN capability
a container PID namespace, with the option --pid="container:goblog".

docker run --rm \
  -e BEYLA_OPEN_PORT=8443 \
  -e BEYLA_PRINT_TRACES=true \
  --pid="container:goblog" \
  --privileged \
  grafana/beyla:latest

Once Beyla is running, open https://localhost:8443 in your browser, use the app to generate test data, and verify that Beyla prints trace requests to stdout similar to:

time=2023-05-22T14:03:42.402Z level=INFO msg="creating instrumentation pipeline"
time=2023-05-22T14:03:42.526Z level=INFO msg="Starting main node"
2023-05-22 14:03:53.5222353 (19.066625ms[942.583µs]) 200 GET / [172.17.0.1]->[localhost:18443] size:0B
2023-05-22 14:03:53.5222353 (355.792µs[321.75µs]) 200 GET /static/style.css [172.17.0.1]->[localhost:18443] size:0B
2023-05-22 14:03:53.5222353 (170.958µs[142.916µs]) 200 GET /static/img.png [172.17.0.1]->[localhost:18443] size:0B
2023-05-22 14:13:47.52221347 (7.243667ms[295.292µs]) 200 GET /entry/201710281345_instructions.md [172.17.0.1]->[localhost:18443] size:0B
2023-05-22 14:13:47.52221347 (115µs[75.625µs]) 200 GET /static/style.css [172.17.0.1]->[localhost:18443] size:0B

Now that Beyla is tracing the the target HTTP service, configure it to send metrics and traces to an OpenTelemetry endpoint, or have metrics scraped by Prometheus.

For information on how to export traces and metrics, see the quick start tutorial and the configuration options documentation.

Docker Compose example

The following Docker compose file replicates the same functionality of the Docker CLI example:

version: "3.8"

services:
  # Service to instrument. Change it to any
  # other container that you want to instrument.
  goblog:
    image: mariomac/goblog:dev
    ports:
      # Exposes port 18843, forwarding it to container port 8443
      - "18443:8443"

  autoinstrumenter:
    image: grafana/beyla:latest
    pid: "service:goblog"
    cap_add:
      - SYS_ADMIN
    # If using the above capability fails to instrument your service, remove it
    # and uncomment the line below
    # privileged: true
    environment:
      BEYLA_PRINT_TRACES: true
      BEYLA_OPEN_PORT: 8443

Run the Docker compose file with the following command and use the app to generate traces:

docker compose -f compose-example.yml up

Deploy Beyla in Kubernetes

Sat, 11 Apr 2026 18:21:38 +0000

Deploy Beyla in Kubernetes

You can deploy Beyla in Kubernetes in two separate ways:

As a Sidecar Container (recommended)
As a DaemonSet

In the future, we will release a Beyla operator but at the moment it is work in progress and its API is not stable enough.

Deploying as a sidecar container

This is the recommended way of deploying Beyla for the following reason:

You can configure the auto-instrumentation per instance, instead of having Beyla monitor all of the service instances on the host.
You will save on compute and memory resources. If the auto-instrumented service is present only in a subset of the containers running on the host, you won’t need to deploy the auto-instrument tool for all containers.

Deploying Beyla as a sidecar container has the following configuration requirements:

The process namespace must be shared between all containers in the Pod (shareProcessNamespace: true pod variable)
The auto-instrument tool must internally run as privileged user in the container (securityContext.runAsUser: 0 property in the container configuration).
The auto-instrument container must run in privileged mode (securityContext.privileged: true property of the container configuration) or at least with SYS_ADMIN capability (`securityContext.capabilities.add: [“SYS_ADMIN”])

The following example instruments the goblog pod by attaching Beyla as a container (image available at grafana/beyla:latest). The auto-instrumentation tool is configured to forward metrics and traces to a Grafana Agent, which is accessible behind the grafana-agent service in the same namespace:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: goblog
  labels:
    app: goblog
spec:
  replicas: 2
  selector:
    matchLabels:
      app: goblog
  template:
    metadata:
      labels:
        app: goblog
    spec:
      # Required so the sidecar instrument tool can access the service process
      shareProcessNamespace: true
      containers:
        # Container for the instrumented service
        - name: goblog
          image: mariomac/goblog:dev
          imagePullPolicy: IfNotPresent
          command: ["/goblog"]
          env:
            - name: "GOBLOG_CONFIG"
              value: "/sample/config.yml"
          ports:
            - containerPort: 8443
              name: https
        # Sidecar container with Beyla - the eBPF auto-instrumentation tool
        - name: autoinstrument
          image: grafana/beyla:latest
          securityContext: # Privileges are required to install the eBPF probes
            runAsUser: 0
            capabilities:
              add:
                - SYS_ADMIN
          env:
            - name: BEYLA_OPEN_PORT # The internal port of the goblog application container
              value: "8443"
            - name: OTEL_EXPORTER_OTLP_ENDPOINT
              value: "http://grafana-agent:4318"

For more information about the different configuration options, please check the Configuration section of this documentation site.

Deploying as a sidecar container, is the default deployment mode for the eBPF auto-instrument Kubernetes Operator.

Deploying as a Daemonset

Alternatively, you can deploy the auto-instrumentation tool as a DaemonSet. Using the previous example (the goblog pod), we cannot select the process to instrument by using its open port, because the port is internal to the Pod. At the same time multiple instances of the service would have different open ports. In this case, we will need to instrument by using the application service executable name (see later example).

For security reasons, you should not deploy as DaemonSet unless you can be sure that no external users can deploy pods to the Kubernetes cluster. This is to avoid deploying a pod with a process whose name collides with the original instrumented process.

In addition to the privilege requirements of the sidecar scenario, you will need to configure the auto-instrument pod template with the hostPID: true option enabled, so that it can access all of the processes running on the same host.

---
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: beyla
  labels:
    app: beyla
spec:
  selector:
    matchLabels:
      app: beyla
  template:
    metadata:
      labels:
        app: beyla
    spec:
      hostPID: true # Require to access the processes on the host
      containers:
        - name: autoinstrument
          image: grafana/beyla:latest
          securityContext:
            runAsUser: 0
            privileged: true # Alternative to the capabilities.add SYS_ADMIN setting
          env:
            - name: BEYLA_EXECUTABLE_NAME # Select the executable by its name instead of BEYLA_OPEN_PORT
              value: "goblog"
            - name: OTEL_EXPORTER_OTLP_ENDPOINT
              value: "http://grafana-agent:4318"