---
title: "beyla.ebpf | Grafana Alloy documentation"
description: "Learn about beyla.ebpf"
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

# `beyla.ebpf`

> Note
> 
> The `beyla.ebpf` component uses Grafana Beyla version v3.28.0.

The `beyla.ebpf` component is a wrapper for [Grafana Beyla](https://github.com/grafana/beyla) which uses [eBPF](https://ebpf.io/) to automatically inspect application executables and the OS networking layer, and capture trace spans related to web transactions and Rate Errors Duration (RED) metrics for Linux HTTP/S and gRPC services. You can configure the component to collect telemetry data from a specific port or executable path, and other criteria from Kubernetes metadata. The component exposes metrics that can be collected by a Prometheus scrape component, and traces that can be forwarded to an OTel exporter component.

## Permissions

`beyla.ebpf` uses eBPF and needs elevated privileges. Alloy spawns Beyla as a child process and transfers the required capabilities through the kernel’s inheritable and ambient capability sets. You don’t need `SETPCAP`.

The required capabilities are: `BPF`, `NET_ADMIN`, `NET_RAW`, `PERFMON`, `DAC_READ_SEARCH`, `SYS_PTRACE`, `CHECKPOINT_RESTORE`, `SYS_RESOURCE` on kernels earlier than 5.11, and `SYS_ADMIN` for library-level instrumentation only. The exact set depends on your use case. Refer to [Beyla capabilities](/docs/beyla/latest/security/#list-of-capabilities-required-by-beyla) for more information.

In Kubernetes, set `hostPID: true` in the Pod spec and configure an [Unconfined AppArmor profile](https://kubernetes.io/docs/tutorials/security/apparmor/#securing-a-pod).

### Standalone: root

Run Alloy as root. On a standard Linux system, root processes inherit all capabilities from the bounding set, so you don’t need extra configuration. If systemd or another tool restricts the bounding set, grant the required capabilities explicitly:

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
setcap 'cap_bpf,cap_net_admin,cap_net_raw,cap_perfmon,cap_dac_read_search,cap_sys_ptrace,cap_checkpoint_restore,cap_sys_resource,cap_sys_admin+ep' /path/to/alloy
```

### Standalone: non-root

Set file capabilities on the Alloy binary with the `+ip` flag. This seeds the permitted set but doesn’t grant effective capabilities to Alloy, so Alloy holds them only to pass to Beyla:

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
setcap 'cap_bpf,cap_net_admin,cap_net_raw,cap_perfmon,cap_dac_read_search,cap_sys_ptrace,cap_checkpoint_restore,cap_sys_resource,cap_sys_admin+ip' /path/to/alloy
```

> Note
> 
> File capabilities aren’t scoped to a container boundary and travel with the binary. Treat this as a deliberate security decision.

### Kubernetes: privileged

Set `privileged: true` in the container’s `securityContext`. This grants all capabilities and disables `seccomp` and AppArmor profiles. This approach is **not recommended** for production environments.

### Kubernetes: unprivileged, root user

This is the recommended approach for Kubernetes. Run the container as root with `privileged: false` and grant only the required capabilities:

YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```yaml
spec:
  hostPID: true
  containers:
    - name: alloy
      securityContext:
        privileged: false
        allowPrivilegeEscalation: true  # optional: true is the default for root containers
        capabilities:
          add:
            - BPF
            - NET_ADMIN
            - NET_RAW
            - PERFMON
            - DAC_READ_SEARCH
            - SYS_PTRACE
            - CHECKPOINT_RESTORE
            - SYS_RESOURCE  # kernels < 5.11
            - SYS_ADMIN  # only for library-level instrumentation
```

Unlike `privileged: true`, this keeps `seccomp` and AppArmor profiles active.

### Kubernetes: unprivileged, non-root user

For the most restrictive posture, run as a non-root UID. Add `setcap +ip` to the binary when you build a custom image:

dockerfile ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```dockerfile
RUN setcap 'cap_bpf,cap_net_admin,cap_net_raw,cap_perfmon,cap_dac_read_search,cap_sys_ptrace,cap_checkpoint_restore,cap_sys_resource,cap_sys_admin+ip' /bin/alloy
```

Then configure the Pod security context:

YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```yaml
spec:
  hostPID: true
  containers:
    - name: alloy
      securityContext:
        privileged: false
        runAsUser: 473
        runAsNonRoot: true
        allowPrivilegeEscalation: true  # required: no_new_privs blocks PR_CAP_AMBIENT_RAISE
        capabilities:
          add:
            - BPF
            - NET_ADMIN
            - NET_RAW
            - PERFMON
            - DAC_READ_SEARCH
            - SYS_PTRACE
            - CHECKPOINT_RESTORE
            - SYS_RESOURCE  # kernels < 5.11
            - SYS_ADMIN  # only for library-level instrumentation
```

## Usage

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
beyla.ebpf "<LABEL>" {

}
```

## Arguments

You can use the following arguments with `beyla.ebpf`:

Expand table

| Name               | Type     | Description                                                    | Default      | Required |
|--------------------|----------|----------------------------------------------------------------|--------------|----------|
| `debug`            | `bool`   | Enable debug mode for Beyla.                                   | `false`      | no       |
| `enforce_sys_caps` | `bool`   | Enforce system capabilities required for eBPF instrumentation. | `false`      | no       |
| `trace_printer`    | `string` | Format for printing trace information.                         | `"disabled"` | no       |

`debug` enables debug mode for Beyla. This mode logs BPF logs, network logs, trace representation logs, and other debug information.

When `enforce_sys_caps` is set to true and the required system capabilities aren’t present, Beyla aborts its startup and logs a list of the missing capabilities.

`trace_printer` is used to print the trace information in a specific format. The following formats are supported:

- `disabled`: Disables trace printing.
- `counter`: Prints the trace information in a counter format.
- `text`: Prints the trace information in a text format.
- `json`: Prints the trace information in a JSON format.
- `json_indent`: Prints the trace information in a JSON format with indentation.

## Blocks

You can use the following blocks with `beyla.ebpf`:

No valid configuration blocks found.

### `output`

Required

The `output` block configures a set of components to forward the resulting telemetry data to.

The following arguments are supported:

Expand table

| Name     | Type                     | Description                          | Default | Required |
|----------|--------------------------|--------------------------------------|---------|----------|
| `traces` | `list(otelcol.Consumer)` | List of consumers to send traces to. | `[]`    | no       |

You must specify the `output` block, but all its arguments are optional. By default, telemetry data is dropped. Configure the `traces` argument to send traces data to other components.

### `attributes`

The `attributes` block configures how some attributes for metrics and traces are decorated.

It contains the following blocks:

#### `kubernetes` attributes

This `kubernetes` block configures the decorating of the metrics and traces with Kubernetes metadata from the instrumented Pods.

Expand table

| Name                         | Type           | Description                                                                      | Default      | Required |
|------------------------------|----------------|----------------------------------------------------------------------------------|--------------|----------|
| `cluster_name`               | `string`       | The name of the Kubernetes cluster.                                              | `""`         | no       |
| `disable_informers`          | `list(string)` | List of Kubernetes informers to disable.                                         | `[]`         | no       |
| `enable`                     | `string`       | Enable the Kubernetes metadata decoration.                                       | `autodetect` | no       |
| `informers_resync_period`    | `duration`     | Period for Kubernetes informers resynchronization.                               | `"30m"`      | no       |
| `informers_sync_timeout`     | `duration`     | Timeout for Kubernetes informers synchronization.                                | `"30s"`      | no       |
| `meta_cache_address`         | `string`       | Address of the Kubernetes metadata cache service.                                | `""`         | no       |
| `meta_restrict_local_node`   | `bool`         | Restrict Kubernetes metadata collection to local node.                           | `false`      | no       |
| `reconnect_initial_interval` | `duration`     | Initial interval for reconnecting to the Kubernetes API after a connection loss. | `"0s"`       | no       |

If `cluster_name` isn’t set, Beyla tries to detect the cluster name from the Kubernetes API.

If `enable` is set to `true`, Beyla decorates the metrics and traces with Kubernetes metadata. The following labels are added:

- `k8s.daemonset.name`
- `k8s.deployment.name`
- `k8s.namespace.name`
- `k8s.node.name`
- `k8s.pod.name`
- `k8s.pod.start_time`
- `k8s.pod.uid`
- `k8s.replicaset.name`
- `k8s.statefulset.name`

If `enable` is set to `false`, the Kubernetes metadata decorator is disabled.

If `enable` is set to `autodetect`, Beyla tries to detect if it’s running inside Kubernetes, and enables the metadata decoration if that’s the case.

In `disable_informers`, you can specify the Kubernetes informers to disable. The accepted value is a list that might contain `node` and `service`.

#### `instance_id`

The `instance_id` block configures instance ID settings.

Expand table

| Name                | Type     | Description                                             | Default | Required |
|---------------------|----------|---------------------------------------------------------|---------|----------|
| `dns`               | `bool`   | Enable DNS resolution for hostname.                     | `true`  | no       |
| `override_hostname` | `string` | Override the hostname used for instance identification. | `""`    | no       |

#### `select`

The `select` block configures which attributes to include or exclude for specific metric/trace sections.

Expand table

| Name      | Type           | Description                                            | Default | Required |
|-----------|----------------|--------------------------------------------------------|---------|----------|
| `attr`    | `string`       | The attribute name to select.                          | `[]`    | yes      |
| `exclude` | `list(string)` | List of attributes to exclude.                         | `[]`    | no       |
| `include` | `list(string)` | List of attributes to include. Use `*` to include all. | `[]`    | no       |

`include` is a list of attributes that need to be reported. Each attribute can be an attribute name or a wildcard, for example, `k8s.dst.*` to include all the attributes starting with `k8s.dst`.

`exclude` is a list to of attribute names/wildcards containing the attributes to remove from the `include` list, or from the default attribute set.

The following example shows how you can include and exclude specific attributes:

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
beyla.ebpf "default" {
attributes {
    select {
        attr = "sql_client_duration"
        include = ["*"]
        exclude = ["db_statement"]
    }
  }
}
```

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

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
beyla.ebpf "default" {
  attributes {
    select {
        attr = "http_*"
        include = ["*"]
        exclude = ["http_path", "http_route"]
    }
    select {
        attr = "http_client_*"
        // override http_* exclusion
        include = ["http_path"]
    }
  }
}
```

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

### `discovery`

The `discovery` block configures the discovery for processes to instrument matching given criteria.

Expand table

| Name                                 | Type   | Description                                                        | Default | Required |
|--------------------------------------|--------|--------------------------------------------------------------------|---------|----------|
| `exclude_otel_instrumented_services` | `bool` | Exclude services that are already instrumented with OpenTelemetry. | `true`  | no       |
| `skip_go_specific_tracers`           | `bool` | Skip Go-specific tracers during discovery.                         | `false` | no       |

It contains the following blocks:

#### `instrument`

The `instrument` block configures the services to discover and instrument using [glob patterns](https://github.com/gobwas/glob).

Expand table

| Name              | Type           | Description                                                                     | Default | Required |
|-------------------|----------------|---------------------------------------------------------------------------------|---------|----------|
| `name`            | `string`       | The name of the service to match.                                               | `""`    | no       |
| `namespace`       | `string`       | The namespace of the service to match.                                          | `""`    | no       |
| `open_ports`      | `string`       | The port of the running service for Beyla automatically instrumented with eBPF. | `""`    | no       |
| `exe_path`        | `string`       | The path of the running service for Beyla automatically instrumented with eBPF. | `""`    | no       |
| `cmd_args`        | `string`       | Glob pattern to match the process command-line arguments.                       | `""`    | no       |
| `containers_only` | `bool`         | Restrict the discovery to processes which are running inside a container.       | `false` | no       |
| `exports`         | `list(string)` | Export modes for the service. Valid values: `"metrics"`, `"traces"`.            | `[]`    | no       |

`exe_path` accepts a glob pattern to be matched against the full executable command line, including the directory where the executable resides on the file system. Common glob patterns include `*` (matches any sequence of characters) and `?` (matches any single character).

`cmd_args` accepts a glob pattern to be matched against the process command-line arguments, excluding the executable name.

`name` defines a name for the matching instrumented service. It’s used to populate the `service.name` OTel property or the `service_name` Prometheus property in the exported metrics/traces.

`open_ports` accepts a comma-separated list of ports (for example, `80,443`), and port ranges (for example, `8000-8999`). If the executable matches only one of the ports in the list, it’s considered to match the selection criteria.

`exports` specifies what types of telemetry data to export for the matching service. You can specify `"metrics"`, `"traces"`, or both. If empty, the service will export both metrics and traces by default.

#### `exclude_instrument`

The `exclude_instrument` block configures services to exclude from instrumentation using glob patterns. Services matching these criteria won’t be instrumented even if they match the `instrument` selection.

The `exclude_instrument` block uses the same configuration options as the `instrument` block.

#### `default_exclude_instrument`

The `default_exclude_instrument` block disables instrumentation of Grafana Alloy and related components by default. The default value for `exe_path` uses a glob pattern that matches `beyla`, `alloy`, and `otelcol*` executables. Set to empty to allow Alloy to instrument itself as well as these other components.

#### `survey`

The `survey` block configures services for discovery without instrumentation using glob patterns. Instead of instrumenting matching services, the component will only emit a `survey_info` metric for each discovered service. This can be helpful for informing external applications of the services available for instrumentation.

The `survey` block uses the same configuration options as the `instrument` block.

#### `kubernetes` services

This `kubernetes` block filters the services to instrument based on their Kubernetes metadata. If you specify other selectors in the same services entry, the instrumented processes need to match all the selector properties.

When used with `instrument`, `exclude_instrument`, `default_exclude_instrument`, or `survey` blocks, the patterns use glob syntax.

Expand table

| Name               | Type          | Description                                                                                             | Default | Required |
|--------------------|---------------|---------------------------------------------------------------------------------------------------------|---------|----------|
| `daemonset_name`   | `string`      | Pattern to match Kubernetes DaemonSets.                                                                 | `""`    | no       |
| `deployment_name`  | `string`      | Pattern to match Kubernetes Deployments.                                                                | `""`    | no       |
| `namespace`        | `string`      | Pattern to match Kubernetes Namespaces.                                                                 | `""`    | no       |
| `owner_name`       | `string`      | Pattern to match Kubernetes owners of running Pods.                                                     | `""`    | no       |
| `pod_labels`       | `map(string)` | Key-value pairs of labels with keys matching Kubernetes Pods with the provided value as pattern.        | `{}`    | no       |
| `pod_annotations`  | `map(string)` | Key-value pairs of labels with keys matching Kubernetes annotations with the provided value as pattern. | `{}`    | no       |
| `pod_name`         | `string`      | Pattern to match Kubernetes Pods.                                                                       | `""`    | no       |
| `replicaset_name`  | `string`      | Pattern to match Kubernetes ReplicaSets.                                                                | `""`    | no       |
| `statefulset_name` | `string`      | Pattern to match Kubernetes StatefulSets.                                                               | `""`    | no       |

Example:

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
beyla.ebpf "default" {
  discovery {
    // Instrument all services with 8080 open port
    instrument {
      open_ports = "8080"
    }
    // Instrument all services from the default namespace
    instrument {
      kubernetes {
        namespace = "default"
      }
    }
    // Exclude all services from the kube-system namespace
    exclude_instrument {
      kubernetes {
        namespace = "kube-system"
      }
    }
  }
}
```

### `traces`

The `traces` block configures trace collection and sampling options for the beyla.ebpf component.

> Note
> 
> To export traces, you must also configure the [`output`](#output) block with a `traces` destination. Without an output configuration, traces are collected but not exported.

Expand table

| Name               | Type           | Description                                              | Default | Required |
|--------------------|----------------|----------------------------------------------------------|---------|----------|
| `instrumentations` | `list(string)` | List of instrumentations to enable for trace collection. | `["*"]` | no       |

The supported values for `instrumentations` are:

- `*`: Enables all `instrumentations`. If `*` is present in the list, the other values are ignored.
- `genai`: Enables the collection of GenAI (LLM) traces.
- `grpc`: Enables the collection of gRPC traces.
- `gpu`: Enables the collection of GPU performance traces.
- `http`: Enables the collection of HTTP/HTTPS/HTTP2 traces.
- `kafka`: Enables the collection of Kafka client/server traces.
- `memcached`: Enables the collection of Memcached client/server traces.
- `mongo`: Enables the collection of MongoDB database traces.
- `redis`: Enables the collection of Redis client/server database traces.
- `sql`: Enables the collection of SQL database client call traces.

Example:

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
beyla.ebpf "default" {
  traces {
    instrumentations = ["http", "grpc", "sql"]
    sampler {
      name = "traceidratio"
      arg = "0.1"  // Global 10% sampling rate for all traces
    }
  }
  output {
    traces = [otelcol.processor.batch.default.input]
  }
}
```

For per-service sampling configuration, use the `sampler` block within the `discovery` &gt; `instrument` section instead.

### `sampler`

The `sampler` block configures trace sampling settings. This block can be used in two contexts:

1. **Per-service sampling** - as a sub-block of `discovery` &gt; `instrument` to configure sampling for individual discovered services
2. **Global sampling** - as a sub-block of `traces` to configure sampling for all traces collected by the component

The following arguments are supported:

Expand table

| Name   | Type     | Description                               | Default | Required |
|--------|----------|-------------------------------------------|---------|----------|
| `arg`  | `string` | The argument for the sampling strategy.   | `""`    | no       |
| `name` | `string` | The name of the sampling strategy to use. | `""`    | no       |

The supported values for `name` are:

- `traceidratio`: Samples traces based on a ratio of trace IDs. The `arg` must be a decimal value between 0 and 1. For example, `"0.1"` for 10% sampling.
- `always_on`: Always samples traces. No `arg` required.
- `always_off`: Never samples traces. No `arg` required.
- `parentbased_always_on`: Uses parent-based sampling that always samples when there’s no parent span. This is the default behavior.
- `parentbased_always_off`: Uses parent-based sampling that never samples when there’s no parent span.
- `parentbased_traceidratio`: Uses parent-based sampling with trace ID ratio-based sampling for root spans. The `arg` must be a decimal value between 0 and 1.

#### Examples

Per-service sampling (configured within `discovery` &gt; `instrument`):

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
beyla.ebpf "default" {
  discovery {
    instrument {
      open_ports = "8080"
      sampler {
        name = "traceidratio"
        arg = "0.1"  // 10% sampling rate for this specific service
      }
    }
  }
}
```

Global sampling (configured within `traces`):

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
beyla.ebpf "default" {
  traces {
    instrumentations = ["http", "grpc", "sql"]
    sampler {
      name = "traceidratio"
      arg = "0.1"  // Global 10% sampling rate for all traces
    }
  }
  output {
    traces = [otelcol.processor.batch.default.input]
  }
}
```

### `ebpf`

The `ebpf` block configures eBPF-specific settings.

Expand table

| Name                    | Type       | Description                                                                   | Default      | Required |
|-------------------------|------------|-------------------------------------------------------------------------------|--------------|----------|
| `wakeup_len`            | `int`      | Number of messages to accumulate before wakeup request.                       | `""`         | no       |
| `track_request_headers` | `bool`     | Enable tracking of request headers for Traceparent fields.                    | `false`      | no       |
| `http_request_timeout`  | `duration` | Timeout for HTTP requests.                                                    | `"30s"`      | no       |
| `context_propagation`   | `string`   | Enables injecting of the Traceparent header value for outgoing HTTP requests. | `"disabled"` | no       |
| `high_request_volume`   | `bool`     | Optimize for immediate request information when response is seen.             | `false`      | no       |
| `heuristic_sql_detect`  | `bool`     | Enable heuristic-based detection of SQL requests.                             | `false`      | no       |

#### `context_propagation`

`context_propagation` allows Beyla to propagate any incoming context to downstream services. This context propagation support works for any programming language.

For TLS encrypted HTTP requests (HTTPS), the Traceparent header value is encoded at TCP packet level, and requires that Beyla is present on both sides of the communication.

The TCP packet level encoding uses Linux Traffic Control (TC). eBPF programs that also use TC need to chain correctly with Beyla. For more information about chaining programs, refer to the [Cilium compatibility](/docs/beyla/latest/cilium-compatibility/) documentation.

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

`context_propagation` can be set to either one of the following values:

- `all`: Enable both HTTP headers and TCP context propagation.
- `headers`: Enable context propagation via the HTTP headers only.
- `tcp`: Enable context propagation via TCP only.
- `disabled`: Disable trace context propagation.

The deprecated value `ip` is still accepted by upstream Beyla for compatibility, but it has no effect.

#### `payload_extraction`

The `payload_extraction` block configures protocol-aware HTTP payload parsing.

##### `http`

###### `openai`

Expand table

| Name      | Type   | Description                               | Default | Required |
|-----------|--------|-------------------------------------------|---------|----------|
| `enabled` | `bool` | Enable OpenAI payload extraction parsing. | `false` | no       |

When enabled, Beyla parses supported OpenAI HTTP payloads and can enrich traces with GenAI-related attributes.

###### `anthropic`

Expand table

| Name      | Type   | Description                                  | Default | Required |
|-----------|--------|----------------------------------------------|---------|----------|
| `enabled` | `bool` | Enable Anthropic payload extraction parsing. | `false` | no       |

When enabled, Beyla parses supported Anthropic HTTP payloads and can enrich traces with GenAI-related attributes.

###### `gemini`

Expand table

| Name      | Type   | Description                               | Default | Required |
|-----------|--------|-------------------------------------------|---------|----------|
| `enabled` | `bool` | Enable Gemini payload extraction parsing. | `false` | no       |

When enabled, Beyla parses supported Gemini HTTP payloads and can enrich traces with GenAI-related attributes.

###### `bedrock`

Expand table

| Name      | Type   | Description                                    | Default | Required |
|-----------|--------|------------------------------------------------|---------|----------|
| `enabled` | `bool` | Enable AWS Bedrock payload extraction parsing. | `false` | no       |

When enabled, Beyla parses supported AWS Bedrock HTTP payloads and can enrich traces with GenAI-related attributes.

###### `embedding`

Expand table

| Name      | Type   | Description                                  | Default | Required |
|-----------|--------|----------------------------------------------|---------|----------|
| `enabled` | `bool` | Enable embedding payload extraction parsing. | `false` | no       |

When enabled, Beyla parses supported embedding provider HTTP payloads and can enrich traces with GenAI-related attributes.

###### `mcp`

Expand table

| Name      | Type   | Description                                               | Default | Required |
|-----------|--------|-----------------------------------------------------------|---------|----------|
| `enabled` | `bool` | Enable Model Context Protocol payload extraction parsing. | `false` | no       |

When enabled, Beyla parses supported Model Context Protocol HTTP payloads and can enrich traces with GenAI-related attributes.

###### `qwen`

Expand table

| Name      | Type   | Description                               | Default | Required |
|-----------|--------|-------------------------------------------|---------|----------|
| `enabled` | `bool` | Enable `Qwen` payload extraction parsing. | `false` | no       |

When enabled, Beyla parses supported `Qwen` HTTP payloads and can enrich traces with GenAI-related attributes.

###### `rerank`

Expand table

| Name      | Type   | Description                                 | Default | Required |
|-----------|--------|---------------------------------------------|---------|----------|
| `enabled` | `bool` | Enable `rerank` payload extraction parsing. | `false` | no       |

When enabled, Beyla parses supported `rerank` HTTP payloads and can enrich traces with GenAI-related attributes.

###### `retrieval`

Expand table

| Name      | Type   | Description                                  | Default | Required |
|-----------|--------|----------------------------------------------|---------|----------|
| `enabled` | `bool` | Enable retrieval payload extraction parsing. | `false` | no       |

When enabled, Beyla parses supported retrieval HTTP payloads and can enrich traces with GenAI-related attributes.

#### `maps_config`

The `maps_config` block configures eBPF map sizing.

Expand table

| Name                  | Type  | Description                                                                | Default | Required |
|-----------------------|-------|----------------------------------------------------------------------------|---------|----------|
| `global_scale_factor` | `int` | Scales all eBPF map sizes in powers of two. Range: -3 to 3; 0 = no change. | `0`     | no       |

### `filters`

The `filters` block allows you to filter both application and network metrics by attribute values.

For a list of metrics under the application and network family, as well as their attributes, refer to the [Beyla exported metrics](/docs/beyla/latest/metrics/).

It contains the following blocks:

#### `application`

The `application` block configures filtering of application attributes.

Expand table

| Name        | Type     | Description                         | Required |
|-------------|----------|-------------------------------------|----------|
| `attr`      | `string` | The name of the attribute to match. | yes      |
| `match`     | `string` | String to match attribute values.   | no       |
| `not_match` | `string` | String to exclude matching values.  | no       |

Both properties accept a [glob-like](https://github.com/gobwas/glob) string (it can be a full value or include wildcards).

#### `network` filters

The `network` block configures filtering of network attributes.

Expand table

| Name        | Type     | Description                         | Required |
|-------------|----------|-------------------------------------|----------|
| `attr`      | `string` | The name of the attribute to match. | yes      |
| `match`     | `string` | String to match attribute values.   | no       |
| `not_match` | `string` | String to exclude matching values.  | no       |

Both properties accept a [glob-like](https://github.com/gobwas/glob) string (it can be a full value or include wildcards).

Example:

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
beyla.ebpf "default" {
  filters {
    application {
      attr = "url.path"
      match = "/user/*"
    }
    network {
      attr = "k8s.src.owner.name"
      match = "*"
    }
  }
}
```

### `metrics`

The `metrics` block configures which metrics Beyla collects.

Expand table

| Name                                  | Type           | Description                                                | Default                                                                                   | Required |
|---------------------------------------|----------------|------------------------------------------------------------|-------------------------------------------------------------------------------------------|----------|
| `allow_service_graph_self_references` | `bool`         | Allow service graph metrics to reference the same service. | `false`                                                                                   | no       |
| `exemplar_filter`                     | `string`       | Controls when exemplars are attached to metrics.           | `"always_off"`                                                                            | no       |
| `extra_resource_labels`               | `list(string)` | List of OTEL resource labels to include on `target_info`.  | `[]`                                                                                      | no       |
| `extra_span_resource_labels`          | `list(string)` | List of OTEL resource labels to include on span metrics.   | `["k8s.cluster.name", "k8s.namespace.name", "service.version", "deployment.environment"]` | no       |
| `features`                            | `list(string)` | List of features to enable for the metrics.                | `["application"]`                                                                         | no       |
| `instrumentations`                    | `list(string)` | List of instrumentations to enable for the metrics.        | `["*"]`                                                                                   | no       |
| `native_histograms`                   | `bool`         | Use Prometheus native histograms.                          | `false`                                                                                   | no       |

`exemplar_filter` controls when exemplars are attached to Prometheus metrics, mirroring the `OTEL_METRICS_EXEMPLAR_FILTER` specification. The accepted values are `always_on`, `always_off`, and `trace_based`.

`features` is a list of features to enable for the metrics. The following features are available:

- `*` or `all` enables all features.
- `application` exports application-level metrics.
- `application_process` exports metrics about the processes that run the instrumented application.
- `application_service_graph` exports application-level service graph metrics.
- `application_span` exports application-level metrics in traces span metrics format.
- `application_span_otel` exports OpenTelemetry-compatible span metrics.
- `application_span_sizes` exports span size metrics for trace analysis.
- `application_host` exports application-level host metrics for host-based pricing.
- `network` exports network-level metrics.
- `network_inter_zone` exports network-level inter-zone metrics.
- `stats` exports kernel-level connection statistics per service.

`instrumentations` is a list of instrumentations to enable for the metrics. The following instrumentations are available:

- `*` enables all `instrumentations`. If `*` is present in the list, the other values are ignored.
- `genai` enables the collection of GenAI (LLM) application metrics.
- `grpc` enables the collection of gRPC application metrics.
- `gpu` enables the collection of GPU performance metrics.
- `http` enables the collection of HTTP/HTTPS/HTTP2 application metrics.
- `kafka` enables the collection of Kafka client/server message queue metrics.
- `memcached` enables the collection of Memcached client/server metrics.
- `mongo` enables the collection of MongoDB database metrics.
- `redis` enables the collection of Redis client/server database metrics.
- `sql` enables the collection of SQL database client call metrics.

`extra_resource_labels` is a list of OTEL resource labels, supplied through the `OTEL_RESOURCE_ATTRIBUTES` environment variable on the service, that you want to include on the `target_info` metric.

`extra_span_resource_labels` is a list of OTEL resource labels, supplied through the `OTEL_RESOURCE_ATTRIBUTES` environment variable on the service, that you want to include on the span metrics. The default list includes:

- `k8s.cluster.name`
- `k8s.namespace.name`
- `service.version`
- `deployment.environment`

The default list of `extra_span_resource_labels` is set to match the defaults chosen by Application Observability plugin in Grafana Cloud.

#### `network` metrics

The `network` block configures network metrics options for Beyla. You must append `network` to the `features` list in the `metrics` block to enable network metrics.

Expand table

| Name                   | Type           | Description                                                           | Default           | Required |
|------------------------|----------------|-----------------------------------------------------------------------|-------------------|----------|
| `agent_ip_iface`       | `string`       | Network interface to get agent IP from.                               | `"external"`      | no       |
| `agent_ip_type`        | `string`       | Type of IP address to use.                                            | `"any"`           | no       |
| `agent_ip`             | `string`       | Allows overriding the reported `beyla.ip` attribute on each metric.   | `""`              | no       |
| `cache_active_timeout` | `duration`     | Timeout for active flow cache entries.                                | `"5s"`            | no       |
| `cache_max_flows`      | `int`          | Maximum number of flows to cache.                                     | `5000`            | no       |
| `cidrs`                | `list(string)` | List of CIDR ranges to monitor.                                       | `[]`              | no       |
| `direction`            | `string`       | Direction of traffic to monitor.                                      | `"both"`          | no       |
| `exclude_interfaces`   | `list(string)` | List of network interfaces to exclude from monitoring.                | `["lo"]`          | no       |
| `exclude_protocols`    | `list(string)` | List of protocols to exclude from monitoring.                         | `[]`              | no       |
| `interfaces`           | `list(string)` | List of network interfaces to monitor.                                | `[]`              | no       |
| `protocols`            | `list(string)` | List of protocols to monitor.                                         | `[]`              | no       |
| `sampling`             | `int`          | Sampling rate for network metrics.                                    | `0` (disabled)    | no       |
| `source`               | `string`       | Linux Kernel feature used to source the network events Beyla reports. | `"socket_filter"` | no       |

You can set `source` to `socket_filter` or `tc`.

- `socket_filter` is used as an event source. Beyla installs an eBPF Linux socket filter to capture the network events.
- `tc` is used as a kernel module. Beyla uses the Linux Traffic Control ingress and egress filters to capture the network events, in a direct action mode.

You can set `agent_ip_iface` to `external` (default), `local`, or `name:<interface name>`, for example `name:eth0`.

You can set `agent_ip_type` to `ipv4`, `ipv6`, or `any` (default).

`protocols` and `exclude_protocols` are defined in the Linux enumeration of [Standard well-defined IP protocols](https://elixir.bootlin.com/linux/v6.8.7/source/include/uapi/linux/in.h#L28), and can be:

- `AH`
- `BEETPH`
- `COMP`
- `DCCP`
- `EGP`
- `ENCAP`
- `ESP`
- `ETHERNET`
- `GRE`
- `ICMP`
- `IDP`
- `IGMP`
- `IP`
- `IPIP`
- `IPV6`
- `L2TP`
- `MPLS`
- `MTP`
- `PIM`
- `PUP`
- `RAW`
- `RSVP`
- `SCTP`
- `TCP`
- `TP`
- `UDP`
- `UDPLITE`

You can set `direction` to `ingress`, `egress`, or `both` (default).

`sampling` defines the rate at which packets should be sampled and sent to the target collector. For example, if you set it to 100, one out of 100 packets, on average, are sent to the target collector.

### `routes`

The `routes` block configures the routes to match HTTP paths into user-provided HTTP routes.

Expand table

| Name                           | Type           | Description                                                                              | Default       | Required |
|--------------------------------|----------------|------------------------------------------------------------------------------------------|---------------|----------|
| `ignore_mode`                  | `string`       | The mode to use when ignoring patterns.                                                  | `""`          | no       |
| `ignored_patterns`             | `list(string)` | List of provided URL path patterns to ignore from `http.route` trace/metric property.    | `[]`          | no       |
| `patterns`                     | `list(string)` | List of provided URL path patterns to set the `http.route` trace/metric property.        | `[]`          | no       |
| `unmatched`                    | `string`       | Specifies what to do when a trace HTTP path doesn’t match any of the `patterns` entries. | `"heuristic"` | no       |
| `wildcard_char`                | `string`       | Character to use as wildcard in patterns.                                                | `"*"`         | no       |
| `max_path_segment_cardinality` | `number`       | Maximum allowed path segment cardinality (per service) for the heuristic matcher.        | `10`          | no       |

`ignore_mode` properties are:

- `all` discards metrics and traces matching the `ignored_patterns`.
- `metrics` discards only the metrics that match the `ignored_patterns`. No trace events are ignored.
- `traces` discards only the traces that match the `ignored_patterns`. No metric events are ignored.

`patterns` and `ignored_patterns` are a list of patterns which a URL path with specific tags which allow for grouping path segments (or ignored them). The matcher tags can be in the `:name` or `{name}` format.

`unmatched` properties are:

- `heuristic` automatically derives the `http.route` field property from the path value based on the following rules:
  
  - Any path components that have numbers or characters outside of the ASCII alphabet (or `-` and \_), are replaced by an asterisk `*`.
  - Any alphabetical components that don’t look like words are replaced by an asterisk `*`.
- `path` copies the `http.route` field property to the path value.
  
  > Caution
  > 
  > This property could lead to a cardinality explosion on the ingester side.
- `unset` leaves the `http.route` property as unset.
- `wildcard` sets the `http.route` field property to a generic asterisk-based `/**` value.

### `injector`

The `injector` block configures the Beyla SDK injection feature, which automatically instruments services by injecting OpenTelemetry SDKs without requiring eBPF.

Expand table

| Name                     | Type           | Description                                                                                      | Default | Required |
|--------------------------|----------------|--------------------------------------------------------------------------------------------------|---------|----------|
| `disable_auto_restart`   | `bool`         | Disable automatic restart of instrumented services after SDK injection.                          | `false` | no       |
| `enabled_sdks`           | `list(string)` | List of enabled SDK auto-instrumentations. Use it to limit which language instrumentations run.  | `[]`    | no       |
| `exporter_otlp_endpoint` | `string`       | Override for the OTLP endpoint that injected SDKs use to export telemetry.                       | `""`    | no       |
| `exporter_otlp_protocol` | `string`       | OTLP protocol that injected SDKs use to export telemetry, for example `http/protobuf` or `grpc`. | `""`    | no       |
| `image_version`          | `string`       | OCI image version to inject.                                                                     | `""`    | no       |
| `trace_propagators`      | `list(string)` | Context propagation formats for injected SDKs, for example `["tracecontext", "baggage"]`.        | `[]`    | no       |

`enabled_sdks` accepts the following values: `java`, `dotnet`, `nodejs`, `python`.

`exporter_otlp_endpoint` overrides the OTLP endpoint that injected SDKs use to export telemetry, for cases where Beyla isn’t configured to export traces. When set, it overrides the global OTLP endpoint for SDK-injected services.

`trace_propagators` common values are `tracecontext`, `baggage`, `b3`, `b3multi`, `jaeger`, and `xray`.

It contains the following blocks:

#### `webhook`

The `webhook` block delegates SDK injection to an external mutating webhook controller or operator instead of Beyla handling it directly.

Expand table

| Name                       | Type     | Description                                                             | Default | Required |
|----------------------------|----------|-------------------------------------------------------------------------|---------|----------|
| `external_deployment_name` | `string` | Name of the external controller or operator that handles SDK injection. | `""`    | no       |

#### `otel_exported_signals`

The `otel_exported_signals` block configures which telemetry signals the injected SDK exports through OTLP. Injected SDKs can only export through OTLP, not Prometheus scraping.

Expand table

| Name      | Type   | Description                              | Default | Required |
|-----------|--------|------------------------------------------|---------|----------|
| `logs`    | `bool` | Enable log export from injected SDKs.    | `false` | no       |
| `metrics` | `bool` | Enable metric export from injected SDKs. | `true`  | no       |
| `traces`  | `bool` | Enable trace export from injected SDKs.  | `true`  | no       |

#### `resources`

The `resources` block configures resource attributes attached to telemetry emitted by injected SDKs.

Expand table

| Name                                     | Type          | Description                                                                                                  | Default | Required |
|------------------------------------------|---------------|--------------------------------------------------------------------------------------------------------------|---------|----------|
| `add_k8s_ip_attribute`                   | `bool`        | Set the `k8s.pod.ip` resource attribute from the Kubernetes downward API (`status.podIP`).                   | `false` | no       |
| `add_k8s_uid_attributes`                 | `bool`        | Add Kubernetes UID attributes, for example `k8s.deployment.uid`, to the resource.                            | `false` | no       |
| `attributes`                             | `map(string)` | Map of additional resource attributes to add, for example `{environment = "production"}`.                    | `{}`    | no       |
| `use_k8s_labels_for_resource_attributes` | `bool`        | Use common Kubernetes labels as resource attributes, for example `app.kubernetes.io/name` as `service.name`. | `false` | no       |

### `stats`

The `stats` block configures stats observability options for Beyla. You must append `stats` to the `features` list in the `metrics` block to enable stats collection.

Expand table

| Name             | Type           | Description                                                                | Default      | Required |
|------------------|----------------|----------------------------------------------------------------------------|--------------|----------|
| `agent_ip`       | `string`       | Overrides the reported agent IP address in stats records.                  | `""`         | no       |
| `agent_ip_iface` | `string`       | Network interface to obtain the agent IP from.                             | `"external"` | no       |
| `agent_ip_type`  | `string`       | Type of IP address to use.                                                 | `"any"`      | no       |
| `cidrs`          | `list(string)` | List of CIDR ranges used to decorate `src.cidr` and `dst.cidr` attributes. | `[]`         | no       |
| `print_stats`    | `bool`         | Print stats records to stdout for debugging.                               | `false`      | no       |

You can set `agent_ip_iface` to `external` (default), `local`, or `name:<interface name>`, for example `name:eth0`.

You can set `agent_ip_type` to `ipv4`, `ipv6`, or `any` (default).

### `jvm_runtime_metrics`

The `jvm_runtime_metrics` block configures collection of JVM runtime metrics, such as heap usage, garbage collection, and thread counts, from instrumented Java processes.

Expand table

| Name                | Type       | Description                               | Default | Required |
|---------------------|------------|-------------------------------------------|---------|----------|
| `enabled`           | `bool`     | Enable collection of JVM runtime metrics. | `false` | no       |
| `sampling_interval` | `duration` | How often to sample JVM runtime metrics.  | `""`    | no       |

When `sampling_interval` is unset, Beyla uses its own default interval.

## Exported fields

The following fields are exported and can be referenced by other components.

Expand table

| Name      | Type                | Description                                                                         |
|-----------|---------------------|-------------------------------------------------------------------------------------|
| `targets` | `list(map(string))` | The targets that can be used to collect metrics of instrumented services with eBPF. |

For example, the `targets` can either be passed to a `discovery.relabel` component to rewrite the targets’ label sets or to a `prometheus.scrape` component that collects the exposed metrics.

The exported targets use the configured [in-memory traffic](../../../../get-started/component_controller/#in-memory-traffic) address specified by the [run command](../../../cli/run/).

## Component health

`beyla.ebpf` is only reported as unhealthy if given an invalid configuration.

## Debug information

`beyla.ebpf` doesn’t expose any component-specific debug information.

## Observability considerations

`beyla.ebpf` runs Beyla as a separate child process. This isolates failures in Beyla from Alloy but changes how Alloy exposes resource usage and profile data.

### Resource metrics

Alloy exposes process-level metrics for the Beyla process under the same name as its own, with a `subprocess="beyla"` label:

promql ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```promql
alloy_resources_process_resident_memory_bytes                    # Alloy process only
alloy_resources_process_resident_memory_bytes{subprocess="beyla"} # Beyla subprocess only
```

If you use `alloy_resources_process_*` to approximate total container resource usage, the metrics include only the Alloy process. To get the combined figure for both processes, sum across the label:

promql ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```promql
sum without(subprocess) (alloy_resources_process_resident_memory_bytes)
```

For container-level limits and OOM monitoring, prefer `kubelet`/cAdvisor metrics such as `container_memory_working_set_bytes`, which already account for every process in the container.

### Profiling

The Alloy `/debug/pprof/*` endpoints reflect goroutines, allocations, and CPU from the Alloy process only. Beyla exposes profile data on its own HTTP port. You can reach it through the component’s reverse-proxy URL, for example:

![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```none
<alloy>/api/v0/component/beyla.ebpf.<LABEL>/debug/pprof/heap
```

When you enable profiling for Alloy, Beyla also exposes pprof endpoints. The toggle is the `--server.http.enable-pprof` flag, which defaults to `true`. If you set it to `false`, the proxied URL returns 404, which matches how the Alloy `/debug/pprof/*` endpoints behave. Beyla doesn’t have a separate switch.

Each `beyla.ebpf` component instance has its own pprof URL scoped by component ID. If you define multiple instances, such as `beyla.ebpf.foo` and `beyla.ebpf.bar`, each one is reachable at its own component path without extra configuration.

To capture Beyla profile data in continuous-profiling pipelines, scrape the component’s proxied pprof URL in addition to the Alloy pprof endpoints. A scrape job that targets only the Alloy pprof endpoints captures only the Alloy profile.

## Examples

The following examples show you how to collect metrics and traces from `beyla.ebpf`.

### Metrics

This example uses a [`prometheus.scrape` component](../../prometheus/prometheus.scrape/) to collect metrics from `beyla.ebpf` of the specified port:

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
beyla.ebpf "default" {
  discovery {
    instrument {
      open_ports = <OPEN_PORT>
    }
  }

  metrics {
    features = [
     "application", 
    ]
  }
}

prometheus.scrape "beyla" {
  targets = beyla.ebpf.default.targets
  honor_labels = true // required to keep job and instance labels
  forward_to = [prometheus.remote_write.demo.receiver]
}

prometheus.remote_write "demo" {
  endpoint {
    url = <PROMETHEUS_REMOTE_WRITE_URL>

    basic_auth {
      username = <USERNAME>
      password = <PASSWORD>
    }
  }
}
```

#### Kubernetes

This example gets metrics from `beyla.ebpf` for the specified namespace and Pods running in a Kubernetes cluster:

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
beyla.ebpf "default" {
  discovery {
    instrument {
     kubernetes {
      namespace = "<NAMESPACE>"
      pod_name = "<POD_NAME>"
     }
    }
  }
  metrics {
    features = [
     "application", 
    ]
  }
}

prometheus.scrape "beyla" {
  targets = beyla.ebpf.default.targets
  honor_labels = true // required to keep job and instance labels
  forward_to = [prometheus.remote_write.demo.receiver]
}

prometheus.remote_write "demo" {
  endpoint {
    url = <PROMETHEUS_REMOTE_WRITE_URL>

    basic_auth {
      username = <USERNAME>
      password = <PASSWORD>
    }
  }
}
```

Replace the following:

- *`<OPEN_PORT>`* : The port of the running service for Beyla automatically instrumented with eBPF.
- *`<NAMESPACE>`* : The namespaces of the applications running in a Kubernetes cluster.
- *`<POD_NAME>`* : The name of the Pods running in a Kubernetes cluster.
- *`<PROMETHEUS_REMOTE_WRITE_URL>`* : The URL of the Prometheus remote\_write-compatible server to send metrics to.
- *`<USERNAME>`* : The username to use for authentication to the `remote_write` API.
- *`<PASSWORD>`* : The password to use for authentication to the `remote_write` API.

### Traces

This example gets traces from `beyla.ebpf` and forwards them to `otlp`:

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
beyla.ebpf "default" {
  discovery {
    instrument {
      open_ports = <OPEN_PORT>
    }
  }
  output {
    traces = [otelcol.processor.batch.default.input]
  }
}

otelcol.processor.batch "default" {
  output {
    traces  = [otelcol.exporter.otlphttp.default.input]
  }
}

otelcol.exporter.otlphttp "default" {
  client {
    endpoint = sys.env("<OTLP_ENDPOINT>")
  }
}
```

Replace the following:

- *`<OPEN_PORT>`* : The port of the running service for Beyla automatically instrumented with eBPF.
- *`<OTLP_ENDPOINT>`* : The endpoint of the OpenTelemetry Collector to send traces to.

## Compatible components

`beyla.ebpf` can accept arguments from the following components:

- Components that export [OpenTelemetry `otelcol.Consumer`](../../../compatibility/#opentelemetry-otelcolconsumer-exporters)

`beyla.ebpf` has exports that can be consumed by the following components:

- Components that consume [Targets](../../../compatibility/#targets-consumers)

> Note
> 
> Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.