Configure Beyla on Grafana Labs

Configure Beyla export modes

Wed, 15 Apr 2026 16:46:57 +0000

Configure Beyla export modes

Beyla exports data in Alloy or Direct mode.

Beyla running in Alloy mode on the left and Direct mode on the right.

Direct mode

In Direct mode Beyla pushes metrics and traces directly to a remote endpoint using the OpenTelemetry protocol (OTLP).

Beyla can also expose a Prometheus HTTP endpoint ready to scrape, for example in pull mode.

To use Direct mode requires configuration with authentication credentials. Set the OTLP endpoint authentication credentials with these environment variables:

OTEL_EXPORTER_OTLP_ENDPOINT
OTEL_EXPORTER_OTLP_HEADERS

To run in Direct mode using the Prometheus scrape endpoint, see the configuration documentation.

Alloy mode

In Alloy mode Beyla sends metrics and traces to Grafana Alloy. Alloy processes and sends them to Mimir and Tempo. Alloy manages the authentication required by the Mimir and Tempo endpoints.

This mode integrates with Grafana exclusive features like span-to-metrics and span-to-service graph converters.

The following sections are examples of how to set up Alloy and Beyla to send to Grafana Cloud.

Configure Alloy pipeline

First, install and configure Grafana Alloy. Configure the Alloy pipeline and specify the following nodes:

Download the example River configuration file.

Create an OpenTelemetry receiver endpoint for the auto-instrumentation tool to forward metrics and traces. Add this entry to the Alloy configuration file:

otelcol.receiver.otlp "default" {
  grpc {}
  http {}

  output {
    metrics = [otelcol.processor.batch.default.input]
    traces = [otelcol.processor.batch.default.input]
  }
}

This enables Alloy to receive OpenTelemetry events via GRPC and HTTP. Alloy forwards the data to the batch processor. The batch processor accumulate the data and forwards it to exporters:

otelcol.processor.batch "default" {
  output {
    metrics = [otelcol.exporter.prometheus.default.input]
    traces  = [otelcol.exporter.otlp.tempo.input]
  }
}

Export either metrics, traces, or both. To export a single data type, omit the metrics or traces lines in the node definitions and skip the related exporters.

Alloy exports metrics in Prometheus format to Grafana Mimir. The configuration uses basic authentication. The Alloy configuration uses values set in environment variables:

otelcol.exporter.prometheus "default" {
    forward_to = [prometheus.remote_write.mimir.receiver]
}

prometheus.remote_write "mimir" {
  endpoint {
    url = "https://" + env("MIMIR_ENDPOINT") + "/api/prom/push"
    basic_auth {
      username = env("MIMIR_USER")
      password = env("GRAFANA_API_KEY")
    }
  }
}

Set authentication environment variables and run Alloy:

export MIMIR_USER=734432
export MIMIR_ENDPOINT=prometheus-prod-01-eu-west-0.grafana.net
export GRAFANA_API_KEY=VHJhbGFyw60gcXVlIHRlIHbD....=

Finally, set up a Grafana Tempo exporter and endpoint. The Alloy configuration uses values set in environment variables:

otelcol.exporter.otlp "tempo" {
    client {
        endpoint = env("TEMPO_ENDPOINT")
        auth     = otelcol.auth.basic.creds.handler
    }
}

otelcol.auth.basic "creds" {
    username = env("TEMPO_USER")
    password = env("GRAFANA_API_KEY")
}

Note that the TEMPO_ENDPOINT and TEMPO_USER values are different from MIMIR_ENDPOINT and MIMIR_USER.

Run Alloy with a named configuration file:

grafana-alloy run alloy-config.river

Configure and run Beyla

This tutorial assumes Beyla and Alloy are running natively on the same host, so there is no need to secure the traffic nor provide authentication in the Alloy OTLP receiver.

Install Grafana Beyla and download the example configuration file.

First, specify the executable to instrument. For a service executable running on port 443, add the open_port property to the YAML document:

discovery:
  instrument:
    - open_ports: 443

Next, specify where the traces and the metrics are sent. If Alloy is running on the local host, it uses port 4318:

otel_metrics_export:
  endpoint: http://localhost:4318
otel_traces_export:
  endpoint: http://localhost:4318

You can specify a combination of otel_metrics_export and otel_traces_export properties to export metrics, traces, or both.

Run Beyla with a named configuration file:

beyla -config instrument-config.yml

BEYLA_CONFIG_PATH=instrument-config.yml beyla

Beyla global configuration properties

Wed, 15 Apr 2026 16:46:57 +0000

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.

For example:

trace_printer: json
shutdown_timeout: 30s
channel_buffer_len: 33

YAML environment variable	Description	Type	Default
(No YAML) `BEYLA_AUTO_TARGET_EXE`	Selects the process to instrument by Glob matching against the full executable path.	string	unset
`open_port` `BEYLA_OPEN_PORT`	Selects a process to instrument by open ports. Accepts comma-separated lists of ports and port ranges.	string	unset
`shutdown_timeout` `BEYLA_SHUTDOWN_TIMEOUT`	Sets the timeout for a graceful shutdown	string	“10s”
`log_level` `BEYLA_LOG_LEVEL`	Sets process logger verbosity. Valid values: `DEBUG`, `INFO`, `WARN`, `ERROR`.	string	`INFO`
`log_format` `BEYLA_LOG_FORMAT`	Sets process logger format. Valid values: `text`, `json`.	string	`text`
`trace_printer` `BEYLA_TRACE_PRINTER`	Prints instrumented traces to the standard output in a specified format, refer to trace printer formats.	string	`disabled`
`enforce_sys_caps` `BEYLA_ENFORCE_SYS_CAPS`	Controls how Beyla handles missing system capabilities at startup.	boolean	`false`
(No YAML) `BEYLA_AUTO_TARGET_LANGUAGE`	Selects the executable to instrument matching a Glob of chosen languages.	string	unset

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.

Configure Beyla Prometheus and OpenTelemetry data export

Wed, 15 Apr 2026 16:46:57 +0000

Configure Beyla Prometheus and OpenTelemetry data export

Beyla can export OpenTelemetry metrics and traces to a OTLP endpoint.

To send metrics directly to the Grafana Cloud OpenTelemetry endpoint, see the Grafana Cloud OTLP endpoint configuration.

Grafana Cloud OTLP endpoint

YAML section: grafana.otlp

You can configure the component under the grafana.otlp section of your YAML configuration or via environment variables. You can configure Beyla to submit OpenTelemetry data to the Grafana Cloud OTEL endpoint using custom variables, allowing an easier setup of the endpoint and the authentication.

For more information on the Grafana Cloud OTLP endpoint, refer to the Send data to the Grafana Cloud OTLP endpoint documentation.

For example:

grafana:
  otlp:
    cloud_submit: ["metrics", "traces"]
    cloud_zone: "eu-west-23"
    cloud_instance_id: "12345"
    cloud_api_key: "abcde"

You can also use the standard OpenTelemetry variables to submit the metrics and traces to any standard OpenTelemetry endpoint, including Grafana Cloud.

YAML environment variable	Description	Type	Default
`cloud_submit` `GRAFANA_CLOUD_SUBMIT`	A list of data types to submit to the OTLP endpoint. Accepts `metrics` and `traces` as values.	string	`traces`
`cloud_zone` `GRAFANA_CLOUD_ZONE`	The cloud zone of your Grafana endpoint used to compose the Grafana OTLP URL. Refer to cloud zone configuration for important details about endpoint overrides.	string
`cloud_instance_id` `GRAFANA_CLOUD_INSTANCE_ID`	Your Grafana user name. Usually a number but must be set as a string in the YAML file.	string
`cloud_api_key` `GRAFANA_CLOUD_API_KEY`	API key of your Grafana Cloud account.	string

Cloud zone configuration

If any of the OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_METRICS_ENDPOINT or OTEL_EXPORTER_OTLP_TRACES_ENDPOINT variables are defined, they override the destination endpoint, and Beyla ignores the cloud_zone configuration option.

OpenTelemetry metrics exporter component

YAML section: otel_metrics_export

Enable the OpenTelemetry metrics export component by setting the endpoint attribute in your configuration file or via an environment variable, refer to metric export configuration options.

Configure the component under the otel_metrics_export section of your YAML configuration or via environment variables.

In addition to the configuration documented in this article, the component supports environment variables from the standard OpenTelemetry exporter configuration.

For example:

otel_metrics_export:
  ttl: 5m
  endpoint: http://otelcol:4318
  protocol: grpc
  features: ["network", "network_inter_zone"]
  buckets:
    duration_histogram: [0, 1, 2]
  histogram_aggregation: base2_exponential_bucket_histogram

YAML environment variable	Description	Type	Default
`endpoint` `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`	The endpoint Beyla sends metrics to.	URL
`OTEL_EXPORTER_OTLP_ENDPOINT`	The shared endpoint for metrics and traces exporters. Beyla adds `/v1/metrics` path to the URL when sending metrics, following the OpenTelemetry standard. To prevent this behavior, use the metrics specific setting.	URL
`protocol` `OTEL_EXPORTER_OTLP_METRICS_PROTOCOL`	The protocol transport/encoding of the OpenTelemetry endpoint, refer to metrics export protocol. Accepted values `http/json`, `http/protobuf`, and `grpc`.	string	Inferred from port usage
`OTEL_EXPORTER_OTLP_PROTOCOL`	Similar to the shared endpoint, the protocol for metrics and traces.	string	Inferred from port usage
`insecure_skip_verify` `BEYLA_OTEL_INSECURE_SKIP_VERIFY`	If `true`, Beyla skips verifying and accepts any server certificate. Only override this setting for non-production environments.	boolean	`false`
`interval` `BEYLA_METRICS_INTERVAL`	The duration between exports.	Duration	`60s`
`features` `BEYLA_OTEL_METRICS_FEATURES`	The list of metric groups Beyla exports data for, refer to metrics export features. Accepted values `application`, `application_span`, `application_span_otel`, `application_host`, `application_service_graph`, `application_process`, `network` and `network_inter_zone`.	list of strings	`["application"]`
`allow_service_graph_self_references` `BEYLA_OTEL_ALLOW_SERVICE_GRAPH_SELF_REFERENCES`	Controls if Beyla includes self-referencing services in service graph generation, for example a service that calls itself. Self referencing reduces service graph usefulness and increases data cardinality.	boolean	`false`
`instrumentations` `BEYLA_OTEL_METRICS_INSTRUMENTATIONS`	The list of metrics instrumentation Beyla collects data for, refer to metrics instrumentation section.	list of strings	`["*"]`
`buckets`	Sets how you can override bucket boundaries of diverse histograms, refer to override histogram buckets.	(n/a)	Object
`histogram_aggregation` `OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION`	Sets the default aggregation Beyla uses for histogram instruments. Accepted values `explicit_bucket_histogram` or `base2_exponential_bucket_histogram`.	`string`	`explicit_bucket_histogram`

