Beyla quickstart guides on Grafana Labs

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

Mon, 16 Mar 2026 19:38:33 +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_PRINT_TRACES=true environment variable. This will cause Beyla to print traces to standard output.

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

export BEYLA_OPEN_PORT=8080
export BEYLA_PRINT_TRACES=true
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

Mon, 16 Mar 2026 19:38:33 +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_PRINT_TRACES=true environment variable. This will cause Beyla to print traces to standard output.

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

export BEYLA_OPEN_PORT=8080
export BEYLA_PRINT_TRACES=true
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

Mon, 16 Mar 2026 19:38:33 +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_PRINT_TRACES=true environment variable. This causes Beyla to print traces to the standard output.

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

export BEYLA_OPEN_PORT=8080
export BEYLA_PRINT_TRACES=true
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

Mon, 16 Mar 2026 19:38:33 +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_PRINT_TRACES=true environment variable. This will cause Beyla to print traces to standard output.

Also set the BEYLA_SERVICE_NAME=quickstart to override the reported service name in the traces and metrics. If it is not set, Beyla would automatically report the name of the process executable: node.

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

export BEYLA_SERVICE_NAME=quickstart
export BEYLA_OPEN_PORT=8080
export BEYLA_PRINT_TRACES=true
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

Mon, 16 Mar 2026 19:38:33 +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_PRINT_TRACES=true environment variable. This will cause Beyla to print traces to standard output.

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

export BEYLA_SERVICE_NAME=quickstart
export BEYLA_OPEN_PORT=8080
export BEYLA_PRINT_TRACES=true
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

Mon, 16 Mar 2026 19:38:33 +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_PRINT_TRACES=true environment variable. This will cause Beyla to print traces to standard output.

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

export BEYLA_SERVICE_NAME=quickstart
export BEYLA_OPEN_PORT=8080
export BEYLA_PRINT_TRACES=true
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

Mon, 16 Mar 2026 19:38:33 +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_PRINT_TRACES=true environment variable. This causes Beyla to print traces to the standard output.

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

export BEYLA_OPEN_PORT=8080
export BEYLA_PRINT_TRACES=true
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.