Configure Beyla on Grafana Labs

Beyla configuration options

Mon, 17 Mar 2025 08:44:01 +0100

Beyla configuration options

Beyla can be configured via environment variables or via a YAML configuration file that is passed either with the -config command-line argument or the BEYLA_CONFIG_PATH environment variable. Environment variables have priority over the properties in the configuration file. For example, in the following command line, the BEYLA_OPEN_PORT option, is used to override any open_port settings inside the config.yaml file:

$ BEYLA_OPEN_PORT=8080 beyla -config /path/to/config.yaml

$ BEYLA_OPEN_PORT=8080 BEYLA_CONFIG_PATH=/path/to/config.yaml beyla

At the end of this document, there is an example of YAML configuration file.

Currently, Beyla consist of a pipeline of components which generate, transform, and export traces from HTTP and GRPC services. In the YAML configuration, each component has its own first-level section.

The architecture below shows the different components of Beyla. The dashed boxes in the diagram below can be enabled and disabled according to the configuration.

A quick description of the components:

Service discovery searches for instrumentable processes matching a given criteria.
EBPF tracer instruments the HTTP and GRPC services of an external process, creates service traces and forwards them to the next stage of the pipeline.
Routes decorator will match HTTP paths (e.g. /user/1234/info) into user-provided HTTP routes (e.g. /user/{id}/info). If no routes are defined, the incoming data will be directly forwarded to the next stage.
Kubernetes decorator will decorate the metrics and traces with Kubernetes metadata of the instrumented Pods.
Grafana Cloud OTEL exporter for metrics and traces simplifies the submission of OpenTelemetry metrics and traces to Grafana cloud.
OTEL metrics exporter exports metrics data to an external OpenTelemetry metrics collector.
OTEL traces exporter exports span data to an external OpenTelemetry traces collector.
Prometheus HTTP endpoint enables an HTTP endpoint that allows any external scraper to pull metrics in Prometheus format.
Internal metrics reporter optionally reports metrics about the internal behavior of the auto-instrumentation tool in Prometheus format.

The following sections explain the global configuration properties, as well as the options for each component.

Global configuration properties

The properties in this section are first-level YAML properties, as they apply to the whole Beyla configuration:

YAML	Env var	Type	Default
`executable_name`	`BEYLA_EXECUTABLE_NAME`	string	(unset)

Selects the process to instrument by the executable name path. This property accepts a regular expression to be matched against the full executable command line, including the directory where the executable resides on the file system.

This property is used to select a single process to instrument, or a group of processes of similar characteristics. For more fine-grained process selection and grouping, you can follow the instructions in the service discovery section.

If the open_port property is set, the executable to be selected needs to match both properties.

When instrumenting by using the executable name, choose a non-ambiguous name, a name that will match a single executable on the target system. For example, if you set BEYLA_EXECUTABLE_NAME=server, and you have running two processes whose executables have the following paths:

/usr/local/bin/language-server
/opt/app/server

Beyla will match indistinctly one of the above processes and instrument both. If you just want to instrument one of them, you should be as concrete as possible about the value of the setting. For example, BEYLA_EXECUTABLE_NAME=/opt/app/server or just BEYLA_EXECUTABLE_NAME=/server.

YAML	Env var	Type	Default
`open_port`	`BEYLA_OPEN_PORT`	string	(unset)

Selects the process to instrument by the port it has open (listens to). This property accepts a comma-separated list of ports (for example, 80), and port ranges (for example, 8000-8999). If the executable matching only one of the ports in the list, it is considered to match the selection criteria.

For example, specifying the following property:

open_port: 80,443,8000-8999

Would make Beyla to select any executable that opens port 80, 443, or any of the ports between 8000 and 8999 included.

If the executable_name property is set, the executable to be selected needs to match both properties.

If an executable opens multiple ports, only one of the ports needs to be specified for Beyla to instrument all the HTTP/S and GRPC requests on all application ports. At the moment, there is no way to restrict the instrumentation only to the methods exposed through a specific port.

If the specified port range is wide (e.g. 1-65535) Beyla will try to execute all the processes owning one of the ports in the range.

YAML	Env var	Type	Default
`service_name`	`BEYLA_SERVICE_NAME` or `OTEL_SERVICE_NAME`	string	(see service discovery section)

Overrides the name of the instrumented service to be reported by the metrics exporter. Defining this property is equivalent to add a name entry into the discovery.services YAML section.