Metrics export protocol

If you don’t set a protocol Beyla sets the protocol as follows:

grpc: if the port ends in 4317, for example 4317, 14317, or 24317.
http/protobuf: if the port ends in 4318, for example 4318, 14318, or 24318.

Metrics export features

The Beyla metrics exporter can export the following metrics data groups for processes matching entries in the metrics discovery configuration.

application: Application-level metrics
application_span: Application-level trace span metrics using legacy naming conventions
application_span_otel: Application-level trace span metrics using OpenTelemetry naming conventions. Refer to span metrics formats for differences between application_span and application_span_otel
application_host: Application-level host metrics for host based pricing
application_service_graph: Application-level service graph metrics. It’s recommended to use a DNS for service discovery and to ensure the DNS names match the OpenTelemetry service names Beyla uses. In Kubernetes environments, the OpenTelemetry service name set by the service name discovery is the best choice for service graph metrics.
application_process: Low-level process metrics (for example, CPU, memory, disk metrics) for the selected services
network: Network-level metrics, refer to the network metrics configuration documentation to learn more
network_inter_zone: Network inter-zone metrics, refer to the network metrics configuration documentation to learn more

Span metrics formats

Beyla provides two formats for span metrics:

application_span: Legacy format using the metric names traces_spanmetrics_latency and traces_spanmetrics_calls_total
application_span_otel: OpenTelemetry-compliant format using the metric names traces_span_metrics_duration_seconds and traces_span_metrics_calls_total

You can only enable one span metrics format at a time. If you specify both application_span and application_span_otel in the features list, Beyla returns a configuration error.

Metrics instrumentation

The list of instrumentation areas Beyla can collection data from:

*: all instrumentation, if * is present Beyla ignores other values
http: HTTP/HTTPS/HTTP2 application metrics
grpc: gRPC application metrics
sql: SQL database client call metrics
redis: Redis client/server database metrics
kafka: Kafka client/server message queue metrics
mongodb: MongoDB client/server database metrics

For example, setting the instrumentations option to: http,grpc enables the collection of HTTP/HTTPS/HTTP2 and gRPC application metrics, and disables other instrumentation.

OpenTelemetry traces exporter component

YAML section: otel_traces_export

You can configure the component under the otel_traces_export section of your YAML configuration or via environment variables.

In addition to the configuration documented in this article, the component supports the environment variables from the standard OpenTelemetry exporter configuration.

otel_traces_export:
  endpoint: http://jaeger:4317
  protocol: grpc
  instrumentations: ["http", "sql"]

YAML environment variable	Description	Type	Default
`endpoint` `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` `OTEL_EXPORTER_OTLP_ENDPOINT`	The endpoint Beyla sends traces to. When using `OTEL_EXPORTER_OTLP_ENDPOINT`, Beyla follows the OpenTelemetry standard and automatically adds `/v1/traces` path to the URL. If you don’t want this to happen, use the traces specific setting.	URL
`protocol` `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL` `OTEL_EXPORTER_OTLP_PROTOCOL`	The protocol transport/encoding of the OpenTelemetry endpoint, refer to traces export protocol. Accepted values `http/json`, `http/protobuf`, and `grpc`.	string	Inferred from port usage
`insecure_skip_verify` `BEYLA_OTEL_INSECURE_SKIP_VERIFY`	If `true`, Beyla skips verifying and accepts any server certificate. Only override this setting for non-production environments.	boolean	`false`
`instrumentations` `BEYLA_OTEL_TRACES_INSTRUMENTATIONS`	The list of instrumentation Beyla collects data for, refer to traces instrumentation section.	list of strings	`["http", "grpc", "sql", "redis", "kafka", "mongo"]`

Traces export protocol

If you don’t set a protocol Beyla sets the protocol as follows:

grpc: if the port ends in 4317, for example 4317, 14317, or 24317.
http/protobuf: if the port ends in 4318, for example 4318, 14318, or 24318.

Traces instrumentation

The list of instrumentation areas Beyla can collection data from:

*: all instrumentation, if * is present Beyla ignores other values
http: HTTP/HTTPS/HTTP2 application traces
grpc: gRPC application traces
sql: SQL database client call traces
redis: Redis client/server database traces
kafka: Kafka client/server message queue traces
mongo: MongoDB client/server database traces
dns: DNS request traces (not enabled by default)
gpu: GPU operation traces (not enabled by default)

For example, setting the instrumentations option to: http,grpc enables the collection of HTTP/HTTPS/HTTP2 and gRPC application traces, and disables other instrumentation.

Note: By default, Beyla enables the most commonly used instrumentations (http, grpc, sql, redis, kafka, mongo). DNS and GPU traces are not enabled by default to reduce overhead, but can be explicitly enabled if needed.

Prometheus exporter component

YAML section: prometheus_export

You can configure the component under the prometheus_export section of your YAML configuration or via environment variables. This component opens an HTTP endpoint in the auto-instrumentation tool that allows any external scraper to pull metrics in Prometheus format. It is enabled if the port property is set.

Note
Prometheus scrapers override the instance and job labels by default. To preserve the per-process instance identifiers set by Beyla, configure your scraper with honor_labels: true. See the Prometheus documentation or Alloy prometheus.scrape documentation.

