Beyla quickstart guides on Grafana Labs

Quickstart: instrument a C/C++ service with Beyla

Wed, 15 Apr 2026 16:46:57 +0000

Quickstart: instrument a C/C++ service with Beyla

1. Run an instrumentable C/C++ service

Run an instrumentable C/C++ service or download and run a simple example C++ HTTP service.

curl -OL https://raw.githubusercontent.com/grafana/beyla/main/examples/quickstart/cpp/httplib.h
curl -OL https://raw.githubusercontent.com/grafana/beyla/main/examples/quickstart/cpp/quickstart.cpp
g++ -std=c++11 quickstart.cpp -o quickstart && ./quickstart

If necessary, replace the g++ command by another compiler supporting C++11.

2. Download Beyla

Download the latest Beyla executable from the Beyla releases page. Uncompress and copy the Beyla executable to any location in your $PATH.

3. (Optional) get Grafana Cloud credentials

Beyla can export metrics and traces to any OpenTelemetry endpoint, as well as exposing metrics as a Prometheus endpoint. However, we recommend using the OpenTelemetry endpoint in Grafana Cloud. You can get a Free Grafana Cloud Account at Grafana’s website.

From the Grafana Cloud Portal, look for the OpenTelemetry box and click Configure.

Under Password / API token click Generate now and follow the instructions to create a default API token.

The Environment Variables will be populated with a set of standard OpenTelemetry environment variables which will provide the connection endpoint and credentials information for Beyla.

Copy the Environment Variables and keep it for the next step.

4. Run Beyla with minimal configuration

To run Beyla, first set the following environment variables:

The OTEL_EXPORTER_OTLP_PROTOCOL, OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_EXPORTER_OTLP_HEADERS variables copied from the previous step.
BEYLA_OPEN_PORT: the port the instrumented service is using (for example, 80 or 443). If using the example service in the first section of this guide, set this variable to 8080.

To facilitate local testing, set the BEYLA_TRACE_PRINTER=text environment variable. When this option is set, Beyla prints traces in text format to the standard output.

Notice: Beyla requires elevated privileges. Running with sudo is the simplest approach. For more restrictive environments, Beyla can run with specific Linux capabilities. Refer to Security, permissions and capabilities for details on the required capabilities for your use case.

export BEYLA_OPEN_PORT=8080
export BEYLA_TRACE_PRINTER=text
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otlp-gateway-prod-eu-west-0.grafana.net/otlp"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic ...your-encoded-credentials..."
sudo -E beyla

5. Test the service

With Beyla and the service running, make HTTP requests to the instrumented service:

curl http://localhost:8080/foo

Beyla should output traces to the standard output similar to this:

2024-01-09 10:31:33.19103133 (3.254486ms[3.254486ms]) 200 GET /foo [127.0.0.1]->[127.0.0.1:8080]
size:80B svc=[{quickstart  generic lima-ubuntu-lts-5074}] traceparent=[00-46214bd23716280eef43cf798dbe5522-0000000000000000-01]

The above trace shows:

2024-01-09 10:31:33.19103133: time of the trace
(3.254486ms[3.254486ms]): total response time for the request
200 GET /foo: response code, HTTP method, and URL path
[127.0.0.1]->[127.0.0.1:8080] source and destination host:port
size:80B: size of the HTTP request (sum of the headers and the body)
svc=[{quickstart generic lima-ubuntu-lts-5074}]: quickstart service, using the generic kernel-based instrumenter, with an automatically created service instance name lima-ubuntu-lts-5074
traceparent as received by the parent request, or a new random one if the parent request didn’t specify it

After a few minutes traces will appear in Grafana Cloud. For example, in the traces explorer:

6. Configure routing

