title

menuTitle

description

weight

keywords

aliases

Beyla configuration options

Options

Learn about the configuration options available for Beyla.

1

Beyla

eBPF

/docs/grafana-cloud/monitor-applications/beyla/configure/options/

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

or

$ 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 applications. In the YAML configuration, each component has its own first-level section.

Optionally, Beyla also provides network-level metrics, which are documented in the [Network metrics section of the Beyla documentation]({{< relref "../network" >}}).

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.
Configuration of metrics and traces attributes to control which attributes are reported.
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.
Filter metrics and traces by attribute values.
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	Environment variable	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	Environment variable	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.

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 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	Environment variable	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	Environment variable	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	Environment variable	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	Environment variable	Type	Default
`trace_printer`	`BEYLA_TRACE_PRINTER`	string	`disabled`

Prints any instrumented trace on the standard output. The value of this option specify the format to be used when printing the trace. Valid formats are:

Value	Description
`disabled`	disables the printer
`text`	prints a concise line of text
`json`	prints a compact JSON object
`json_indent`	prints an indented JSON object

YAML	Environment variable	Type	Default
`enforce_sys_caps`	`BEYLA_ENFORCE_SYS_CAPS`	boolean	`true`

If you have set the enforce_sys_caps to true, if the required system capabilities are not present Beyla aborts its startup and logs a list of the missing capabilities.

If you have set the configuration option to false, Beyla logs a list of the missing capabilities only.

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]({{< relref "../setup/kubernetes.md" >}}) 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	Environment variable	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, go to the discovery services section of this document.

YAML	Environment variable	Type	Default
`exclude_services`	N/A	list of objects	(unset)

This section allows for specifying selection criteria for excluding services from being instrumented. It follows the same definition format as described in the discovery services section of this document.

This option is useful for avoiding instrumentation of services which are typically found in observability environments. For example, use this option to exclude instrumenting Prometheus, the OpenTelemetry collector or Grafana Alloy.

YAML	Environment variable	Type	Default
`skip_go_specific_tracers`	`BEYLA_SKIP_GO_SPECIFIC_TRACERS`	boolean	false

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

YAML	Environment variable	Type	Default
`exclude_otel_instrumented_services`	`BEYLA_EXCLUDE_OTEL_INSTRUMENTED_SERVICES`	boolean	true

Disables Beyla instrumentation of services which are already instrumented with OpenTelemetry. Since Beyla is often deployed to monitor all services in a Kubernetes cluster, monitoring already instrumented services can lead to duplicate telemetry data, unless the instrumentation selection (or exclusion) criteria is carefully crafted. To avoid unnecessary configuration overhead, Beyla monitors for the OpenTelemetry SDK calls to publish metrics and traces, and automatically turns off instrumentation of services which publish their own telemetry data. Turn this option off if your application generated telemetry data doesn't conflict with the Beyla generated metrics and traces.

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	Environment variable	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/DaemonSet/StatefulSet 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 attribute would allow differentiating the different instances of the service.

YAML	Environment variable	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.

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	Environment variable	Type	Default
`open_ports`	--	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.