OBI global configuration properties

OBI can be configured via environment variables or via a YAML configuration file passed either with the -config command-line argument or the OTEL_EBPF_CONFIG_PATH environment variable. Environment variables have priority over the properties in the configuration file. For example, in the following command line, the OTEL_EBPF_LOG_LEVEL option overrides any log_level settings inside config.yaml:

Config argument:

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

Config environment variable:

OTEL_EBPF_LOG_LEVEL=debug OTEL_EBPF_CONFIG_PATH=/path/to/config.yaml beyla

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

OBI 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, OBI 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 OBI configuration.

For example:

trace_printer: json
shutdown_timeout: 30s
channel_buffer_len: 33

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. OBI 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 OTEL_EBPF_AUTO_TARGET_EXE=*/server and have two processes that match the Glob, OBI selects both. Instead use the full application path for exact matches, for example OTEL_EBPF_AUTO_TARGET_EXE=/opt/app/server or OTEL_EBPF_AUTO_TARGET_EXE=/server.

If you set both OTEL_EBPF_AUTO_TARGET_EXE and OTEL_EBPF_OPEN_PORT properties, OBI 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 OBI selects it. For example:

OTEL_EBPF_OPEN_PORT=80,443,8000-8999

In this example, OBI 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 OBI 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, OBI tries to execute all processes that own one of the ports in that range.

If you set both OTEL_EBPF_AUTO_TARGET_EXE and OTEL_EBPF_OPEN_PORT properties, OBI 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 OBI 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, OBI aborts startup and logs the missing capabilities. If you set this option to false, OBI only logs the missing capabilities.