prometheus_export:
  port: 8999
  path: /metrics
  extra_resource_attributes: ["deployment_environment"]
  ttl: 1s
  buckets:
    request_size_histogram: [0, 10, 20, 22]
    response_size_histogram: [0, 10, 20, 22]
  features:
    - application
    - network
    - application_process
    - application_span
    - application_service_graph
  instrumentations: ["http, "sql"]

YAML environment variable	Description	Type	Default
`port` `BEYLA_PROMETHEUS_PORT`	The HTTP port for the Prometheus scrape endpoint. If unset or 0, no Prometheus endpoint is open.	int
`path` `BEYLA_PROMETHEUS_PATH`	The HTTP query path to fetch the list of Prometheus metrics.	string	`/metrics`
`extra_resource_attributes` `BEYLA_PROMETHEUS_EXTRA_RESOURCE_ATTRIBUTES`	A list of additional resource attributes to be added to the reported `target_info` metric. Refer to extra resource attributes for important details about runtime discovered attributes.	list of strings
`ttl` `BEYLA_PROMETHEUS_TTL`	The duration after which metric instances are not reported if they haven’t been updated. Used to avoid reporting indefinitely finished application instances.	Duration	`5m`
`buckets`	Sets how you can override bucket boundaries of diverse histograms, refer to override histogram buckets.	Object
`features` `BEYLA_PROMETHEUS_FEATURES`	The list of metric groups Beyla exports data for, refer to Prometheus export features.	list of strings	`["application"]`
`allow_service_graph_self_references` `BEYLA_PROMETHEUS_ALLOW_SERVICE_GRAPH_SELF_REFERENCES`	Does Beyla include self-referencing service in service graph generation. Self referencing isn’t useful for service graphs and increases data cardinality.	boolean	`false`
`instrumentations` `BEYLA_PROMETHEUS_INSTRUMENTATIONS`	The list of instrumentation Beyla collects data for, refer to Prometheus instrumentation section.	list of strings	`["*"]`

Prometheus extra resource attributes

Due to internal limitations of the Prometheus API client, Beyla needs to know beforehand which attributes are exposed for each metric. This would cause that some attributes that are discovered at runtime, during instrumentation, won’t be visible by default. For example, attributes defined on each application via Kubernetes annotations, or in the target application’s OTEL_RESOURCE_ATTRIBUTES environment variable.

For example, an application defining the OTEL_RESOURCE_ATTRIBUTES=deployment.environment=production as environment variable, the target_info{deployment.environment="production"} attribute would be visible by default if the metrics are exported via OpenTelemetry but not if they are exported via Prometheus.

To make deployment_environment visible in Prometheus, you need to add it to the extra_resource_attributes list.

Prometheus export features

The Prometheus metrics exporter can export the following metrics data groups:

application: Application-level metrics
application_span: Application-level trace span metrics
application_host Application-level host metrics for host based pricing
application_service_graph: Application-level service graph metrics. It’s recommended to use a DNS for service discovery and to ensure the DNS names match the OpenTelemetry service names Beyla uses. In Kubernetes environments, the OpenTelemetry service name set by the service name discovery is the best choice for service graph metrics.
application_process: Low-level process metrics (for example, CPU, memory, disk metrics) for the selected services
network: Network-level metrics, refer to the network metrics configuration documentation to learn more
network_inter_zone: Network inter-zone metrics, refer to the network metrics configuration documentation to learn more

Prometheus instrumentation

The list of instrumentation areas Beyla can collection data from:

*: all instrumentation, if * is present Beyla ignores other values
http: HTTP/HTTPS/HTTP2 application metrics
grpc: gRPC application metrics
sql: SQL database client call metrics
redis: Redis client/server database metrics
kafka: Kafka client/server message queue metrics

For example, setting the instrumentations option to: http,grpc enables the collection of HTTP/HTTPS/HTTP2 and gRPC application metrics, and disables other instrumentation.

Configure Beyla service discovery

Wed, 15 Apr 2026 16:46:57 +0000

Configure Beyla service discovery

The BEYLA_AUTO_TARGET_EXE and BEYLA_OPEN_PORT are environment variables that make it easier to configure Beyla to instrument a single service or a group of related services.

In some scenarios, Beyla instruments many services. For example, as a Kubernetes DaemonSet that instruments all the services in a node. The discovery YAML section lets you specify more granular selection criteria for the services Beyla can instrument.

YAML environment variable	Description	Type	Default
`instrument`	Specify different selection criteria for different services, and override their reported name or namespace. Refer to the discovery services section for details. .	list of objects	(unset)
`survey`	specifying different selection criteria for Beyla survey mode. Refer to the survey mode section for details.	List of objects	(unset)
`exclude_instrument`	Specify selection criteria for excluding services from being instrumented. Useful for avoiding instrumentation of services typically found in observability environments. Refer to the exclude services from instrumentation section for details. .	list of objects	(unset)
`default_exclude_instrument`	Disables instrumentation of Beyla itself, Grafana Alloy, and the OpenTelemetry Collector. Set to empty to allow Beyla to instrument itself and these other components. Refer to the default exclude services from instrumentation section for details. .	list of objects	Path: `{beyla,alloy,prometheus-config-reloader,ebpf-instrument,obi,otelcol,otelcol-contrib,otelcol-contrib[!/]*}` and certain Kubernetes system namespaces
`skip_go_specific_tracers` `BEYLA_SKIP_GO_SPECIFIC_TRACERS`	Disables the detection of Go specifics when the ebpf tracer inspects executables to be instrumented. The tracer falls back to using generic instrumentation, which is generally less efficient. Refer to the skip go specific tracers section for details. .	boolean	false
`exclude_otel_instrumented_services` `BEYLA_EXCLUDE_OTEL_INSTRUMENTED_SERVICES`	Disables Beyla instrumentation of services already instrumented with OpenTelemetry. Refer to the exclude instrumented services section for details.	boolean	true
`exclude_otel_instrumented_services_span_metrics` `BEYLA_EXCLUDE_OTEL_INSTRUMENTED_SERVICES_SPAN_METRICS`	Disables Beyla span metric/service graph metric generation of services already instrumented with OpenTelemetry. Refer to the exclude instrumented services section for details.	boolean	false

Discovery services

You can override the service name, namespace, and other configurations per service type.

YAML	Description	Type	Default
`name`	Defines a name for the matching instrumented service. Refer to name.	string	(see description)
`namespace`	Defines a namespace for the matching instrumented service. Refer to namespace.	string	(empty or K8s namespace)
`open_ports`	Selects the process to instrument by the port it has open (listens to). Refer to open ports.	string	(unset)
`exe_path`	Selects the processes to instrument by their executable name path. Refer to executable path.	string (glob)	(unset)
`containers_only`	Selects processes to instrument which are running in an OCI container. Refer to containers only.	boolean	false
`container_name`	Filter services by OCI container name. Refer to Container name.	string (glob)	(unset)
`k8s_namespace`	Filter services by Kubernetes namespace. Refer to K8s namespace.	string (glob)	(unset)
`k8s_pod_name`	Filter services by Kubernetes Pod. Refer to K8s Pod name.	string (glob)	(unset)
`k8s_deployment_name`	Filter services by Kubernetes Deployment. Refer to K8s deployment name.	string (glob)	(unset)
`k8s_replicaset_name`	Filter services by Kubernetes ReplicaSet. Refer to K8s ReplicaSet name.	string (glob)	(unset)
`k8s_statefulset_name`	Filter services by Kubernetes StatefulSet. Refer to K8s StatefulSet name.	string (glob)	(unset)
`k8s_daemonset_name`	Filter services by Kubernetes DaemonSet. Refer to K8s DaemonSet name.	string (glob)	(unset)
`k8s_owner_name`	Filter services by Kubernetes Pod owner (Deployment, ReplicaSet, DaemonSet, or StatefulSet). Refer to K8s owner name.	string (glob)	(unset)
`k8s_pod_labels`	Filter services by Kubernetes Pod labels. Refer to K8s Pod labels.	map[string]string (glob)	(unset)
`k8s_pod_annotations`	Filter services by Kubernetes Pod annotations. Refer to K8s Pod annotations.	map[string]string (glob)	(unset)
`exports`	Control what telemetry data to export for the matching service. Refer to Exports.	list of strings	(all signals)

Name

Defines a name for the matching instrumented service. Beyla uses it to populate the service.name OTEL property and the service_name Prometheus property in the exported metrics and traces.

This option is deprecated, as multiple matches for the same instrument entry mean multiple services share 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 you don’t set this property, Beyla uses 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, or StatefulSet that runs the instrumented process, if any
3. The name of the Pod that runs the instrumented process
If Kubernetes isn’t enabled:
1. The name of the process executable file

If multiple processes match the service selection criteria, 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 lets you differentiate the different instances of the service.

Namespace

Defines a namespace for the matching instrumented service. If you don’t set this property, Beyla uses the Kubernetes namespace of the instrumented process, if available, or leaves it empty if Kubernetes isn’t 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.

This namespace is not a selector for Kubernetes namespaces. Beyla uses its value to set the value of standard telemetry attributes. For example, the OpenTelemetry service.namespace attribute.

Open ports

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 matches only one of the ports in the list, Beyla considers it a match.

For example, specifying the following property:

discovery:
  instrument:
    - open_ports: 80,443,8000-8999

Beyla selects any executable that opens port 80, 443, or any of the ports between 8000 and 8999 included.

If you specify other selectors in the same instrument entry, the processes must match all the selector properties.

If an executable opens multiple ports, you only need to specify one of those ports for Beyla to instrument all the HTTP/S and GRPC requests on all application ports. Currently, you can’t restrict the instrumentation only to the methods exposed through a specific port.

Executable path

Selects the processes to instrument by their executable name path. This property accepts a glob to match against the full executable command line, including the directory where the executable resides on the file system.

Beyla tries to instrument all the processes with an executable path matching this property. For example, setting exe_path: * makes Beyla try to instrument all the executables in the host.

If you specify other selectors in the same instrument entry, the processes must match all the selector properties.

Containers only

Selects processes to instrument which are running in an OCI container. To perform this check, Beyla inspects the process network namespace and matches it against its own network namespace. If Beyla doesn’t have enough permissions to perform the network namespace inspection, it ignores this option.

If you specify other selectors in the same instrument entry, the processes must match all the selector properties.

Container name

This selector property limits the instrumentation to the applications running in OCI containers (such as Docker) with a name matching the provided glob pattern.

For example:

discovery:
  instrument:
    - container_name: "*testserver*"
    - container_name: "my-app-*"

This example discovers all processes running in containers whose names contain testserver or start with my-app-.

If you specify other selectors in the same instrument entry, the processes must match all the selector properties.

K8s namespace

This selector property limits the instrumentation to the applications running in the Kubernetes Namespaces with a name matching the provided glob.

If you specify other selectors in the same instrument entry, the processes must match all the selector properties.

K8s Pod name

This selector property limits the instrumentation to the applications running in the Kubernetes Pods with a name matching the provided glob.

If you specify other selectors in the same instrument entry, the processes must match all the selector properties.

K8s deployment name

This selector property limits the instrumentation to the applications running in the Kubernetes Deployments with a name matching the provided glob.

If you specify other selectors in the same instrument entry, the processes must match all the selector properties.

K8s replicaset name

This selector property limits the instrumentation to the applications running in the Kubernetes ReplicaSets with a name matching the provided glob.

If you specify other selectors in the same instrument entry, the processes must match all the selector properties.

K8s statefulset name

This selector property limits the instrumentation to the applications running in the Kubernetes StatefulSets with a name matching the provided glob.

If you specify other selectors in the same instrument entry, the processes must match all the selector properties.

K8s daemonset name

This selector property limits the instrumentation to the applications running in the Kubernetes DaemonSet with a name matching the provided glob.

If you specify other selectors in the same instrument entry, the processes must match all the selector properties.

K8s owner name

This selector property limits the instrumentation to the applications running in the Pods owned by a Deployment, ReplicaSet, DaemonSet, or StatefulSet with a name matching the provided glob.

If you specify other selectors in the same instrument entry, the processes must match all the selector properties.

K8s Pod labels

This selector property limits the instrumentation to the applications running in the Pods with labels matching the provided value as glob.

If you specify other selectors in the same instrument entry, the processes must match all the selector properties.

For example:

discovery:
  instrument:
    - k8s_namespace: frontend
      k8s_pod_labels:
        instrument: beyla

The preceding example discovers all Pods in the frontend namespace that have a label instrument with a value that matches the glob beyla.

K8s Pod annotations

This selector property limits the instrumentation to the applications running in the Pods with annotations matching the provided value as glob.

If you specify other selectors in the same instrument entry, the processes must match all the selector properties.

For example:

discovery:
  instrument:
    - k8s_namespace: backend
      k8s_pod_annotations:
        beyla.instrument: "true"

The preceding example discovers all Pods in the backend namespace that have an annotation beyla.instrument with a value that matches the glob true.

Exports

Controls which telemetry signals Beyla exports for the matching service. This property enables per-service feature enablement, allowing you to selectively enable specific observability capabilities for different services within a single Beyla instance.

The exports property accepts a list containing metrics, traces, or both. An empty list [] disables export for the service. If not specified, Beyla exports all configured telemetry signals.

For example:

discovery:
  instrument:
    - k8s_deployment_name: "*"
      exports: [metrics]
    - k8s_deployment_name: backend
      exports: [traces]
    - k8s_deployment_name: worker
      exports: []

This example configures Beyla to export only metrics for all services. For the specific case of backend, only traces are enabled, and for worker, everything is disabled. The order of defined instrument selectors matters, as later entries can override earlier export rules.

For an export signal to function, you must configure the corresponding exporter in Beyla. For example, specifying traces in the exports list requires configuring the OTLP traces exporter via otel_traces_export. Specifying metrics requires configuring at least one metrics exporter, such as prometheus_export or otel_metrics_export. If you specify an export signal without configuring the corresponding exporter, Beyla ignores that signal.

Metrics export features

Additionally to configuring custom export modes per discovery instrumentation criteria, Beyla allows you to override the global metrics export features for each discovery criteria by adding metrics > features as a property to individual discovery > instrument entries.

For example:

metrics:
  features: ['application_service_graph']
discovery:
  instrument:
    - open_ports: 3030,3040
      metrics:
        features:
          - 'application'
          - 'application_span'
          - 'application_service_graph'
    - name: pyserver
      open_ports: 7773
      metrics:
        features:
          - 'application'
    - name: apache
      open_ports: 8080
    - name: nginx
      open_ports: 8085
    - name: tomcat
      open_ports: 8090

This example configures Beyla to only export application service graph metrics by default, but it later overrides specific discovery criteria with different set of exported metrics. The outcome of the configuration is as follows:

The apache, nginx, and tomcat service instances only export application_service_graph metrics (as defined in the top-level metrics > features configuration).
The pyserver service only exports the application group of metrics.
Services listening on ports 3030 or 3040 export the application, application_span, and application_service_graph metric groups.

Custom trace sampler

By using the sampler property for an instrument definition criteria, you can define individual trace sampling strategy for each instrument criteria. This option overrides the default specified trace sampling configuration if it is defined for all instrumented services. For more details on configuring sampling, refer to the sample traces documentation section.

For example:

discovery:
  instrument:
    - k8s_deployment_name: backend
      sampler:
        name: "traceidratio"
        arg: "0.1"      
    - k8s_deployment_name: worker
otel_traces_export:
  sampler:
    name: "traceidratio"
    arg: "0.5"

This example configures a global trace sampling configuration with the traceidratio sampling option of 50%, for all instrumented services. However, for the deployment name backend, this discovery criteria defines an override that uses the same traceidratio sampling option, but samples only 10% of the traces.

Custom route matching rules

By using the routes property for an instrument definition criteria, you can define individual incoming and outgoing route matching rules for each instrument criteria. This option appends to the default specified route matching patterns if it is defined for all instrumented services. For more details on configuring route matching patterns, refer to the routes decorator documentation section.

Unlike the default routes pattern matching configuration option, the instrument definition criteria routes option has separate section for defining route matching rules for incoming and outgoing requests. This allows for precise control of your HTTP route cardinality.

For example:

discovery:
  instrument:
    - k8s_deployment_name: backend
      routes:
        incoming: ["/api/users/{user_id}", "/api/customers/{customer_id}"]
        outgoing: ["/*"]  
    - k8s_deployment_name: frontend
routes:
  patterns:
    - /user/{id}

In the example above, we have global route matching pattern definition for the HTTP route /user/{id}. However, the service backend has additional route matchers for incoming calls to /api/users/{user_id} and /api/customers/{customer_id}, and an additional outgoing request pattern for /*. If the backend service was making high-cardinality outgoing calls that we didn’t want to store in out metrics database, by specifying a catch all outgoing pattern of /*, we can selectively remove the problematic cardinality source without impacting all other services.

Survey mode

In survey mode, Beyla only performs service discovery and detects the programming language of each service, but doesn’t instrument any discovered services.

Beyla writes the discovered information from survey mode to a metric called survey_info, which uses the same attributes as the target_info metric. The Prometheus exporter creates this metric based on the OpenTelemetry metric resource attributes. You can use survey mode to build external automated instrumentation solutions. For example, you can use the survey_info metric to list available instrumentation targets and choose which ones to instrument.

Configure the survey section exactly like the instrument section. For more details, see the discovery services section of this document.

Exclude services from instrumentation

The exclude_instrument section lets you specify 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 helps you avoid instrumenting services typically found in observability environments. For example, use this option to exclude instrumenting Prometheus.

Default exclude services from instrumentation

The default_exclude_instrument section disables instrumentation of Beyla itself (self-instrumentation), as well as Grafana Alloy and the OpenTelemetry Collector. It also disables instrumentation of various Kubernetes system namespaces to reduce the overall cost of metric generation. The following section contains all excluded components:

Excluded services by exe_path: *beyla, *alloy, *ebpf-instrument, *obi, *otelcol, *otelcol-contrib, *otelcol-contrib[!/]*.
Excluded services by k8s_namespace: kube-system, kube-node-lease, local-path-storage, grafana-alloy, cert-manager, monitoring, gke-connect, gke-gmp-system, gke-managed-cim, gke-managed-filestorecsi, gke-managed-metrics-server, gke-managed-system, gke-system, gke-managed-volumepopulator, gatekeeper-system.

Change this option to allow Beyla to instrument itself or some of the other excluded components.

Note: to enable such self-instrumentation, you still need to include them in the instrument section, or these components need to be a part of a encompassing inclusion criteria.

Skip go specific tracers

The skip_go_specific_tracers option disables the detection of Go specifics when the ebpf tracer inspects executables to be instrumented. The tracer falls back to using generic instrumentation, which is generally less efficient. This option should only be used for Go services built with Go versions older than 1.17.

Exclude otel instrumented services

The exclude_otel_instrumented_services option disables Beyla instrumentation of services 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 you carefully craft the instrumentation selection (or exclusion) criteria. To avoid unnecessary configuration overhead, Beyla monitors for OpenTelemetry SDK calls to publish metrics and traces, and automatically turns off instrumentation of services that 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.

Override service name and namespace

If you export instrumentation data via OpenTelemetry or Prometheus, Beyla follows the service name conventions from the OpenTelemetry operator to improve interoperability with other instrumentation solutions.

Beyla uses the following criteria in this order to automatically set the service name and namespace:

Resource attributes set via OTEL_RESOURCE_ATTRIBUTES and OTEL_SERVICE_NAME environment variables of the instrumented process or container.
In Kubernetes, resource attributes set via the following Pod annotations:
- resource.opentelemetry.io/service.name
- resource.opentelemetry.io/service.namespace
In Kubernetes, resource attributes set via the following Pod labels:
- app.kubernetes.io/name sets the service name
- app.kubernetes.io/part-of sets the service namespace
In Kubernetes, resource attributes calculated from the Pod owner’s metadata, in the following order (according to their availability):
- k8s.deployment.name
- k8s.replicaset.name
- k8s.statefulset.name
- k8s.daemonset.name
- k8s.cronjob.name
- k8s.job.name
- k8s.pod.name
- k8s.container.name
The executable name of the instrumented process.

You can override the Kubernetes labels from the previous bullet 3 via configuration.

In YAML:

attributes:
  kubernetes:
    resource_labels:
      service.name:
        # gets service name from the first existing Pod label
        - override-svc-name
        - app.kubernetes.io/name
      service.namespace:
        # gets service namespace from the first existing Pod label
        - override-svc-ns
        - app.kubernetes.io/part-of

They accept a comma-separated list of annotation and label names.

Minimum process age

The min_process_age (environment variable BEYLA_MIN_PROCESS_AGE) option sets a requirement for a process to be alive for at least certain amount of time before it is considered for instrumentation. The default value is "5s" (five seconds). This option is a performance optimization related to cost of processing discovered binaries based on the chosen discovery criteria. It avoids instrumenting periodic short lived processes.

Route harvesting

Since Beyla instruments at the protocol level, for HTTP requests we see the actual URL path, while the OpenTelemetry specification requires that we provide a low-cardinality URL route. Beyla has purpose built route detector, which uses heuristics and cardinality reduction logic to automatically determine the low-cardinality route from the protocol provided URL path (for more information on this refer to Routes Decorator). However, for certain programming languages, Beyla can process the application symbols and extract the actual routes set in the application.

Currently the route harvesting is supported for Java, Go and NodeJS.

YAML environment variable	Description	Type	Default
`route_harvester_timeout` `BEYLA_ROUTE_HARVESTER_TIMEOUT`	A timeout to abandon the route harvesting if it takes too long	string	“10s”
`disabled_route_harvesters`	A list of disabled route harvesters. Available choices: ["`java`", “`nodejs`”, “`go`”]	list of strings	(empty)

The route harvesting for Java applications works by communicating with the JVM at runtime. Java application typically load after a bit of time, which may result in incomplete route information, if Beyla harvests the Java application routes immediately as it instruments the process. Therefore, Beyla performs Java route harvesting on Java applications which have been running for at least 60 seconds. This value can be modified by setting the environment variable BEYLA_JAVA_ROUTE_HARVEST_DELAY or by setting the configuration file option:

discovery:
  route_harvester_advanced:
    java_harvest_delay: 30s

Configure Beyla metrics and traces attributes

Wed, 15 Apr 2026 16:46:57 +0000

Configure Beyla metrics and traces attributes

You can configure how Beyla decorates attributes for metrics and traces. Use the attributes top YAML section to enable and configure how attributes are set.

The Beyla exported metrics document lists the attributes you can report with each metric. Beyla reports some attributes by default and hides others to control cardinality.

For each metric, you control which attributes to see with the select subsection. This is a map where each key is the name of a metric either in its OpenTelemetry or Prometheus port, and each metric has two sub-properties: include and exclude.

include is a list of attributes to report. Each attribute can be a name or a wildcard, for example, k8s.dst.* to include all attributes starting with k8s.dst. If you don’t provide an include list, Beyla reports the default attribute set, refer to Beyla exported metrics for more information about default attributes for a given metric
exclude is a list of attribute names or wildcards to remove from the include list, or the default attribute set

Example:

attributes:
  select:
    beyla_network_flow_bytes:
      # limit the beyla_network_flow_bytes attributes to only the three attributes
      include:
        - beyla.ip
        - src.name
        - dst.port
    db_client_operation_duration:
      # report all the possible attributes but db_query_text
      include: ["*"]
      exclude: ["db_query_text"]
    http_client_request_duration:
      # report the default attribute set but exclude the Kubernetes Pod information
      exclude: ["k8s.pod.*"]

Additionally, you can use wildcards as metric names to add and exclude attributes for groups of metrics with the same name. For example:

attributes:
  select:
    http_*:
      include: ["*"]
      exclude: ["http_path", "http_route"]
    http_client_*:
      # override http_* exclusion
      include: ["http_path"]
    http_server_*:
      # override http_* exclusion
      include: ["http_route"]

In the previous example, all metrics with a name starting with http_ or http. include all possible attributes except http_path and http_route or http.path/http.route. The http_client_* and http_server_* sections override the base configuration, enabling the http_path attribute for HTTP client metrics and http_route for HTTP server metrics.

When a metric name matches multiple definitions using wildcards, exact matches take precedence over wildcard matches.

Instance ID decoration

YAML section: attributes.instance_id

Beyla decorates metrics and traces with a unique instance ID string, identifying each instrumented application. By default, Beyla uses the host name that runs Beyla (can be a container or Pod name), followed by the PID of the instrumented process. You can override how the instance ID is composed in the instance_id YAML subsection under the attributes top-level section.

For example:

attributes:
  instance_id:
    dns: false

YAML environment variable	Description	Type	Default
`dns` `BEYLA_HOSTNAME_DNS_RESOLUTION`	If `true`, Beyla tries to resolve the local hostname against the network DNS. If `false`, uses local name. For more information, refer to the dns section.	boolean	true
`override_hostname` `BEYLA_HOSTNAME`	If set, Beyla uses the provided string as the host part of the Instance ID. Overrides DNS resolution. For more information, refer to the override hostname section.	string	(unset)

DNS

If true, Beyla tries to resolve the local hostname against the network DNS. If false, it uses the local hostname.

Override hostname

If set, Beyla uses the provided string as the host part of the Instance ID instead of trying to resolve the host name. This option takes precedence over dns.

Kubernetes decorator

YAML section: attributes.kubernetes

You can configure the component under the attributes.kubernetes section of your YAML configuration or via environment variables.

To enable this feature, you must provide extra permissions to the Beyla Pod. See the “Configuring Kubernetes metadata decoration section” in the “Running Beyla in Kubernetes” page.

If you set this option to true, Beyla decorates metrics and traces with Kubernetes metadata. If you set it to false, Beyla disables the Kubernetes metadata decorator. If you set it to autodetect, Beyla tries to detect if it is running inside Kubernetes and enables metadata decoration if so.

For example:

attributes:
  kubernetes:
    enable: true

YAML environment variable	Description	Type	Default
`enable` `BEYLA_KUBE_METADATA_ENABLE`	Enable or disable Kubernetes metadata decoration. Set to `autodetect` to enable if running in Kubernetes. For more information, refer to the enable kubernetes section.	boolean/string	false
`kubeconfig_path` `KUBECONFIG`	Path to the Kubernetes configuration file. For more information, refer to the Kubernetes configuration path section.	string	~/.kube/config
`disable_informers` `BEYLA_KUBE_DISABLE_INFORMERS`	List of informers to disable (`node`, `service`). For more information, refer to the disable informers section.	string	(empty)
`meta_restrict_local_node` `BEYLA_KUBE_META_RESTRICT_LOCAL_NODE`	Restrict metadata to local node only. For more information, refer to the meta restrict local node section.	boolean	false
`informers_sync_timeout` `BEYLA_KUBE_INFORMERS_SYNC_TIMEOUT`	Maximum time to wait for Kubernetes metadata before starting. For more information, refer to the informers sync timeout section.	Duration	30s
`informers_resync_period` `BEYLA_KUBE_INFORMERS_RESYNC_PERIOD`	Periodically resynchronize all Kubernetes metadata. For more information, refer to the informers resynchronization period section.	Duration	30m
`service_name_template` `BEYLA_SERVICE_NAME_TEMPLATE`	Go template for service names. For more information, refer to the service name template section.	string	(empty)

Enable kubernetes

If you run Beyla in a Kubernetes environment, you can configure it to decorate traces and metrics with the standard OpenTelemetry labels:

k8s.namespace.name
k8s.deployment.name
k8s.statefulset.name
k8s.replicaset.name
k8s.daemonset.name
k8s.node.name
k8s.pod.name
k8s.container.name
k8s.pod.uid
k8s.pod.start_time
k8s.cluster.name

Kubernetes configuration path

This is a standard Kubernetes configuration environment variable. Use it to tell Beyla where to find the Kubernetes configuration to communicate with the Kubernetes Cluster. Usually, you do not need to change this value.

Disable informers

The accepted value is a list that might contain node and service.

This option lets you selectively disable some Kubernetes informers, which continuously listen to the Kubernetes API to get the metadata needed for decorating network metrics or application metrics and traces.

When you deploy Beyla as a DaemonSet in very large clusters, all the Beyla instances creating multiple informers might overload the Kubernetes API.

Disabling some informers causes reported metadata to be incomplete, but reduces the load on the Kubernetes API.

You cannot disable the Pods informer. To do that, disable the whole Kubernetes metadata decoration.

Meta restrict local node

If true, Beyla stores Pod and Node metadata only from the node where the Beyla instance runs.

This option decreases the memory used to store metadata, but some metrics such as network bytes or service graph metrics won’t include metadata from destination pods on a different node.

Informers sync timeout

This is the maximum time Beyla waits to get all the Kubernetes metadata before starting to decorate metrics and traces. If this timeout is reached, Beyla starts normally, but the metadata attributes might be incomplete until all the Kubernetes metadata is updated in the background.

Informers resynchronization period

Beyla immediately receives any update on resources’ metadata. In addition, Beyla periodically resynchronizes all Kubernetes metadata at the frequency you specify with this property. Higher values reduce the load on the Kubernetes API service.

Service name template

You can template service names using Go templates. This lets you create conditional or extended service names.

The following context is available to the template:

Meta: (*informer.ObjectMeta)
  Name: (string)
  Namespace: (string)
  Labels:
    label1: lv1
    label2: lv2
  Annotations:
    Anno1: av1
    Anno2: av2
  Pod: (*PodInfo)
  ...

ContainerName: (string)

You can find the full object and structure in the kubecache informer.pb.go source file.

Service name template examples:

{{- .Meta.Namespace }}/{{ index .Meta.Labels "app.kubernetes.io/name" }}/{{ index .Meta.Labels "app.kubernetes.io/component" -}}{{ if .ContainerName }}/{{ .ContainerName -}}{{ end -}}

{{- .Meta.Namespace }}/{{ index .Meta.Labels "app.kubernetes.io/name" }}/{{ index .Meta.Labels "app.kubernetes.io/component" -}}

In this example, only the first line is used and trimmed to prevent white space in the service name.

Extra group attributes

Beyla allows you to enhance your metrics with custom attributes using the extra_group_attributes configuration. This gives you the flexibility to include additional metadata in your metrics, beyond the standard set.

To use this feature, specify the group name and the list of attributes you want to include in that group.

Currently, only the k8s_app_meta group is supported. This group contains Kubernetes-specific metadata such as Pod name, namespace, container name, Pod UID, and more.

Example configuration:

attributes:
  kubernetes:
    enable: true
  extra_group_attributes:
    k8s_app_meta: ["k8s.app.version"]

In this example:

Adding k8s.app.version to the extra_group_attributes > k8s_app_meta block causes the k8s.app.version label to appear in the metrics.
You can also define annotations with the prefix resource.opentelemetry.io/ and suffix k8s.app.version in your Kubernetes manifests, these annotations are automatically included in the metrics.

The following table describes the default group attributes.

Group	Label
`k8s_app_meta`	`k8s.namespace.name`
`k8s_app_meta`	`k8s.pod.name`
`k8s_app_meta`	`k8s.container.name`
`k8s_app_meta`	`k8s.deployment.name`
`k8s_app_meta`	`k8s.replicaset.name`
`k8s_app_meta`	`k8s.daemonset.name`
`k8s_app_meta`	`k8s.statefulset.name`
`k8s_app_meta`	`k8s.node.name`
`k8s_app_meta`	`k8s.pod.uid`
`k8s_app_meta`	`k8s.pod.start_time`
`k8s_app_meta`	`k8s.cluster.name`
`k8s_app_meta`	`k8s.owner.name`

And the following table describes the metrics and their associated groups.

Group	OTEL Metric	Prom Metric
`k8s_app_meta`	`process.cpu.utilization`	`process_cpu_utilization_ratio`
`k8s_app_meta`	`process.cpu.time`	`process_cpu_time_seconds_total`
`k8s_app_meta`	`process.memory.usage`	`process_memory_usage_bytes`
`k8s_app_meta`	`process.memory.virtual`	`process_memory_virtual_bytes`
`k8s_app_meta`	`process.disk.io`	`process_disk_io_bytes_total`
`k8s_app_meta`	`messaging.publish.duration`	`messaging_publish_duration_seconds`
`k8s_app_meta`	`messaging.process.duration`	`messaging_process_duration_seconds`
`k8s_app_meta`	`http.server.request.duration`	`http_server_request_duration_seconds`
`k8s_app_meta`	`http.server.request.body.size`	`http_server_request_body_size_bytes`
`k8s_app_meta`	`http.server.response.body.size`	`http_server_response_body_size_bytes`
`k8s_app_meta`	`http.client.request.duration`	`http_client_request_duration_seconds`
`k8s_app_meta`	`http.client.request.body.size`	`http_client_request_body_size_bytes`
`k8s_app_meta`	`http.client.response.body.size`	`http_client_response_body_size_bytes`
`k8s_app_meta`	`rpc.client.duration`	`rpc_client_duration_seconds`
`k8s_app_meta`	`rpc.server.duration`	`rpc_server_duration_seconds`
`k8s_app_meta`	`db.client.operation.duration`	`db_client_operation_duration_seconds`
`k8s_app_meta`	`gpu.kernel.launch.calls`	`gpu_kernel_launch_calls_total`
`k8s_app_meta`	`gpu.kernel.grid.size`	`gpu_kernel_grid_size_total`
`k8s_app_meta`	`gpu.kernel.block.size`	`gpu_kernel_block_size_total`
`k8s_app_meta`	`gpu.memory.allocations`	`gpu_memory_allocations_bytes_total`

Configure cardinality limits

YAML section: attributes

Since Beyla instruments at the protocol level, it doesn’t have access to programming language/framework information about host names or URL routes. Therefore, it’s possible to create a metric cardinality explosion, without putting restrictions on how many possible values can be reported for a given metric label. To limit the possibility of cardinality explosion, Beyla has several options that control cardinality.

YAML environment variable	Description	Type	Default
`metric_span_names_limit` `BEYLA_METRIC_SPAN_NAMES_LIMIT`	Sets the maximum cardinality of the `span_name` attribute for span metrics. See more details below.	int	(100)
`rename_unresolved_hosts` `BEYLA_RENAME_UNRESOLVED_HOSTS`	Value used for the host and peer service graph attributes when they are empty or contain unresolved IP addresses to reduce cardinality.	string	“unresolved”
`rename_unresolved_hosts_outgoing` `BEYLA_RENAME_UNRESOLVED_HOSTS_OUTGOING`	Value used for the client peer service graph attribute when it’s empty or contain unresolved IP addresses to reduce cardinality.	string	“outgoing”
`rename_unresolved_hosts_incoming` `BEYLA_RENAME_UNRESOLVED_HOSTS_INCOMING`	Value used for the client peer service graph attribute when it’s empty or contain unresolved IP addresses to reduce cardinality.	string	“incoming”

Metric span name limit

metric_span_names_limit works per service and only relates to span metrics (metrics option application_span). When the span_name cardinality surpasses this limit, the span_name is be reported as AGGREGATED for all future spans. If the value is set to less or equal to zero, the aggregation is disabled.

Unresolved host names

rename_unresolved_hosts, rename_unresolved_hosts_outgoing and rename_unresolved_hosts_incoming only affect service graph metrics (metrics option application_service_graph).

Configure Beyla host name resolution

Wed, 15 Apr 2026 16:46:57 +0000

Configure Beyla service host and peer name resolution

Since Beyla instruments at the protocol level, it doesn’t have access to programming language/framework information about host and peer names. Instead, Beyla has access to the IP addresses used for the communication between the services which are monitored. Therefore Beyla sources this information from metadata services, such as the Kubernetes API, or from information found in protocol headers, for example HTTP’s Host header value.

Name resolution configuration

YAML section: name_resolver

YAML environment variable	Description	Type	Default
`sources` `BEYLA_NAME_RESOLVER_SOURCES`	A comma separated list of metadata sources to use for name resolution. More details below.	list of strings	[“k8s”]
`cache_len` `BEYLA_NAME_RESOLVER_CACHE_LEN`	Size of the service name cache. Used to speed up reverse IP lookups.	int	(1024)
`cache_expiry` `BEYLA_NAME_RESOLVER_CACHE_TTL`	Time-to-live value for the service name cache.	string	“5m”

The possible values for the name resolver sources are:

k8s. Use Kubernetes API metadata for reverse IP address lookup.
dns. Use the host DNS for reverse IP address lookup. This option can cause flood of DNS requests in certain situations and should be used only on services that are not exposed to the Internet.
rdns. Beyla tracks DNS requests for instrumentation purposes. This option uses that information to build internal cache of DNS resolved names.

Configure Beyla instrumentation options

Wed, 15 Apr 2026 16:46:57 +0000

Configure Beyla instrumentation options

This configuration section describes various options for controlling the instrumentation capabilities of Beyla related to distributed traces, context propagation and various protocol instrumentation options.

Distributed traces and context propagation

YAML section: ebpf

You can configure the component under the ebpf section of your YAML configuration or via environment variables.

YAML environment variable	Description	Type	Default
`enable_context_propagation` `BEYLA_BPF_ENABLE_CONTEXT_PROPAGATION`	Deprecated. Use `context_propagation` instead. For more information, refer to the enable context propagation section.	boolean	false
`context_propagation` `BEYLA_BPF_CONTEXT_PROPAGATION`	Controls trace context propagation method. Accepted: `all`, `headers`, `ip`, `disabled`. For more information, refer to the context propagation section.	string	disabled
`track_request_headers` `BEYLA_BPF_TRACK_REQUEST_HEADERS`	Track incoming `Traceparent` headers for trace spans. For more information, refer to the track request headers section.	boolean	false

Enable context propagation

Deprecated. Use context_propagation instead.

Context propagation

Beyla injects the Traceparent header value for outgoing HTTP requests, so it can propagate any incoming context to downstream services. This context propagation works for any programming language.

For TLS encrypted HTTP requests (HTTPS), Beyla encodes the Traceparent header value at the TCP/IP packet level. Beyla must be present on both sides of the communication.

The TCP/IP packet level encoding uses Linux Traffic Control (TC). eBPF programs that also use TC must chain correctly with Beyla. For more information about chaining programs, see the Cilium compatibility documentation.

You can disable the TCP/IP level encoding and TC programs by setting context_propagation="headers". This context propagation is fully compatible with any OpenTelemetry distributed tracing library.

Context propagation values:

all: Enable both HTTP and IP options context propagation
headers: Enable context propagation via the HTTP headers only
ip: Enable context propagation via the IP options field only
disabled: Disable trace context propagation

To use this option in containerized environments (Kubernetes and Docker), you must:

Deploy Beyla as a DaemonSet with host network access hostNetwork: true
Volume mount the /sys/fs/cgroup path from the host as local /sys/fs/cgroup path
Grant the CAP_NET_ADMIN capability to the Beyla container

gRPC and HTTP2 are not supported.

For an example of how to configure distributed traces in Kubernetes, see our Distributed traces with Beyla guide.

Track request headers

This option lets Beyla process any incoming Traceparent header values. If enabled, when Beyla sees an incoming server request with a Traceparent header value, it uses the provided ’trace id’ to create its own trace spans.

This option does not affect Go applications, where the Traceparent field is always processed.

Enabling this option may increase performance overhead in high request volume scenarios. This option is only useful when generating Beyla traces; it does not affect metrics.

Payload extraction

Various cloud and database protocols are implemented on top of HTTP. For example, all AWS S3 (Amazon Web Services) requests are in fact HTTP requests. To create better traces and metrics, Beyla has custom protocol detectors which run on top of HTTP, by performing HTTP payload extraction. You can configure which payload extractors are enabled by default with the following options:

YAML section:

ebpf:
  http:
    graphql:

YAML option Environment variable	Description	Type	Default
`enabled` `BEYLA_HTTP_GRAPHQL_ENABLED`	Enable GraphQL protocol detection in HTTP payload processing.	boolean	(true)

YAML section:

ebpf:
  http:
    elasticsearch:

YAML option Environment variable	Description	Type	Default
`enabled` `BEYLA_HTTP_HTTP_ELASTICSEARCH_ENABLED`	Enable Elasticsearch protocol detection in HTTP payload processing. See below for details.	boolean	(true)

Opensearch is a fork of Elasticsearch and therefore also supported.

Product	Methods	Version
`Elasticsearch`	/_search, /_msearch, /_bulk, /_doc	7.14+
`Opensearch`	/_search, /_msearch, /_bulk, /_doc	3.0.0+

YAML section:

ebpf:
  http:
    aws:

YAML option Environment variable	Description	Type	Default
`enabled` `BEYLA_HTTP_HTTP_AWS_ENABLED`	Enable AWS services protocol detection in HTTP payload processing. See below for list of AWS supported protocols.	boolean	(true)

List of supported AWS services protocol detectors:

Protocol	Methods
S3	CreateBucket, DeleteBucket, PutObject, DeleteObject, ListBuckets, ListObjects, GetObject
SQS	All

Configure data processing buffer sizes

To minimize the performance impact of eBPF data collection, Beyla uses limited payload buffer size capture for various protocols, which gives us the best quality to performance ratio. However, for certain kinds of protocols, especially for some that are mentioned in Payload extraction, it might be beneficial to use larger buffer sizes. The following section describes the configuration options for controlling the auxiliary buffers captured for higher quality trace generation.

YAML section:

ebpf:
  buffer_sizes:

YAML option Environment variable	Description	Type	Default	Maximum
`http` `BEYLA_BPF_BUFFER_SIZE_HTTP`	Auxiliary buffer size (in bytes) for HTTP protocol capture.	int	(0)	8192
`mysql` `BEYLA_BPF_BUFFER_SIZE_MYSQL`	Auxiliary buffer size (in bytes) for MYSQL protocol capture.	int	(0)	8192
`postgres` `BEYLA_BPF_BUFFER_SIZE_POSTGRES`	Auxiliary buffer size (in bytes) for POSTGRESQL protocol capture.	int	(0)	8192

Other attributes

YAML section: ebpf

YAML option Environment variable	Description	Type	Default
`heuristic_sql_detect` `BEYLA_HEURISTIC_SQL_DETECT`	Enable heuristic SQL client detection. See below for details.	boolean	(false)

The heuristic sql detect option lets Beyla detect SQL client requests by inspecting query statements, even if the protocol is not directly supported. By default, Beyla detects SQL client requests by their binary protocol format. If you use a database technology not directly supported by Beyla, you can enable this option to get database client telemetry. This option is not enabled by default, because it can create false positives, for example, if an application sends SQL text for logging through a TCP connection. Currently, Beyla natively supports the Postgres and MySQL binary protocols.

YAML option Environment variable	Description	Type	Default
`max_transaction_time` `BEYLA_BPF_MAX_TRANSACTION_TIME`	Maximum allowed transaction time. See below for details.	string	(5m)

The max_transaction_time option configures the distributed tracing transaction correlation maximum allowed time. It specifies the maximum time allowed for two requests to be correlated as parent -> child. This is implemented as a safety measure for limiting the maximum possible trace size, because some programs (for example load generators) keep on generating requests from the same thread in perpetuity, which can generate very large traces. If a child request has started later than the time specified by max_transaction_time, then we consider the two requests not correlated to prevent infinite traces.

Configure Beyla language specific agents

Wed, 15 Apr 2026 16:46:57 +0000

Language specific agents

Certain programming languages that Beyla instruments are using managed runtimes with complicated threading models, such that Beyla cannot perform correct thread context propagation solely by using eBPF based techniques. In certain situations, for example Java, capturing TLS traffic is also not possible by eBPF techniques, because the Java SDK has its own TLS implementation written in Java. A lot of these programming languages start program execution with interpreters, but later perform method or execution trace compilation using Just-In-Time(JIT) compilers, which generate code in anonymous memory regions. These anonymous regions cannot be attached to with eBPF uprobes, because there is no Linux inode number associated with them. Therefore, it’s not possible to perform eBPF instrumentation on the generated code, without potentially unstable techniques of stopping the program with ptrace and remapping the anonymous regions to memory mapped files.

Because of the inherent limitation of certain programming languages and technologies, Beyla dynamically injects tiny language specific agents for certain languages, to be able to perform TLS traffic capture and context propagation. Currently, Beyla uses language agents for Java and NodeJS.

YAML section: nodejs

YAML option Environment variable	Description	Type	Default
`enabled` `BEYLA_NODEJS_ENABLED`	Enable dynamic injection of the `NodeJS` agent.	boolean	(true)

The NodeJS agent is used only for context propagation, since NodeJS uses libssl for TLS encryption and decryption. This agent is injected via the debugger interface. You should disable the NodeJS agent support if your program has a handler attached on SIGUSR1.

YAML section: javaagent

YAML option Environment variable	Description	Type	Default
`enabled` `BEYLA_JAVAAGENT_ENABLED`	Enable dynamic injection of the Java agent.	boolean	(true)
`attach_timeout` `BEYLA_JAVAAGENT_ATTACH_TIMEOUT`	Timeout for waiting on dynamic attach to succeed.	string	“10s”

The Java agent is used for both context propagation and for TLS traffic capture. The dynamic injection of the agent is supported for OpenJDK Hotspot JVM (and derivatives) and for OpenJ9. Minimum Java version supported is Java 8. If the JVM is busy during the agent attach process, the attach process may take longer than 10 seconds. You can use the attach_timeout option to increase the time Beyla waits for the dynamic attach to successfully complete.

Injection of the Java agent requires that the target process has writeable file system, for example, the injection process doesn’t work for containers with read-only file systems.

Filter metrics and traces by attribute values

Wed, 15 Apr 2026 16:46:57 +0000

Filter metrics and traces by attribute values

You might want to restrict the reported metrics and traces to very concrete event types based on the values of the attributes (for example, filter network metrics to report only TCP traffic).

The filter YAML section allows filtering both application and network metrics by attribute values. It has the following structure:

filter:
  application:
    # map of attribute matches to restrict application metrics
  network:
    # map of attribute matches to restrict network metrics

For a list of metrics under the application and network family, as well as their attributes, check the Beyla exported metrics document.

Each application and network filter section is a map where each key is an attribute name (either in Prometheus or OpenTelemetry format), with either the match or the not_match property. Both properties accept a glob-like string (it can be a full value or include wildcards). If you set the match property, Beyla only reports the metrics and traces matching the provided value for that given attribute. The not_match property is the negation of match.

The following example reports network metrics for connections targeting the destination port 53, excluding the UDP protocol:

filter:
  network:
    transport:
      not_match: UDP
    dst_port:
      match: "53"

The following example filters application metrics to only report database operations for PostgreSQL and MongoDB:

filter:
  application:
    db.system.name:
      match: "{postgresql,mongodb}"

Configure Beyla routes decorator

Wed, 15 Apr 2026 16:46:57 +0000

Configure Beyla routes decorator

YAML section: routes

You can configure this component in the routes section of your YAML configuration or with environment variables.

You must configure this section in the YAML file. If you don’t provide a routes section, Beyla creates a default routes pipeline stage and uses the heuristic routes decorator.

For example:

routes:
  patterns:
    - /basic/:rnd
  unmatched: path
  ignored_patterns:
    - /metrics
  ignore_mode: traces

YAML	Description	Type	Default
`patterns`	List of URL path patterns to match and set the `http.route` property. Refer to patterns.	list of strings	(unset)
`ignored_patterns`	List of URL path patterns to ignore. Discards trace/metric events if matched. Refer to ignored patterns.	list of strings	(unset)
`ignore_mode`	Specifies which event types to ignore when using `ignored_patterns`. Refer to ignore mode.	string	all
`unmatched`	Specifies what to do when an HTTP path doesn’t match any `patterns` entries. Refer to unmatched.	string	heuristic
`wildcard_char`	Character to use for path components replaced by cardinality reducing modes. Refer to wildcard char.	string	“*”
`max_path_segment_cardinality`	Maximum cardinality in a segment for the low-cardinality unmatched mode.	int	10

Patterns

Beyla matches the provided URL path patterns and sets the http.route trace/metric property. Use the routes property when possible to reduce the cardinality of generated metrics.

Each route pattern is a URL path with tags that group path segments. You can use the :name or {name} format for matcher tags.

For example, if you define these patterns:

routes:
  patterns:
    - /user/{id}
    - /user/{id}/basket/{product}

Traces with these HTTP paths have the same http.route='/user/{id}' property:

/user/123
/user/456

Traces with these HTTP paths have the same http.route='/user/{id}'/basket/{product} property:

/user/123/basket/1
/user/456/basket/3

The route matcher also supports the wildcard character *, which matches path prefixes. For example, if you define this pattern:

routes:
  patterns:
    - /user/*

Any traces with HTTP paths starting with /user (including /user itself) match the route /user/*. All these paths match as /user/*:

/user
/user/123
/user/123/basket/1
/user/456/basket/3

Ignored patterns

Beyla matches the provided URL path against the defined patterns and discards trace or metric events if they match any ignored_patterns. The format for ignored_patterns is identical to patterns. You can define ignored patterns with or without wildcard options. For example, if you define these ignored patterns:

routes:
  ignored_patterns:
    - /health
    - /v1/*

Any event paths with a prefix of /v1 or equal to /health are ignored.

This is useful to prevent certain paths used for development or service health monitoring from being recorded as traces or metrics.

Ignore mode

Use this property with ignored_patterns to specify which event types to ignore.

Possible values for ignore_mode are:

all discards both metrics and traces that match ignored_patterns
traces discards only traces that match ignored_patterns, metrics are still recorded
metrics discards only metrics that match ignored_patterns, traces are still recorded

For example, you may want performance metrics for your health check API but not the overhead of trace records in your traces database. Set ignore_mode to traces so only traces matching ignored_patterns are discarded, while metrics are still recorded.

Unmatched

This property specifies what to do when an HTTP path doesn’t match any patterns entries.

Possible values for unmatched are:

unset leaves the http.route property unset
path copies the path value to the http.route field. This can lead to cardinality explosion at the ingestion side
wildcard sets the http.route field to a generic asterisk-based /** value
heuristic automatically derives http.route from the path value using these rules:
- Path components with numbers or characters outside the ASCII alphabet (or - and _) are replaced by wildcard_char
- Alphabetical components that don’t look like words are replaced by wildcard_char
low-cardinality automatically derives http.route from the path value, ensuring path components with unbounded cardinality are replaced with wildcard_char.

Wildcard char

Use this property with unmatched: heuristic to choose the character that replaces path components identified by heuristic mode. By default, Beyla uses an asterisk '*'. The value should be quoted and must be a single character.

Heuristic route decorator mode

The heuristic decorator is a best effort route decorator, which may still lead to cardinality explosion in some scenarios. For example, GitHub URL paths are constructed like a directory tree, so all paths remain unique and lead to cardinality explosion. In this case consider the low-cardinality route decorator.

If your URL path patterns follow a certain structure and unique IDs are made of numbers or random characters, then the heuristic decorator may work for your use case with minimal configuration. For example, these mock Google Docs URLs are correctly reduced to a low cardinality version:

Both URL paths below:

document/d/CfMkAGbE_aivhFydEpaRafPuGWbmHfG/edit (no numbers in the ID)
document/d/C2fMkAGb3E_aivhFyd5EpaRafP123uGWbmHfG/edit

are converted to a low cardinality route (using the default wildcard_char):

document/d/*/edit

Low cardinality route decorator mode

Low cardinality route decorator mode extends the heuristic mode by performing additional cardinality reduction after applying heuristics.

The cardinality reduction logic detects cardinality explosion in specific URL path segments using this process:

It builds a per-service route database by deconstructing URL path segments into nodes. For example, with /api/users/123, there are three nodes: api -> users -> 123.
Each URL path segment node tracks how many unique children it has. For example, when processing /api/users/abc, /api/users/def, /api/users/xyz, the users node sees its children cardinality increase to 3.
High cardinality URL path segment nodes are automatically collapsed when a threshold is reached. When a node’s children exceed max_path_segment_cardinality, all children merge into a single wildcard node (wildcard_char). Future paths through that segment return the wildcard_char.

Example flow with low-cardinality mode and max_path_segment_cardinality=3:

Insert /api/users/alice -> /api/users/alice (cardinality: 1)
Insert /api/users/bob -> /api/users/bob (cardinality: 2)
Insert /api/users/carol -> /api/users/carol (cardinality: 3)
Insert /api/users/dave -> /api/users/* (threshold exceeded, collapsed)
Insert /api/users/eve -> /api/users/* (stays collapsed)

This means the first three routes match the original URL path. After the cardinality limit is reached, all future URL paths collapse to a low cardinality route.

Note that the per-service low-cardinality route database is in-memory only and resets on every Beyla restart.

Configure Beyla Prometheus and OpenTelemetry metrics histograms

Wed, 15 Apr 2026 16:46:57 +0000

Configure Beyla Prometheus and OpenTelemetry metrics histograms

You can configure Beyla Prometheus and OpenTelemetry metrics histograms. You can also choose to use native histograms and exponential histograms.

Override histogram buckets

You can override the histogram bucket boundaries for OpenTelemetry and Prometheus metrics exporters by setting the buckets YAML configuration option:

YAML section: otel_metrics_export.buckets

For example:

otel_metrics_export:
  buckets:
    duration_histogram: [0, 1, 2]

YAML	Type
`duration_histogram`	`[]float64`

Set the bucket boundaries for metrics related to request duration. Specifically:

http.server.request.duration (OTEL) / http_server_request_duration_seconds (Prometheus)
http.client.request.duration (OTEL) / http_client_request_duration_seconds (Prometheus)
rpc.server.duration (OTEL) / rpc_server_duration_seconds (Prometheus)
rpc.client.duration (OTEL) / rpc_client_duration_seconds (Prometheus)

If you leave the value unset, Beyla uses the default bucket boundaries from the OpenTelemetry semantic conventions:

0, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10

YAML section: prometheus_export.buckets

prometheus_export:
  buckets:
    request_size_histogram: [0, 10, 20, 22]
    response_size_histogram: [0, 10, 20, 22]

YAML	Type
`request_size_histogram`	`[]float64`
`response_size_histogram`	`[]float64`

Set the bucket boundaries for metrics related to request and response sizes:

http.server.request.body.size (OTEL) / http_server_request_body_size_bytes (Prometheus)
http.client.request.body.size (OTEL) / http_client_request_body_size_bytes (Prometheus)
http.server.response.body.size (OTEL) / http_server_response_body_size_bytes (Prometheus)
http.client.response.body.size (OTEL) / http_client_response_body_size_bytes (Prometheus)

If you leave the value unset, Beyla uses these default bucket boundaries:

0, 32, 64, 128, 256, 512, 1024, 2048, 4096, 8192

These default values are UNSTABLE and may change if Prometheus or OpenTelemetry semantic conventions recommend different bucket boundaries.

Use native histograms and exponential histograms

For Prometheus, you enable native histograms by enabling the native-histograms feature in your Prometheus collector.

For OpenTelemetry, you can use exponential histograms for the predefined histograms instead of defining the buckets manually. Set the standard OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION environment variable. See the histogram_aggregation section in the OTEL metrics exporter section for more information.

Configure Beyla OpenTelemetry trace sampling

Wed, 15 Apr 2026 16:46:57 +0000

Configure Beyla OpenTelemetry trace sampling

Beyla accepts the standard OpenTelemetry environment variables to configure the sampling ratio of traces.

YAML section: otel_traces_export.sampler

You can configure the component under the otel_traces_export.sampler section of your YAML configuration or via environment variables.

otel_traces_export:
  sampler:
    name: "traceidratio"
    arg: "0.1"

If you’re using Grafana Alloy as your OTEL collector, you can configure the sampling policy at that level instead.

YAML environment variable	Description	Type	Default
`name` `OTEL_TRACES_SAMPLER`	Specifies the name of the sampler. Accepts standard sampler names from the OpenTelemetry specification. Refer to sampler name for details.	string	`parentbased_always_on`
`arg` `OTEL_TRACES_SAMPLER_ARG`	Specifies the argument for the selected sampler. Only `traceidratio` and `parentbased_traceidratio` require an argument. Refer to sampler argument for details.	string	(unset)

Sampler name

The name property accepts the following standard sampler names:

always_on: samples every trace. Be careful using this sampler in an application with significant traffic: a new trace will be started and exported for every request
always_off: samples no traces
traceidratio: samples a given fraction of traces (specified by the arg property). The fraction must be a real value between 0 and 1. For example, a value of "0.5" samples 50% of the traces. Fractions >= 1 always sample. Fractions < 0 are treated as zero. To respect the parent trace’s sampling configuration, use the parentbased_traceidratio sampler
parentbased_always_on (default): parent-based version of always_on sampler
parentbased_always_off: parent-based version of always_off sampler
parentbased_traceidratio: parent-based version of traceidratio sampler

Parent-based samplers are composite samplers that behave differently based on the parent of the traced span. If the span has no parent, the root sampler is used to make the sampling decision. If the span has a parent, the sampling configuration depends on the sampling parent.

Sampler argument

The arg property specifies the argument for the selected sampler. Only traceidratio and parentbased_traceidratio require an argument.

In YAML, you MUST provide this value as a string. Even if the value is numeric, make sure to enclose it in quotes in the YAML file (for example, arg: "0.25").

Configure the Beyla internal metrics reporter

Wed, 15 Apr 2026 16:46:57 +0000

Configure the Beyla internal metrics reporter

YAML section: internal_metrics

This component reports internal metrics about the auto-instrumentation tool’s behavior. You can export these metrics using Prometheus or OpenTelemetry.

To export metrics with Prometheus, set exporter to prometheus in the internal_metrics section. Then set port in the prometheus subsection.

To export metrics with OpenTelemetry, set exporter to otel in the internal_metrics section. Then set an endpoint in the otel_metrics_export or grafana.otlp section.

Example:

internal_metrics:
  exporter: prometheus
  prometheus:
    port: 6060
    path: /internal/metrics

Configuration summary

YAML	Environment Variable	Type	Default	Summary
`exporter`	`BEYLA_INTERNAL_METRICS_EXPORTER`	string	`disabled`	Selects the internal metrics exporter.
`prometheus.port`	`BEYLA_INTERNAL_METRICS_PROMETHEUS_PORT`	int	(unset)	HTTP port for Prometheus scrape endpoint.
`prometheus.path`	`BEYLA_INTERNAL_METRICS_PROMETHEUS_PATH`	string	`/internal/metrics`	HTTP query path for Prometheus metrics.

Internal metrics exporter

Set the internal metrics exporter. You can use disabled, prometheus, or otel.

Prometheus port

Set the HTTP port for the Prometheus scrape endpoint. If you leave it unset or set it to 0, Beyla doesn’t open a Prometheus endpoint and doesn’t report metrics.

You can use the same value as prometheus_export.port (both metric families share the same HTTP server, but use different paths), or use a different value (Beyla opens two HTTP servers for the different metric families).

Prometheus path

Set the HTTP query path to fetch Prometheus metrics.

If prometheus_export.port and internal_metrics.prometheus.port use the same value, you can set internal_metrics.prometheus.path to a different value than prometheus_export.path to keep the metric families separate, or use the same value to list both metric families in the same scrape endpoint.

Configure Beyla performance

Wed, 15 Apr 2026 16:46:57 +0000

Configure Beyla performance

YAML section: grafana.otlp

You can use the eBPF tracer to fine-tune Beyla performance.

You can configure the component under the ebpf section of your YAML configuration or with environment variables.

YAML environment variable	Description	Type	Default
`wakeup_len` `BEYLA_BPF_WAKEUP_LEN`	Sets how many messages Beyla accumulates in the eBPF ring buffer before sending a wake-up request to user space. Refer to wake up length.	string	(unset)
`traffic_control_backend` `BEYLA_BPF_TC_BACKEND`	Selects the backend for attaching traffic control probes. Refer to the traffic control backend section for details.	string	`auto`
`http_request_timeout` `BEYLA_BPF_HTTP_REQUEST_TIMEOUT`	Sets the time interval after which Beyla considers an HTTP request a timeout. Refer to the HTTP request timeout section for details.	string	(0ms)
`high_request_volume` `BEYLA_BPF_HIGH_REQUEST_VOLUME`	Sends telemetry events as soon as Beyla detects a response. Refer to the high request volume section for details.	boolean	(false)
`dns_request_timeout` `BEYLA_BPF_DNS_REQUEST_TIMEOUT`	Sets the time interval after which Beyla considers an DNS request a timeout.	string	(5s)

Wake up length

Beyla accumulates messages in the eBPF ringbuffer and sends a wake-up request to user space when it reaches this value.

For high-load services, set this option higher to reduce CPU overhead.

For low-load services, high values can delay when Beyla submits metrics and when they become visible.

Traffic control backend

This option selects the backend for attaching traffic control probes. Linux 6.6 adds support for TCX, a file-descriptor based traffic control attachment. TCX is more robust, doesn’t require explicit qdisc management, and chains probes deterministically. We recommend the tcx backend for kernels >= 6.6. When set to auto, Beyla chooses the best backend for your kernel.

Accepted backends: tc, tcx, and auto. If you leave this value empty or unset, Beyla uses auto.

HTTP request timeout

This option sets how long Beyla waits before considering an HTTP request a timeout. Beyla can report HTTP transactions that time out and never return. Set this option to a non-zero value to enable automatic HTTP request timeouts. When a request times out, Beyla reports HTTP status code 408. Disconnects can look like timeouts, so setting this value may increase your request averages.

High request volume

This option makes Beyla send telemetry events as soon as it detects a response. It reduces timing accuracy for requests with large responses, but in high-volume scenarios, it helps reduce dropped trace events.

Beyla configuration YAML example

Wed, 15 Apr 2026 16:46:57 +0000

YAML file example

An example Beyla YAML configuration file to send OTLP data to Grafana Cloud OTLP endpoint:

discovery:
  instrument:
    - open_ports: 443
log_level: DEBUG

ebpf:
  wakeup_len: 100

otel_traces_export:
  endpoint: https://otlp-gateway-prod-eu-west-0.grafana.net/otlp

prometheus_export:
  port: 8999
  path: /metrics