Upgrade Beyla component to 2.5.4 #4100
+870
−73
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -25,7 +25,7 @@ To run this component, {{< param "PRODUCT_NAME" >}} requires administrative priv | |
| The number of required capabilities depends on the specific use case. | ||
| Refer to the [Beyla capabilities](https://grafana.com/docs/beyla/latest/security/#list-of-capabilities-required-by-beyla) for more information. | ||
|
|
||
| In Kubernetes environments, the [AppArmor profile must be `Unconfined`](https://kubernetes.io/docs/tutorials/security/apparmor/#securing-a-pod) for the Deployment or DaemonSet running {{< param "PRODUCT_NAME" >}}. You will also need to set the `hostPID` flag to `true` in the Pod spec so that in can access all the processes running on the host. | ||
marctc marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| {{< /admonition >}} | ||
|
|
||
| ## Usage | ||
|
|
@@ -76,6 +76,7 @@ You can use the following blocks with `beyla.ebpf`: | |
| | `discovery` > `exclude_services` > [`kubernetes`][kubernetes services] | Configures the Kubernetes services to exclude for the component. | no | | ||
| | `discovery` > [`services`][services] | Configures the services to discover for the component. | no | | ||
| | `discovery` > `services` > [`kubernetes`][kubernetes services] | Configures the Kubernetes services to discover for the component. | no | | ||
| | `discovery` > `services` > [`sampler`][sampler] | Configures trace sampling for the service. | no | | ||
| | `discovery` > [`survey`][services] | Configures the surveying mechanism for the component. | no | | ||
| | `discovery` > `survey` > [`kubernetes`][kubernetes services] | Configures the Kubernetes surveying mechanism for the component. | no | | ||
| | [`ebpf`][ebpf] | Configures eBPF-specific settings. | no | | ||
|
|
@@ -84,17 +85,20 @@ You can use the following blocks with `beyla.ebpf`: | |
| | `filters` > [`network`][network filters] | Configures filtering of network attributes. | no | | ||
| | [`metrics`][metrics] | Configures which metrics Beyla exposes. | no | | ||
| | `metrics` > [`network`][network metrics] | Configures network metrics options for Beyla. | no | | ||
| | `traces` | Configures trace collection and sampling options for all services instrumented by the component. | no | | ||
marctc marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| | [`routes`][routes] | Configures the routes to match HTTP paths into user-provided HTTP routes. | no | | ||
|
|
||
| The > symbol indicates deeper levels of nesting. | ||
| For example, `attributes` > `kubernetes` refers to a `kubernetes` block defined inside an `attributes` block. | ||
|
|
||
| [routes]: #routes | ||
| [traces]: #traces | ||
| [attributes]: #attributes | ||
| [kubernetes attributes]: #kubernetes-attributes | ||
| [kubernetes services]: #kubernetes-services | ||
| [discovery]: #discovery | ||
| [services]: #services | ||
| [sampler]: #sampler | ||
| [instance_id]: #instance_id | ||
| [select]: #select | ||
| [ebpf]: #ebpf | ||
|
|
@@ -135,7 +139,7 @@ This `kubernetes` block configures the decorating of the metrics and traces with | |
| |----------------------------|----------------|--------------------------------------------------------|---------|----------| | ||
| | `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_restrict_local_node` | `bool` | Restrict Kubernetes metadata collection to local node. | `false` | no | | ||
|
|
@@ -244,13 +248,14 @@ The `services` block configures the services to discover for the component. | |
| The `exclude_services` block configures the services to exclude for the component. | ||
| The `survey` block configures the services that the component will emit information for. | ||
|
|
||
| | 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 | | ||
| | `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 regular expression to be matched against the full executable command line, including the directory where the executable resides on the file system. | ||
|
|
||
|
|
@@ -260,6 +265,8 @@ It's used to populate the `service.name` OTel property or the `service_name` Pro | |
| `open_port` 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. | ||
|
|
||
| If the block is defined as `survey` then the component will discover services but instead of instrumenting them via metrics and traces, it will only emit a `survey_info` metric for each. | ||
| This can be helpful in informing external applications of the services available for instrumentation before building out the `service` and `exclude_services` block and telemetry flows through. | ||
|
|
||
|
|
@@ -310,6 +317,112 @@ beyla.ebpf "default" { | |
| } | ||
| ``` | ||
|
|
||
|
|
||
|
|
||
| ### `traces` | ||
marctc marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| The `traces` block configures trace collection and sampling options for the beyla.ebpf component. | ||
|
|
||
| {{< admonition type="note" >}} | ||
| To export traces, you must also configure the [`output`][output] block with a `traces` destination. Without an output configuration, traces will be collected but not exported. | ||
marctc marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| {{< /admonition >}} | ||
|
|
||
| | Name | Type | Description | Default | Required | | ||
| |-------------------|----------------|------------------------------------------------------------------|---------|----------| | ||
| | `instrumentations` | `list(string)` | List of instrumentations to enable for trace collection. | `["*"]` | no | | ||
|
|
||
| The `traces` block contains the following sub-blocks: | ||
|
|
||
| - [`sampler`][sampler] - configures global trace sampling settings. See the [`sampler`][sampler] section for detailed configuration options. | ||
|
Comment on lines
+335
to
+337
There was a problem hiding this comment. For child blocks, this is usually documented in the blocks table (lines 67-89). I'd expect that a child block of I've added this as a comment to that section of the table. If this is correct, then lines 334-336 should be deleted. There was a problem hiding this comment. Hey @clayton-cornell, the thing is the sampler section has the same config block for the block traces and for each invidual discovery service section, so I wanted to avoid repeat the block There was a problem hiding this comment. We shouldn't have to repeat the block. It's defined once (below on lines 369-390). If it's noted as a child block in the block table, then it's all consistent with other component topics that have child blocks in multiple places. We don't note child block hierarchy in the block descriptions... only in the block tables. |
||
|
|
||
| #### `instrumentations` | ||
|
|
||
| `instrumentations` is a list of instrumentations to enable for trace collection. The following instrumentations are available: | ||
marctc marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| * `*` enables all `instrumentations`. If `*` is present in the list, the other values are ignored. | ||
| * `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. | ||
| * `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. | ||
marctc marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| Example: | ||
|
|
||
| ```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` > `services` 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` > `services` 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 | ||
|
|
||
| | Name | Type | Description | Default | Required | | ||
| |--------|----------|-------------------------------------------------------------------------|---------|----------| | ||
| | `name` | `string` | The name of the sampling strategy to use. | `""` | no | | ||
| | `arg` | `string` | The argument for the sampling strategy. | `""` | no | | ||
marctc marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| The following sampling strategies are supported: | ||
marctc marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| * `traceidratio`: Samples traces based on a ratio of trace IDs. The `arg` should be a decimal value between 0 and 1 (e.g., "0.1" for 10% sampling). | ||
marctc marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| * `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` should be a decimal value between 0 and 1. | ||
marctc marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| #### Examples | ||
|
|
||
| Per-service sampling (configured within `discovery` > `services`): | ||
|
|
||
| ```alloy | ||
| beyla.ebpf "default" { | ||
| discovery { | ||
| services { | ||
| open_ports = "8080" | ||
| sampler { | ||
| name = "traceidratio" | ||
| arg = "0.1" // 10% sampling rate for this specific service | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| Global sampling (configured within `traces`): | ||
|
|
||
| ```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. | ||
|
|
@@ -417,6 +530,8 @@ The `metrics` block configures which metrics Beyla collects. | |
| * `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. | ||
|
|
@@ -425,8 +540,10 @@ The `metrics` block configures which metrics Beyla collects. | |
|
|
||
| * `*` enables all `instrumentations`. If `*` is present in the list, the other values are ignored. | ||
| * `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. | ||
| * `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. | ||
|
|
||
|
|
@@ -599,11 +716,6 @@ This example gets metrics from `beyla.ebpf` for the specified namespace and Pods | |
|
|
||
| ```alloy | ||
| beyla.ebpf "default" { | ||
| discovery { | ||
| services { | ||
| kubernetes { | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It'd be good to mention which version we're upgrading from. After all users would need to check the changelogs of all the intermediate versions too.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It'd be especially good to mention any breaking changes. Normally breaking changes should be described in the release notes in more detail.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Do we also want to put there breaking changes from things that are not config? We introduced some breaking changes that are more from behaviour but I dont think honestly affects much to the component.