The exposed span name in Grafana Cloud is a generic GET /**, where it should say something like GET /foo (the path of the test request URL).

Beyla groups any unknown URL path as /** to avoid unexpected cardinality explosions.

Configure routing to tell Beyla about expected routes.

For this quickstart, let Beyla to heuristically group the routes.

First, create a config.yml file with the following content:

routes:
  unmatched: heuristic

Then, run Beyla with the -config argument (or use the BEYLA_CONFIG_PATH environment variable instead):

sudo -E beyla -config config.yml

Finally, make HTTP requests:

curl http://localhost:8080/foo
curl http://localhost:8080/user/1234
curl http://localhost:8080/user/5678

Grafana will now heuristically assign a route to each trace. /foo got its own route while /user/1234 and /user/5678 were grouped into the /user/* route.

Next steps

Get more details of the different Beyla configuration options.
Learn how to deploy Beyla as a Docker container or as a Kubernetes DaemonSet or sidecar.

Quickstart: instrument a Go service with Beyla

Wed, 15 Apr 2026 16:46:57 +0000

Quickstart: instrument a Go service with Beyla

1. Run an instrumentable Go service

Run an instrumentable Go service or download and run a simple example Go HTTP service.

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

2. Download Beyla

Download the latest Beyla executable from the Beyla releases page. Uncompress and copy the Beyla executable to any location in your $PATH.

As an alternative (if your host has the Go toolset installed), you can directly download the Beyla executable with the go install command:

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

3. (Optional) get Grafana Cloud credentials

From the Grafana Cloud Portal, look for the OpenTelemetry box and click Configure.

Under Password / API token click Generate now and follow the instructions to create a default API token.

The Environment Variables will be populated with a set of standard OpenTelemetry environment variables which will provide the connection endpoint and credentials information for Beyla.

Copy the Environment Variables and keep it for the next step.

4. Run Beyla with minimal configuration

To run Beyla, first set the following environment variables:

The OTEL_EXPORTER_OTLP_PROTOCOL, OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_EXPORTER_OTLP_HEADERS variables copied from the previous step.
BEYLA_OPEN_PORT: the port the instrumented service is using (for example, 80 or 443). If using the example service in the first section of this guide, set this variable to 8080.

To facilitate local testing, set the BEYLA_TRACE_PRINTER=text environment variable. When this option is set, Beyla prints traces in text format to the standard output.

export BEYLA_OPEN_PORT=8080
export BEYLA_TRACE_PRINTER=text
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otlp-gateway-prod-eu-west-0.grafana.net/otlp"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic ...your-encoded-credentials..."
sudo -E beyla

5. Test the service

With Beyla and the service running, make HTTP requests to the instrumented service:

curl http://localhost:8080/foo

Beyla should output traces to the standard output similar to this:

2024-01-08 14:06:14.182614 (432.191µs[80.421µs]) 200 GET /foo [127.0.0.1]->[localhost:8080]
size:0B svc=[{quickstart  go lima-ubuntu-lts-8222}] traceparent=[00-0f82735dab5798dfbf7f7a26d5df827b-0000000000000000-01]

The above trace shows:

2024-01-08 14:06:14.182614: time of the trace
(432.191µs[80.421µs]): total response time for the request, with the actual internal execution time of the request (not counting the request enqueuing time)
200 GET /foo: response code, HTTP method, and URL path
[127.0.0.1]->[localhost:8080] source and destination host:port
size:0B: size of the HTTP request body (0 bytes, as it was a GET request). For non-go programs, this size would also include the size of the request headers
svc=[{quickstart go lima-ubuntu-lts-8222}]: quickstart service, written in Go, with an automatically created service instance name lima-ubuntu-lts-8222
traceparent as received by the parent request, or a new random one if the parent request didn’t specify it

After a few minutes traces will appear in Grafana Cloud. For example, in the traces explorer:

6. Configure routing

The exposed span name in Grafana Cloud is a generic GET /**, where it should say something like GET /foo (the path of the test request URL).

Beyla groups any unknown URL path as /** to avoid unexpected cardinality explosions.

Configure routing to tell Beyla about expected routes.

For this quickstart, let Beyla to heuristically group the routes.

First, create a config.yml file with the following content:

routes:
  unmatched: heuristic

Then, run Beyla with the -config argument (or use the BEYLA_CONFIG_PATH environment variable instead):

sudo -E beyla -config config.yml

Finally, make HTTP requests:

curl http://localhost:8080/foo
curl http://localhost:8080/user/1234
curl http://localhost:8080/user/5678

Grafana will now heuristically assign a route to each trace. /foo got its own route while /user/1234 and /user/5678 were grouped into the /user/* route.

Next steps

Get more details of the different Beyla configuration options.
Learn how to deploy Beyla as a Docker container or as a Kubernetes DaemonSet or sidecar.

Quickstart: instrument a Java service with Beyla

Wed, 15 Apr 2026 16:46:57 +0000

Quickstart: instrument a Java service with Beyla

1. Run an instrumentable Java service

Run an instrumentable Java service or download and run a simple example Java HTTP service.

curl -OL https://raw.githubusercontent.com/grafana/beyla/main/examples/quickstart/java/Quickstart.java
javac Quickstart.java && java Quickstart

2. Download Beyla

Download the latest Beyla executable from the Beyla releases page. Uncompress and copy the Beyla executable to any location in your $PATH.

3. (Optional) get Grafana Cloud credentials

From the Grafana Cloud Portal, look for the OpenTelemetry box and click Configure.

Under Password / API token click Generate now and follow the instructions to create a default API token.

The Environment Variables will be populated with a set of standard OpenTelemetry environment variables which will provide the connection endpoint and credentials information for Beyla.

Copy the Environment Variables and keep it for the next step.

4. Run Beyla with minimal configuration

To run Beyla, first set the following environment variables:

The OTEL_EXPORTER_OTLP_PROTOCOL, OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_EXPORTER_OTLP_HEADERS variables copied from the previous step.
BEYLA_OPEN_PORT: the port the instrumented service is using (for example, 80 or 443). If using the example service in the first section of this guide, set this variable to 8080.

To facilitate local testing, set the BEYLA_TRACE_PRINTER=text environment variable. When this option is set, Beyla prints traces in text format to the standard output.

export BEYLA_OPEN_PORT=8080
export BEYLA_TRACE_PRINTER=text
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otlp-gateway-prod-eu-west-0.grafana.net/otlp"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic ...your-encoded-credentials..."
sudo -E beyla

5. Test the service

With Beyla and the service running, make HTTP requests to the instrumented service:

curl http://localhost:8080/foo

Beyla should output traces to the standard output similar to this:

2024-01-09 10:31:33.19103133 (3.254486ms[3.254486ms]) 200 GET /foo [127.0.0.1]->[127.0.0.1:8080]
size:80B svc=[{quickstart java lima-ubuntu-lts-5074}] traceparent=[00-46214bd23716280eef43cf798dbe5522-0000000000000000-01]

The above trace shows:

2024-01-09 10:31:33.19103133: time of the trace
(3.254486ms[3.254486ms]): total response time for the request
200 GET /foo: response code, HTTP method, and URL path
[127.0.0.1]->[127.0.0.1:8080] source and destination host:port
size:80B: size of the HTTP request (sum of the headers and the body)
svc=[{quickstart java lima-ubuntu-lts-5074}]: quickstart service, running in a java VM, with an automatically created service instance name lima-ubuntu-lts-5074
traceparent as received by the parent request, or a new random one if the parent request didn’t specify it

After a few minutes traces will appear in Grafana Cloud. For example, in the traces explorer:

6. Configure routing

The exposed span name in Grafana Cloud is a generic GET /**, where it should say something like GET /foo (the path of the test request URL).

Beyla groups any unknown URL path as /** to avoid unexpected cardinality explosions.

Configure routing to tell Beyla about expected routes.

For this quickstart, let Beyla to heuristically group the routes.

First, create a config.yml file with the following content:

routes:
  unmatched: heuristic

Then, run Beyla with the -config argument:

sudo -E beyla -config config.yml

Finally, make HTTP requests:

curl http://localhost:8080/foo
curl http://localhost:8080/user/1234
curl http://localhost:8080/user/5678

Grafana will now heuristically assign a route to each trace. /foo got its own route while /user/1234 and /user/5678 were grouped into the /user/* route.

Next steps

Get more details of the different Beyla configuration options.
Learn how to deploy Beyla as a Docker container or as a Kubernetes DaemonSet or sidecar.

Quickstart: instrument a Node.js service with Beyla

Wed, 15 Apr 2026 16:46:57 +0000

Quickstart: instrument a Node.js service with Beyla

1. Run an instrumentable Node.js service

Run an instrumentable Node.js service or download and run a simple example Node.js HTTP service.

curl -OL https://raw.githubusercontent.com/grafana/beyla/main/examples/quickstart/nodejs/package.json
curl -OL https://raw.githubusercontent.com/grafana/beyla/main/examples/quickstart/nodejs/quickstart.js
npm install && npm start

2. Download Beyla

Download the latest Beyla executable from the Beyla releases page. Uncompress and copy the Beyla executable to any location in your $PATH.

3. (Optional) get Grafana Cloud credentials

From the Grafana Cloud Portal, look for the OpenTelemetry box and click Configure.

Under Password / API token click Generate now and follow the instructions to create a default API token.

The Environment Variables will be populated with a set of standard OpenTelemetry environment variables which will provide the connection endpoint and credentials information for Beyla.

Copy the Environment Variables and keep it for the next step.

4. Run Beyla with minimal configuration

To run Beyla, first set the following environment variables:

The OTEL_EXPORTER_OTLP_PROTOCOL, OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_EXPORTER_OTLP_HEADERS variables copied from the previous step.
BEYLA_OPEN_PORT: the port the instrumented service is using (for example, 80 or 443). If using the example service in the first section of this guide, set this variable to 8080.

To facilitate local testing, set the BEYLA_TRACE_PRINTER=text environment variable. When this option is set, Beyla prints traces in text format to the standard output.

Beyla automatically reports the name of the process executable as service name: node. To override it, refer to the override service name and namespace documentation section.

export BEYLA_OPEN_PORT=8080
export BEYLA_TRACE_PRINTER=text
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otlp-gateway-prod-eu-west-0.grafana.net/otlp"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic ...your-encoded-credentials..."
sudo -E beyla

5. Test the service

With Beyla and the service running, make HTTP requests to the instrumented service:

curl http://localhost:8080/foo

Beyla should output traces to the standard output similar to this:

2024-01-09 10:31:33.19103133 (3.254486ms[3.254486ms]) 200 GET /foo [127.0.0.1]->[127.0.0.1:8080]
size:80B svc=[{quickstart nodejs lima-ubuntu-lts-5074}] traceparent=[00-46214bd23716280eef43cf798dbe5522-0000000000000000-01]

The above trace shows:

2024-01-09 10:31:33.19103133: time of the trace
(3.254486ms[3.254486ms]): total response time for the request
200 GET /foo: response code, HTTP method, and URL path
[127.0.0.1]->[127.0.0.1:8080] source and destination host:port
size:80B: size of the HTTP request (sum of the headers and the body)
svc=[{quickstart nodejs lima-ubuntu-lts-5074}]: quickstart service, running in Node.js, with an automatically created service instance name lima-ubuntu-lts-5074
traceparent as received by the parent request, or a new random one if the parent request didn’t specify it

After a few minutes traces will appear in Grafana Cloud. For example, in the traces explorer:

6. Configure routing

The exposed span name in Grafana Cloud is a generic GET /**, where it should say something like GET /foo (the path of the test request URL).

Beyla groups any unknown URL path as /** to avoid unexpected cardinality explosions.

Configure routing to tell Beyla about expected routes.

For this quickstart, let Beyla to heuristically group the routes.

First, create a config.yml file with the following content:

routes:
  unmatched: heuristic

Then, run Beyla with the -config argument (or use the BEYLA_CONFIG_PATH environment variable instead):

sudo -E beyla -config config.yml

Finally, make HTTP requests:

curl http://localhost:8080/foo
curl http://localhost:8080/user/1234
curl http://localhost:8080/user/5678

Grafana will now heuristically assign a route to each trace. /foo got its own route while /user/1234 and /user/5678 were grouped into the /user/* route.

Next steps

Get more details of the different Beyla configuration options.
Learn how to deploy Beyla as a Docker container or as a Kubernetes DaemonSet or sidecar.

Quickstart: instrument a Python service with Beyla

Wed, 15 Apr 2026 16:46:57 +0000

Quickstart: instrument a Python service with Beyla

1. Run an instrumentable Python service

Run an instrumentable Python service or download and run a simple example Python HTTP service.

curl -OL https://raw.githubusercontent.com/grafana/beyla/main/examples/quickstart/python/quickstart.py
python3 quickstart.py

2. Download Beyla

Download the latest Beyla executable from the Beyla releases page. Uncompress and copy the Beyla executable to any location in your $PATH.

3. (Optional) get Grafana Cloud credentials

From the Grafana Cloud Portal, look for the OpenTelemetry box and click Configure.

Under Password / API token click Generate now and follow the instructions to create a default API token.

The Environment Variables will be populated with a set of standard OpenTelemetry environment variables which will provide the connection endpoint and credentials information for Beyla.

Copy the Environment Variables and keep it for the next step.

4. Run Beyla with minimal configuration

To run Beyla, first set the following environment variables:

The OTEL_EXPORTER_OTLP_PROTOCOL, OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_EXPORTER_OTLP_HEADERS variables copied from the previous step.
BEYLA_OPEN_PORT: the port the instrumented service is using (for example, 80 or 443). If using the example service in the first section of this guide, set this variable to 8080.

To facilitate local testing, set the BEYLA_TRACE_PRINTER=text environment variable. When this option is set, Beyla prints traces in text format to the standard output.

Beyla automatically reports the name of the process executable as service name: python3. To override it, refer to the override service name and namespace documentation section.

export BEYLA_OPEN_PORT=8080
export BEYLA_TRACE_PRINTER=text
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otlp-gateway-prod-eu-west-0.grafana.net/otlp"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic ...your-encoded-credentials..."
sudo -E beyla

5. Test the service

With Beyla and the service running, make HTTP requests to the instrumented service:

curl http://localhost:8080/foo

Beyla should output traces to the standard output similar to this:

2024-01-09 10:31:33.19103133 (3.254486ms[3.254486ms]) 200 GET /foo [127.0.0.1]->[127.0.0.1:8080]
size:80B svc=[{quickstart python lima-ubuntu-lts-5074}] traceparent=[00-46214bd23716280eef43cf798dbe5522-0000000000000000-01]

The above trace shows:

2024-01-09 10:31:33.19103133: time of the trace
(3.254486ms[3.254486ms]): total response time for the request
200 GET /foo: response code, HTTP method, and URL path
[127.0.0.1]->[127.0.0.1:8080] source and destination host:port
size:80B: size of the HTTP request (sum of the headers and the body)
svc=[{quickstart python lima-ubuntu-lts-5074}]: quickstart service, running in Python, with an automatically created service instance name lima-ubuntu-lts-5074
traceparent as received by the parent request, or a new random one if the parent request didn’t specify it

After a few minutes traces will appear in Grafana Cloud. For example, in the traces explorer:

6. Configure routing

The exposed span name in Grafana Cloud is a generic GET /**, where it should say something like GET /foo (the path of the test request URL).

Beyla groups any unknown URL path as /** to avoid unexpected cardinality explosions.

Configure routing to tell Beyla about expected routes.

For this quickstart, let Beyla to heuristically group the routes.

First, create a config.yml file with the following content:

routes:
  unmatched: heuristic

Then, run Beyla with the -config argument (or use the BEYLA_CONFIG_PATH environment variable instead):

sudo -E beyla -config config.yml

Finally, make HTTP requests:

curl http://localhost:8080/foo
curl http://localhost:8080/user/1234
curl http://localhost:8080/user/5678

Grafana will now heuristically assign a route to each trace. /foo got its own route while /user/1234 and /user/5678 were grouped into the /user/* route.

Next steps

Get more details of the different Beyla configuration options.
Learn how to deploy Beyla as a Docker container or as a Kubernetes DaemonSet or sidecar.

Quickstart: instrument a Ruby service with Beyla

Wed, 15 Apr 2026 16:46:57 +0000

Quickstart: instrument a Ruby service with Beyla

1. Run an instrumentable Ruby service

Run an instrumentable Ruby service or download and run a simple example Ruby HTTP service.

curl -OL https://raw.githubusercontent.com/grafana/beyla/main/examples/quickstart/ruby/quickstart.rb
ruby quickstart.rb

2. Download Beyla

Download the latest Beyla executable from the Beyla releases page. Uncompress and copy the Beyla executable to any location in your $PATH.

3. (Optional) get Grafana Cloud credentials

From the Grafana Cloud Portal, look for the OpenTelemetry box and click Configure.

Under Password / API token click Generate now and follow the instructions to create a default API token.

The Environment Variables will be populated with a set of standard OpenTelemetry environment variables which will provide the connection endpoint and credentials information for Beyla.

Copy the Environment Variables and keep it for the next step.

4. Run Beyla with minimal configuration

To run Beyla, first set the following environment variables:

The OTEL_EXPORTER_OTLP_PROTOCOL, OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_EXPORTER_OTLP_HEADERS variables copied from the previous step.
BEYLA_OPEN_PORT: the port the instrumented service is using (for example, 80 or 443). If using the example service in the first section of this guide, set this variable to 8080.

To facilitate local testing, set the BEYLA_TRACE_PRINTER=text environment variable. When this option is set, Beyla prints traces in text format to the standard output.

Beyla automatically reports the name of the process executable as service name: ruby. To override it, refer to the override service name and namespace documentation section.

export BEYLA_OPEN_PORT=8080
export BEYLA_TRACE_PRINTER=text
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otlp-gateway-prod-eu-west-0.grafana.net/otlp"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic ...your-encoded-credentials..."
sudo -E beyla

5. Test the service

With Beyla and the service running, make HTTP requests to the instrumented service:

curl http://localhost:8080/foo

Beyla should output traces to the standard output similar to this:

2024-01-09 10:31:33.19103133 (3.254486ms[3.254486ms]) 200 GET /foo [127.0.0.1]->[127.0.0.1:8080]
size:80B svc=[{quickstart ruby lima-ubuntu-lts-5074}] traceparent=[00-46214bd23716280eef43cf798dbe5522-0000000000000000-01]

The above trace shows:

2024-01-09 10:31:33.19103133: time of the trace
(3.254486ms[3.254486ms]): total response time for the request
200 GET /foo: response code, HTTP method, and URL path
[127.0.0.1]->[127.0.0.1:8080] source and destination host:port
size:80B: size of the HTTP request (sum of the headers and the body)
svc=[{quickstart ruby lima-ubuntu-lts-5074}]: quickstart service, running in Ruby, with an automatically created service instance name lima-ubuntu-lts-5074
traceparent as received by the parent request, or a new random one if the parent request didn’t specify it

After a few minutes traces will appear in Grafana Cloud. For example, in the traces explorer:

6. Configure routing

The exposed span name in Grafana Cloud is a generic GET /**, where it should say something like GET /foo (the path of the test request URL).

Beyla groups any unknown URL path as /** to avoid unexpected cardinality explosions.

Configure routing to tell Beyla about expected routes.

For this quickstart, let Beyla to heuristically group the routes.

First, create a config.yml file with the following content:

routes:
  unmatched: heuristic

Then, run Beyla with the -config argument (or use the BEYLA_CONFIG_PATH environment variable instead):

sudo -E beyla -config config.yml

Finally, make HTTP requests:

curl http://localhost:8080/foo
curl http://localhost:8080/user/1234
curl http://localhost:8080/user/5678

Grafana will now heuristically assign a route to each trace. /foo got its own route while /user/1234 and /user/5678 were grouped into the /user/* route.

Next steps

Get more details of the different Beyla configuration options.
Learn how to deploy Beyla as a Docker container or as a Kubernetes DaemonSet or sidecar.

Quickstart: instrument a Rust service with Beyla

Wed, 15 Apr 2026 16:46:57 +0000

Quickstart: instrument a Rust service with Beyla

1. Run an instrumentable Rust service

Run an instrumentable Rust service or download and run a simple example Rust HTTP service.

curl -OL https://raw.githubusercontent.com/grafana/beyla/main/examples/quickstart/rust/quickstart.rs
rustc quickstart.rs && ./quickstart

2. Download Beyla

Download the latest Beyla executable from the Beyla releases page. Uncompress and copy the Beyla executable to any location in your $PATH.

3. (Optional) get Grafana Cloud credentials

From the Grafana Cloud Portal, look for the OpenTelemetry box and click Configure.

Under Password / API token click Generate now and follow the instructions to create a default API token.

The Environment Variables will be populated with a set of standard OpenTelemetry environment variables which will provide the connection endpoint and credentials information for Beyla.

Copy the Environment Variables and keep it for the next step.

4. Run Beyla with minimal configuration

To run Beyla, first set the following environment variables:

The OTEL_EXPORTER_OTLP_PROTOCOL, OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_EXPORTER_OTLP_HEADERS variables copied from the previous step.
BEYLA_OPEN_PORT: the port the instrumented service is using (for example, 80 or 443). If using the example service in the first section of this guide, set this variable to 8080.

To facilitate local testing, set the BEYLA_TRACE_PRINTER=text environment variable. When this option is set, Beyla prints traces in text format to the standard output.

export BEYLA_OPEN_PORT=8080
export BEYLA_TRACE_PRINTER=text
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otlp-gateway-prod-eu-west-0.grafana.net/otlp"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic ...your-encoded-credentials..."
sudo -E beyla

5. Test the service

With Beyla and the service running, make HTTP requests to the instrumented service:

curl http://localhost:8080/foo

Beyla should output traces to the standard output similar to this:

2024-01-09 10:31:33.19103133 (3.254486ms[3.254486ms]) 200 GET /foo [127.0.0.1]->[127.0.0.1:8080]
size:80B svc=[{quickstart  rust lima-ubuntu-lts-5074}] traceparent=[00-46214bd23716280eef43cf798dbe5522-0000000000000000-01]

The above trace shows:

2024-01-09 10:31:33.19103133: time of the trace
(3.254486ms[3.254486ms]): total response time for the request
200 GET /foo: response code, HTTP method, and URL path
[127.0.0.1]->[127.0.0.1:8080] source and destination host:port
size:80B: size of the HTTP request (sum of the headers and the body)
svc=[{quickstart rust lima-ubuntu-lts-5074}]: quickstart service, written in rust, with an automatically created service instance name lima-ubuntu-lts-5074
traceparent as received by the parent request, or a new random one if the parent request didn’t specify it

After a few minutes traces will appear in Grafana Cloud. For example, in the traces explorer:

6. Configure routing

The exposed span name in Grafana Cloud is a generic GET /**, where it should say something like GET /foo (the path of the test request URL).

Beyla groups any unknown URL path as /** to avoid unexpected cardinality explosions.

Configure routing to tell Beyla about expected routes.

For this quickstart, let Beyla to heuristically group the routes.

First, create a config.yml file with the following content:

routes:
  unmatched: heuristic

Then, run Beyla with the -config argument (or use the BEYLA_CONFIG_PATH environment variable instead):

sudo -E beyla -config config.yml

Finally, make HTTP requests:

curl http://localhost:8080/foo
curl http://localhost:8080/user/1234
curl http://localhost:8080/user/5678

Grafana will now heuristically assign a route to each trace. /foo got its own route while /user/1234 and /user/5678 were grouped into the /user/* route.

Next steps

Get more details of the different Beyla configuration options.
Learn how to deploy Beyla as a Docker container or as a Kubernetes DaemonSet or sidecar.

Beyla and Kubernetes quickstart

Wed, 15 Apr 2026 16:46:57 +0000

Beyla and Kubernetes quickstart

Kubernetes is fully integrated into the Beyla operation mode.

On one side, metrics and traces can be decorated with the metadata of the Kubernetes entities running the automatically instrumented services.

On the other side, DaemonSet has become the preferred deployment mode for Beyla: thanks to the versatility of the new service selectors, a user can precisely define which services need to be instrumented and which don’t. A single instance of Beyla will be able to instrument the selected group of services within a single Kubernetes node.

Beyla service selectors

A service selector is a set of properties that let Beyla to query which processes need to be instrumented.

When Beyla is deployed as a regular operating system process that instrument other processes, the unique service selectors are the network port where the instrumented process should be listening to (can be specified with the BEYLA_OPEN_PORT environment variable) or a Glob to match against the executable filename of the process to instrument (BEYLA_AUTO_TARGET_EXE environment variable).

To select multiple groups of processes, the Beyla YAML configuration file format provides a discovery.instrument section that accepts multiple selector groups:

discovery:
  instrument:
    # Instrument any process using the ports from 8080 to 8089
    - open_ports: 8080-8089
    # Instrument any process whose command line path contains "http"
    - exe_path: "*http*"
    # Instrument any process with a command line path containing "nginx"
    # and using the port 443 (both conditions must be fulfilled)
    - open_ports: 443
      exe_path: "*nginx*"

The above criteria are insufficient for Kubernetes pods where the ports are ephemeral and internal to the pods. Also, pods are a level of abstraction that should hide details such as the name of their executables. For that reason, Beyla makes it possible to use Kubernetes attributes in the service instrumentation selection criteria. All of them accept a glob as value:

k8s_namespace: only instrument applications in the namespace matching the provided glob.
k8s_deployment_name: only instrument Pods that belong to a Deployment with a name matching the provided glob.
k8s_replicaset_name: only instrument Pods that belong to a ReplicaSet with a name matching the provided glob.
k8s_pod_name: only instrument Pods with a name matching the provided glob.

Example scenario

1. Deploy testing instrumentable services

You can instrument any HTTP or HTTPS service in your Kubernetes cluster. If you prefer, you can first try instrumenting the dummy services provided in this example.

The following Kubernetes example file contains two Apache HTTP servers: one pretends to be a company website and the other pretends to be a documentation site (docs). Let’s ignore that both servers will just return an “It Works!” string when the root directory is requested and a 404 error if any other path is requested.

Copy the following contents into a file (for example, sampleapps.yml) and deploy it with the command kubectl apply -f sampleapps.yml.

kind: Deployment
apiVersion: apps/v1
metadata:
  name: docs
spec:
  replicas: 2
  selector:
    matchLabels:
      app: docs
  template:
    metadata:
      labels:
        app: docs
    spec:
      containers:
        - name: docs-server
          image: httpd:latest
          ports:
            - containerPort: 80
              protocol: TCP
              name: http
---
apiVersion: v1
kind: Service
metadata:
  name: docs
spec:
  selector:
    app: docs
  ports:
    - protocol: TCP
      port: 80
---
kind: Deployment
apiVersion: apps/v1
metadata:
  name: website
spec:
  replicas: 2
  selector:
    matchLabels:
      app: website
  template:
    metadata:
      labels:
        app: website
    spec:
      containers:
        - name: website-server
          image: httpd:latest
          ports:
            - containerPort: 80
              protocol: TCP
              name: http
---
apiVersion: v1
kind: Service
metadata:
  name: website
spec:
  selector:
    app: website
  ports:
    - protocol: TCP
      port: 80

To test that they are up and running, open two terminal sessions and run one of each command below on a different session:

# Redirect website to local port 8080
kubectl port-forward services/website 8080:80

# Redirect docs site to local port 8081
kubectl port-forward services/docs 8081:80

From your computer, each request to http://localhost:8080 will be a hypothetical request to the company website and each request to http://localhost:8081 will be a hypothetical request to the documentation website.

2. Create `beyla` namespace

Before configuring and deploying Beyla, let’s create a beyla namespace. We will group there all the permissions, configurations and deployments related to it:

kubectl create namespace beyla

3. Get Grafana Cloud credentials

From the Grafana Cloud Portal, look for the OpenTelemetry box and click Configure.

Under Password / API token click Generate now and follow the instructions to create a default API token.

The Environment Variables will be populated with a set of standard OpenTelemetry environment variables which will provide the connection endpoint and credentials information for Beyla.

From the Environment Variables section, copy the OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_EXPORTER_OTLP_HEADERS values and create a new secret from them. For example, create the following secret file and apply it:

apiVersion: v1
kind: Secret
metadata:
  namespace: beyla
  name: grafana-credentials
type: Opaque
stringData:
  otlp-endpoint: "https://otlp-gateway-prod-eu-west-0.grafana.net/otlp"
  otlp-headers: "Authorization=Basic ...rest of the secret header value..."

3. Configure and run Beyla

Next, you need to provide Beyla with permissions to watch and inspect the metadata of the diverse Kubernetes resources that Beyla’s discovery mechanism requires. You must create the following YAML file and apply it:

apiVersion: v1
kind: ServiceAccount
metadata:
  namespace: beyla
  name: beyla
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: beyla
rules:
  - apiGroups: [ "apps" ]
    resources: [ "replicasets" ]
    verbs: [ "list", "watch" ]
  - apiGroups: [ "" ]
    resources: [ "pods", "services", "nodes" ]
    verbs: [ "list", "watch" ]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: beyla
subjects:
  - kind: ServiceAccount
    name: beyla
    namespace: beyla
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: beyla

And now, deploy Beyla by creating the following Kubernetes entities:

A ConfigMap storing the beyla-config.yml Beyla configuration file, which defines the service discovery criteria. To verify that Beyla is able to discriminate by service instance even if they run the same image and executable, Beyla is configured to select ONLY the docs Apache web server.
A Beyla DaemonSet providing the Beyla pod and its configuration:
- Loads the beyla-config.yml file from the ConfigMap, as specified in the BEYLA_CONFIG_PATH environment variable.
- References to the grafana-secrets values for the endpoint and credentials.
- Uses the beyla ServiceAccount to get all the permissions.

Copy and deploy the following YAML file:

apiVersion: v1
kind: ConfigMap
metadata:
  namespace: beyla
  name: beyla-config
data:
  beyla-config.yml: |
    # this is required to enable kubernetes discovery and metadata
    attributes:
      kubernetes:
        enable: true
    # this will provide automatic routes report while minimizing cardinality
    routes:
      unmatched: heuristic
    # let's instrument only the docs server
    discovery:
      instrument:
        - k8s_deployment_name: "docs"
        # uncomment the following line to also instrument the website server
        # - k8s_deployment_name: "website"
---
apiVersion: apps/v1
kind: DaemonSet
metadata:
  namespace: beyla
  name: beyla
spec:
  selector:
    matchLabels:
      instrumentation: beyla
  template:
    metadata:
      labels:
        instrumentation: beyla
    spec:
      serviceAccountName: beyla
      hostPID: true # mandatory!
      containers:
        - name: beyla
          image: grafana/beyla:latest
          imagePullPolicy: IfNotPresent
          securityContext:
            privileged: true # mandatory!
            readOnlyRootFilesystem: true
          volumeMounts:
            - mountPath: /config
              name: beyla-config
            - mountPath: /var/run/beyla
              name: var-run-beyla
          env:
            - name: BEYLA_CONFIG_PATH
              value: "/config/beyla-config.yml"
            - name: OTEL_EXPORTER_OTLP_ENDPOINT
              valueFrom:
                secretKeyRef:
                  name: grafana-credentials
                  key: otlp-endpoint
            - name: OTEL_EXPORTER_OTLP_HEADERS
              valueFrom:
                secretKeyRef:
                  name: grafana-credentials
                  key: otlp-headers
      volumes:
        - name: beyla-config
          configMap:
            name: beyla-config
        - name: var-run-beyla
          emptyDir: {}

Also notice:

To run in DaemonSet mode, Beyla requires to have access to all the processes in the node. Then the Beyla Pod requires to run with hostPID: true.
The Beyla container needs to run with privileged: true, as it requires to perform privileged actions such as loading BPF programs and creating BPF maps. For running Beyla as unprivileged container, i.e. without the privileged: true option, visit the Deploy Beyla unprivileged guide.

4. Test your instrumented services and see the results in Grafana

With the kubectl port-forward commands from the firs step still running, test both web server instances. For example:

curl http://localhost:8080
curl http://localhost:8080/foo
curl http://localhost:8081
curl http://localhost:8081/foo

Some requests will return 404 error, but it’s OK because they are also instrumented.

Now, go to the instance in Grafana Cloud, and from the Explore section in the left panel, select the data source for the traces (usually named grafanacloud-<your user name>-traces).

To search for all the traces, select the Search box in the Query bar, leave the form empty, and click Run query:

This will show the traces for the docs instance (port 8081). You might see traces from your own services, but shouldn’t see traces from the website service, as it has not been instrumented by Beyla.

In the trace details, the resource attributes of the traces are decorated with the metadata of the Kubernetes Pod running the instrumented service:

Beyla quickstart guides on Grafana Labs

Quickstart: instrument a C/C++ service with Beyla

Quickstart: instrument a C/C++ service with Beyla

1. Run an instrumentable C/C++ service

2. Download Beyla

3. (Optional) get Grafana Cloud credentials

4. Run Beyla with minimal configuration

5. Test the service

6. Configure routing

Next steps

Quickstart: instrument a Go service with Beyla

Quickstart: instrument a Go service with Beyla

1. Run an instrumentable Go service

2. Download Beyla

3. (Optional) get Grafana Cloud credentials

4. Run Beyla with minimal configuration

5. Test the service

6. Configure routing

Next steps

Quickstart: instrument a Java service with Beyla

Quickstart: instrument a Java service with Beyla

1. Run an instrumentable Java service

2. Download Beyla

3. (Optional) get Grafana Cloud credentials

4. Run Beyla with minimal configuration

5. Test the service

6. Configure routing

Next steps

Quickstart: instrument a Node.js service with Beyla

Quickstart: instrument a Node.js service with Beyla

1. Run an instrumentable Node.js service

2. Download Beyla

3. (Optional) get Grafana Cloud credentials

4. Run Beyla with minimal configuration

5. Test the service

6. Configure routing

Next steps

Quickstart: instrument a Python service with Beyla

Quickstart: instrument a Python service with Beyla

1. Run an instrumentable Python service

2. Download Beyla

3. (Optional) get Grafana Cloud credentials

4. Run Beyla with minimal configuration

5. Test the service

6. Configure routing

Next steps

Quickstart: instrument a Ruby service with Beyla

Quickstart: instrument a Ruby service with Beyla

1. Run an instrumentable Ruby service

2. Download Beyla

3. (Optional) get Grafana Cloud credentials

4. Run Beyla with minimal configuration

5. Test the service

6. Configure routing

Next steps

Quickstart: instrument a Rust service with Beyla

Quickstart: instrument a Rust service with Beyla

1. Run an instrumentable Rust service

2. Download Beyla

3. (Optional) get Grafana Cloud credentials

4. Run Beyla with minimal configuration

5. Test the service

6. Configure routing

Next steps

Beyla and Kubernetes quickstart

Beyla and Kubernetes quickstart

Beyla service selectors

Example scenario

1. Deploy testing instrumentable services

2. Create beyla namespace

3. Get Grafana Cloud credentials

3. Configure and run Beyla

4. Test your instrumented services and see the results in Grafana

Links

2. Create `beyla` namespace