Configure Beyla 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	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.

YAML	Environment variable	Type	Default
`default_exclude_services`	N/A	list of objects	Path: `(?:^\|\/)(beyla$\|alloy$\|otelcol[^\/]*$)`

Disables instrumentation of Beyla itself (self-instrumentation), as well as Grafana Alloy and the OpenTelemetry Collector. Set to empty to allow Beyla to instrument itself as well as these other components. Note: to enable such self-instrumentation, it is still required to include them in the services section.

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)

Deprecated

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

This option is deprecated, as multiple matches for the same services entry would involve multiple services sharing the same name. Refer to the override service name and namespace section to enable automatic configuration of service name and namespace from diverse metadata sources.

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)

Deprecated.

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.

This option is deprecated. Refer to the overriding service name and namespace section to enable automatic configuration of service name and namespace from diverse metadata sources.

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.