Beyla global configuration properties

Beyla global configuration properties

Beyla can be configured via environment variables or via a YAML configuration file 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_LOG_LEVEL option overrides any log_level settings inside config.yaml:

Config argument:

BEYLA_LOG_LEVEL=debug beyla -config /path/to/config.yaml

Config environment variable:

BEYLA_LOG_LEVEL=debug BEYLA_CONFIG_PATH=/path/to/config.yaml beyla

Refer to the example YAML configuration file for a configuration file template.

Beyla consists of a pipeline of components that 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, refer to the network metrics documentation for more information.

The following sections explain the global configuration properties that apply to the entire Beyla configuration:

Executable name matching

This property accepts a glob matched against the full executable command line, including the directory where the executable resides on the file system. Beyla selects one process, or multiple processes with similar characteristics. For more detailed process selection and grouping, refer to the service discovery documentation.

When you instrument by executable name, choose a non-ambiguous name that matches one executable on the target system. For example, if you set BEYLA_AUTO_TARGET_EXE=*/server and have two processes that match the Glob, Beyla selects both. Instead use the full application path for exact matches, for example BEYLA_AUTO_TARGET_EXE=/opt/app/server or BEYLA_AUTO_TARGET_EXE=/server.

If you set both BEYLA_AUTO_TARGET_EXE and BEYLA_OPEN_PORT properties, Beyla selects only executables matching both selection criteria.

Open port matching

This property accepts a comma-separated list of ports or port ranges. If an executable matches any of the ports Beyla selects it. For example:

BEYLA_OPEN_PORT=80,443,8000-8999

In this example, Beyla selects any executable that opens port 80, 443, or any port between 8000 and 8999. It can select one process or multiple processes with similar characteristics. For more detailed process selection and grouping, follow the instructions in the service discovery documentation.

If an executable opens multiple ports, specifying one of those ports is enough for Beyla to instrument all HTTP/S and GRPC requests on all application ports. Currently, there’s no way to limit instrumentation to requests on a specific port.

If the specified port range is wide, for example 1-65535, Beyla tries to execute all processes that own one of the ports in that range.

If you set both BEYLA_AUTO_TARGET_EXE and BEYLA_OPEN_PORT properties, Beyla selects only executables matching both selection criteria.

Service name and namespace

These configuration options are deprecated.

Defining these properties is equivalent to adding a name entry to the discovery.instrument YAML section. When a single instance of Beyla instruments multiple processes, they share the same service name even if they differ. To give multiple services different names, see how to override the service name and namespace in the service discovery documentation.

Trace printer formats

This option prints any instrumented trace on the standard output using one of the following formats:

• disabled: Disables the printer
• text: Prints a concise line of text
• json: Prints a compact JSON object
• json_indent: Prints an indented JSON object

System capabilities

If you set enforce_sys_caps to true and the required system capabilities are missing, Beyla aborts startup and logs the missing capabilities. If you set this option to false, Beyla only logs the missing capabilities.