Documentation Beyla Set up Linux host

Run Beyla on a Linux host

You can run Grafana Beyla as a process on a Linux host, such as a virtual machine or a bare-metal server. Beyla runs with elevated privileges and instruments services that run on the same host, without changes to the services. The steps are the same for services written in any language that Beyla supports.

Before you begin

Before you run Beyla, make sure you have the following:

• A Linux host on amd64 or arm64, with a kernel that meets the Beyla requirements and limitations
• Root access with sudo, or the Linux capabilities listed in Beyla security, permissions, and capabilities
• A service on the host that listens on a TCP port, for example an HTTP, HTTPS, or gRPC service

Start an example service

To try Beyla before you instrument your own service, start one of the example services from the examples/quickstart directory of the Beyla repository. Each example is an HTTP service that listens on port 8080. If you instrument your own service, skip this section.

For example, to download and start the Go example:

sh Copy

curl -OL https://raw.githubusercontent.com/grafana/beyla/main/examples/quickstart/golang/quickstart.go
go run quickstart.go

Download and install Beyla

Beyla releases include a Linux binary for amd64 and arm64.

1. Download the archive for your host from the Beyla releases page:

   sh Copy

   curl -LO https://github.com/grafana/beyla/releases/download/<VERSION>/beyla-linux-<ARCH>-<VERSION>.tar.gz

   Replace the following:

   • <VERSION>: The Beyla release tag, for example v3.40.0
   • <ARCH>: The host architecture, amd64 or arm64

2. Extract the beyla binary and install it in /usr/local/bin:

   sh Copy

   tar -xzf beyla-linux-<ARCH>-<VERSION>.tar.gz beyla
   sudo install beyla /usr/local/bin/

Run Beyla

Beyla needs a way to select the process to instrument, and at least one exporter. The following commands instrument the process that opens port 8080 and print traces to standard output, so you don’t need a backend:

sh Copy

export BEYLA_OPEN_PORT=8080
export BEYLA_TRACE_PRINTER=text
sudo -E beyla

The commands set these environment variables:

The -E option of sudo passes the exported variables to Beyla.

You can also set options in a YAML configuration file. Pass the file with the -config argument or the BEYLA_CONFIG_PATH environment variable. If you set an option in both the file and an environment variable, the environment variable takes precedence.

Check that Beyla instruments the service

Send a request to the service:

sh Copy

curl http://localhost:8080/foo

Beyla prints one line for each request it captures. Each line includes the start time and duration of the request, the protocol, the response status code, the HTTP method and path, the route, the source and destination addresses, the request and response sizes, the service name, and the trace context.

Send data to a backend

The trace printer is for testing. To send data to a backend, unset BEYLA_TRACE_PRINTER and set exporter options instead.

To send metrics and traces to an OpenTelemetry endpoint, such as Grafana Cloud, set the OTLP environment variables:

sh Copy

unset BEYLA_TRACE_PRINTER
export BEYLA_OPEN_PORT=<SERVICE_PORT>
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_ENDPOINT="<OTLP_ENDPOINT>"
export OTEL_EXPORTER_OTLP_HEADERS="<OTLP_HEADERS>"
sudo -E beyla

Replace the following:

• <SERVICE_PORT>: The port your service opens
• <OTLP_ENDPOINT>: The URL of your OTLP endpoint. For Grafana Cloud, copy the endpoint from the OpenTelemetry tile of your stack.
• <OTLP_HEADERS>: The headers your endpoint needs, such as authentication, as comma-separated key=value pairs. For Grafana Cloud, copy the OTEL_EXPORTER_OTLP_HEADERS value that the OpenTelemetry tile generates.

For Grafana Cloud, follow the procedure in Send data to the Grafana Cloud OTLP endpoint.

To expose metrics for Prometheus to scrape, set the Prometheus port:

sh Copy

unset BEYLA_TRACE_PRINTER
export BEYLA_OPEN_PORT=<SERVICE_PORT>
export BEYLA_PROMETHEUS_PORT=8999
sudo -E beyla

Replace <SERVICE_PORT> with the port your service opens.

Beyla serves the metrics at http://localhost:8999/metrics.

For all export options, refer to Configure Beyla Prometheus and OpenTelemetry data export.

Run Beyla as a systemd service

To keep Beyla running and start it when the host boots, run Beyla as a systemd service. The Beyla repository includes a systemd unit file. The unit runs /usr/local/bin/beyla as root, reads environment variables from /etc/beyla/beyla.env, and loads the configuration file /etc/beyla/beyla.yaml.

1. Create the configuration directory:

   sh Copy

   sudo mkdir -p /etc/beyla

2. Create /etc/beyla/beyla.yaml to select the service to instrument:

   YAML Copy

   discovery:
     instrument:
       - open_ports: <SERVICE_PORT>

   Replace <SERVICE_PORT> with the port your service opens.

3. Create /etc/beyla/beyla.env with the exporter settings:

   sh Copy

   OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
   OTEL_EXPORTER_OTLP_ENDPOINT="<OTLP_ENDPOINT>"
   OTEL_EXPORTER_OTLP_HEADERS="<OTLP_HEADERS>"

   Replace <OTLP_ENDPOINT> and <OTLP_HEADERS> with the values from Send data to a backend. The unit fails to start if this file doesn’t exist, so create it even if you set the exporters in beyla.yaml.

4. Download the unit file to /etc/systemd/system/beyla.service:

   sh Copy

   sudo curl -L -o /etc/systemd/system/beyla.service https://raw.githubusercontent.com/grafana/beyla/main/contrib/beyla.service

5. Reload systemd, then start Beyla and turn it on at boot:

   sh Copy

   sudo systemctl daemon-reload
   sudo systemctl enable --now beyla

6. Check that Beyla is running:

   sh Copy

   systemctl status beyla

   To read the Beyla logs, run journalctl -u beyla.

Next steps

• Configure Beyla service discovery
• Configure Beyla Prometheus and OpenTelemetry data export
• Beyla security, permissions, and capabilities
• Run Beyla in a Docker container