If a single instance of Beyla is instrumenting multiple instances of different processes, they will share the same service name even if they are different. If you need that a single instance of Beyla report different service names, follow the instructions in the service discovery section.

YAML	Env var	Type	Default
`service_namespace`	`BEYLA_SERVICE_NAMESPACE`	string	(see service discovery section)

Optionally, allows assigning a namespace for the service selected from the executable_name or open_port properties.

Defining this property is equivalent to add a name entry into the discovery.services YAML section.

This will assume a single namespace for all the services instrumented by Beyla. If you need that a single instance of Beyla groups multiple services into different namespaces, follow the instructions in the service discovery section.

It is important to notice that this namespace is not a selector for Kubernetes namespaces. Its value will be use to set the value of standard telemetry attributes. For example, the OpenTelemetry service.namespace attribute.

YAML	Env var	Type	Default
`log_level`	`BEYLA_LOG_LEVEL`	string	`INFO`

Sets the verbosity level of the process standard output logger. Valid log level values are: DEBUG, INFO, WARN and ERROR. DEBUG being the most verbose and ERROR the least verbose.

YAML	Env var	Type	Default
`print_traces`	`BEYLA_PRINT_TRACES`	boolean	`false`

If true, prints any instrumented trace on the standard output (stdout).

Service discovery

The executable_name, open_port, service_name and service_namespace are top-level properties that simplify the configuration of Beyla to instrument a single service, or a group of related services.

In some scenarios, Beyla will instrument a big variety of services; for example, as a Kubernetes DaemonSet that instruments all the services in a node. The discovery YAML section will let you specify a higher differentiation degree in the services that Beyla can instrument.

For example, it will allow overriding the service name and namespace per service type.

YAML	Env var	Type	Default
`services`	N/A	list of objects	(unset)

This section allows specifying different selection criteria for different services, as well as overriding some of their metadata, such as their reported name or namespace.

For more details about this section, please go to the discovery services section of this document.

YAML	Env var	Type	Default
`skip_go_specific_tracers`	`BEYLA_SKIP_GO_SPECIFIC_TRACERS`	boolean	false

Disables the detection of Go specifics when ebpf tracer inspects executables to be instrumented. The tracer will fallback to using generic instrumentation, which will generally be less efficient.

Discovery services section

Example of YAML file allowing the selection of multiple groups of services:

discovery:
  services:
    - exe_path: (worker)|(backend)|(frontend)
      namespace: MyApplication
    - exe_path: loadgen
      namespace: testing
      name: "TestLoadGenerator"

The above example YAML will select two groups of executables. The first group will be formed by any process whose executable path contains the worker, backend or frontend text. For each service, Beyla will take the service name attribute from the executable name. The reported service namespace for all the processes matching this group will be MyApplication.

The second group in the above example YAML will select any executable whose path contains regexp, but instead of taking the service name from the executable name, it will override the service name with TestLoadGenerator.

The rest of this section describes the properties that are accepted in each entry of the services list.

Each services entry is a map where the properties can be grouped according to two purposes:

Overriding the reported service name and namespace: name and namespace properties.
Selecting the process to instrument: the rest of the properties, referred as selectors in this documentation.

YAML	Env var	Type	Default
`name`	–	string	(see description)

Defines a name for the matching instrumented service. It will be used to populate the service.name OTEL property and/or the service_name prometheus property in the exported metrics/traces.

If the property is not set, it will default to any of the following properties, in order of precedence:

If Kubernetes is enabled:
1. The name of the Deployment that runs the instrumented process, if any.
2. The name of the ReplicaSet that runs the instrumented process, if any.
3. The name of the Pod that runs the instrumented process.
If kubernetes is not enabled:
1. The name of the process executable file.

If multiple processes match the service selection criteria described below, the metrics and traces for all the instances might share the same service name; for example, when multiple instrumented processes run under the same Deployment, or have the same executable name. In that case, the reported instance.id (OTEL) or target_instance (Prometheus) would allow differentiating the different instances of the service.

YAML	Env var	Type	Default
`namespace`	–	string	(empty or K8s namespace)

Defines a namespace for the matching instrumented service. If the property is not set, it will be defaulted to the Kubernetes namespace of that runs the instrumented process, if Kubernetes is available, or empty when Kubernetes is not available.

YAML	Env var	Type	Default
`open_ports`	–	string	(unset)

For example, specifying the following property:

open_port: 80,443,8000-8999

Would make Beyla to select any executable that opens port 80, 443, or any of the ports between 8000 and 8999 included.