feat(beyla.ebpf): Bump to v3.7.0

[grafana-alloybot]

Summary

• Bumps github.com/grafana/beyla/v3 from v3.6.0 to v3.7.0
• Bumps go.opentelemetry.io/obi replacement from OBI pseudo-version v1.12.2-0.20260318145328-e31c5acda289 to tagged release v1.16.2 (grafana/opentelemetry-ebpf-instrumentation)
• Adds the new stats block mapping to the Alloy Beyla integration for parity with Beyla v3.7.0

OBI replacement bump

The .obi-src gitlink in Beyla at tag v3.7.0 points to 9632afd12f59cda12c2958415beb420abca6a3e2, which is the tip of the v1.16.2 tag on grafana/opentelemetry-ebpf-instrumentation.

New fields: stats block

Beyla v3.7.0 adds Stats obi.StatsConfig to beyla.Config, enabling the new Stats Observability (FeatureStatsO11y) mode. The following fields are now exposed:

Alloy attr	OBI field	Type
agent_ip	AgentIP	string
agent_ip_iface	AgentIPIface	string
agent_ip_type	AgentIPType	string
cidrs	CIDRs	list(string)
print_stats	Print	bool

The "stats" value is also added to the valid metrics.features set.

Notable fix

beyla.DefaultConfig() in v3.7.0 mutates the global obi.DefaultConfig.Routes pointer when applying the new UnmatchLowCardinality default. This caused Routes.Convert() to have its result overwritten by subsequent DefaultConfig() calls (e.g., inside Attributes.Convert()). Fixed by deep-copying the default RoutesConfig struct in Routes.Convert().

🤖 Generated with Claude Code

[github-actions]

💻 Deploy preview available (chore(beyla): Bump to v3.7.0):

• https://deploy-preview-alloy-5966-zb444pucvq-vp.a.run.app/docs/alloy/latest/

[github-actions]

💻 Deploy preview available (feat(beyla): Bump to v3.7.0):

• https://deploy-preview-alloy-5966-zb444pucvq-vp.a.run.app/docs/alloy/latest/

[github-actions]

💻 Deploy preview available (feat(beyla.ebpf): Bump to v3.7.0):

• https://deploy-preview-alloy-5966-zb444pucvq-vp.a.run.app/docs/alloy/latest/

[github-actions]

🔍 Dependency Review

Below are the dependency upgrades detected in go.mod and associated replace directives, along with the concrete code/config changes required to adopt them. For each, I’ve included evidence and minimal diffs to maintain current behavior.

---

github.com/grafana/beyla/v3 v3.6.0 -> v3.7.0 — ⚠️ Needs Review

Impact summary:

• New “stats” metrics feature and config block are available (opt‑in).
• The default config’s Routes is returned as a pointer; mutating it directly can now affect the shared default. Copy before modifying to avoid unintended global mutations.
• Java auto-injection flows may benefit from explicitly declaring open_ports and a higher attach timeout in tests (behavioral improvement, not API break).

Required code/config changes (to preserve/extend behavior):

1. Avoid mutating the shared default Routes pointer

• Why: In v3.7.0, beyla.DefaultConfig().Routes is a pointer to a default instance. Direct mutations can change the default globally for subsequent calls/usages.
• Change:

- func (args Routes) Convert() *transform.RoutesConfig {
-     routes := beyla.DefaultConfig().Routes
+ func (args Routes) Convert() *transform.RoutesConfig {
+     defaultRoutes := *beyla.DefaultConfig().Routes
+     routes := &defaultRoutes
      if args.Unmatch != "" {
          routes.Unmatch = transform.UnmatchType(args.Unmatch)
      }
      ...
      return routes
  }

2. Wire up the new “stats” feature (optional, but supported)

• Add a new stats block to arguments, validate “stats” as a metrics feature, convert to beyla/OBI config, and assign to cfg.Stats.

Code additions:

--- internal/component/beyla/ebpf/args.go
+++ internal/component/beyla/ebpf/args.go
@@
 type Arguments struct {
   ...
   Injector       Injector                   `alloy:"injector,block,optional"`
+  Stats          Stats                      `alloy:"stats,block,optional"`
 }
@@
+type Stats struct {
+  AgentIP      string   `alloy:"agent_ip,attr,optional"`
+  AgentIPIface string   `alloy:"agent_ip_iface,attr,optional"`
+  AgentIPType  string   `alloy:"agent_ip_type,attr,optional"`
+  CIDRs        []string `alloy:"cidrs,attr,optional"`
+  Print        bool     `alloy:"print_stats,attr,optional"`
+}

--- internal/component/beyla/ebpf/beyla_linux.go
+++ internal/component/beyla/ebpf/beyla_linux.go
@@
 func (args Metrics) Validate() error {
   validFeatures := map[string]struct{}{
     "application": {}, "application_db": {}, "application_exceptions": {},
     "application_span_sizes": {}, "application_host": {},
     "application_service_graph": {}, "application_process": {},
-    "network": {}, "network_inter_zone": {},
+    "network": {}, "network_inter_zone": {}, "stats": {},
   }
   ...
 }
@@
+func (args Stats) Convert() obi.StatsConfig {
+  stats := beyla.DefaultConfig().Stats
+  if args.AgentIP != "" {
+    stats.AgentIP = args.AgentIP
+  }
+  if args.AgentIPIface != "" {
+    stats.AgentIPIface = obi.AgentTypeIface(args.AgentIPIface)
+  }
+  if args.AgentIPType != "" {
+    stats.AgentIPType = args.AgentIPType
+  }
+  if args.CIDRs != nil {
+    stats.CIDRs = args.CIDRs
+  }
+  stats.Print = args.Print
+  return stats
+}
@@
 func (a *Arguments) Convert() (*beyla.Config, error) {
   ...
   cfg.NetworkFlows = a.Metrics.Network.Convert()
+  cfg.Stats = a.Stats.Convert()
   ...
 }

3. Documentation updates (to expose the new feature and options)

• Mention “stats” as a feature in metrics and add a “stats” configuration block.

--- docs/sources/reference/components/beyla/beyla.ebpf.md
+++ docs/sources/reference/components/beyla/beyla.ebpf.md
@@
 * `network` exports network-level metrics.
 * `network_inter_zone` exports network-level inter-zone metrics.
+* `stats` exports kernel-level connection statistics per service.
@@
+### `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.
+| 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. (`ipv4`, `ipv6`, `any`)                                | `"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       |

4. Java injection test stability improvements (recommended)

• Specify open_ports for discovery/injector instrumentation (helps target the proper process/port).
• Increase the Java agent attach timeout.

--- integration-tests/docker/tests/beyla-java/config.alloy
+++ integration-tests/docker/tests/beyla-java/config.alloy
@@
   discovery {
     instrument {
       name = "petclinic"
+      open_ports = "8080"
       exe_path = "*java"
       containers_only = true
       exports = ["traces"]
@@
   injector {
     instrument {
+      open_ports = "8080"
       exe_path = "*java"
     }
     enabled_sdks = ["java"]

--- integration-tests/docker/tests/beyla-java/docker-compose.yaml
+++ integration-tests/docker/tests/beyla-java/docker-compose.yaml
@@
   alloy:
     image: alloy-integration-tests
+    environment:
+      OTEL_EBPF_JAVAAGENT_ATTACH_TIMEOUT: "30s"

Changelog highlights (evidence)

• Added a new stats feature for kernel-level connection statistics with related config (stats block) that can be enabled via metrics.features=["stats"].
• Default config returns pointers in some nested fields (e.g., Routes) — direct mutation risks altering the shared default.

---

go.opentelemetry.io/obi (replaced by) github.com/grafana/opentelemetry-ebpf-instrumentation v1.12.2-0... -> v1.16.2 — ⚠️ Needs Review

Impact summary:

• New StatsConfig surfaced in the OBI API (enables wiring the new Beyla stats feature).
• Minor type surface additions such as obi.AgentTypeIface to specify agent IP interface selection.
• No breaking changes detected for existing usage of export/transform/filter/kube packages between these versions in this repo, but you can optionally adopt new stats wiring.

Recommended (optional) code changes to adopt new functionality:

• Map the new Alloy config “stats” block to OBI’s new StatsConfig, and plumb into the Beyla config.

Code changes:

--- internal/component/beyla/ebpf/beyla_linux.go
+++ internal/component/beyla/ebpf/beyla_linux.go
@@
+import (
+  ...
+  "go.opentelemetry.io/obi/pkg/obi"
+)
@@
+func (args Stats) Convert() obi.StatsConfig {
+  stats := beyla.DefaultConfig().Stats
+  if args.AgentIP != "" {
+    stats.AgentIP = args.AgentIP
+  }
+  if args.AgentIPIface != "" {
+    stats.AgentIPIface = obi.AgentTypeIface(args.AgentIPIface)
+  }
+  if args.AgentIPType != "" {
+    stats.AgentIPType = args.AgentIPType
+  }
+  if args.CIDRs != nil {
+    stats.CIDRs = args.CIDRs
+  }
+  stats.Print = args.Print
+  return stats
+}

Evidence (from the OBI fork’s API surface across these versions):

• Introduction of type StatsConfig struct { AgentIP string; AgentIPIface AgentTypeIface; AgentIPType string; CIDRs []string; Print bool } in go.opentelemetry.io/obi/pkg/obi.
• type AgentTypeIface string exposed for interface selection semantics.

Tests adapted to the new surface:

--- internal/component/beyla/ebpf/beyla_linux_test.go
+++ internal/component/beyla/ebpf/beyla_linux_test.go
@@
- import (
+ import (
    ...
+   "go.opentelemetry.io/obi/pkg/obi"
  )
@@
 func TestConvert_Stats(t *testing.T) {
   args := Stats{
     AgentIP:      "0.0.0.0",
     AgentIPIface: "local",
     AgentIPType:  "ipv4",
     CIDRs:        []string{"10.0.0.0/8"},
     Print:        true,
   }
   expectedConfig := beyla.DefaultConfig().Stats
   expectedConfig.AgentIP = args.AgentIP
   expectedConfig.AgentIPIface = obi.AgentTypeIface(args.AgentIPIface)
   expectedConfig.AgentIPType = args.AgentIPType
   expectedConfig.CIDRs = args.CIDRs
   expectedConfig.Print = args.Print
   require.Equal(t, expectedConfig, args.Convert())
 }

Notes

• If you do not enable or wire the new stats feature, existing code paths should continue to compile and run as before with v1.16.2 based on current usage in this repo.
• Ensure your replace directives are consistent across modules (collector, extension, root), as done in this PR.

---

Notes

• The PR also includes test reliability improvements (Tempo probe function and Java traffic generation). These are not strictly required by the dependency upgrades but help minimize flakiness with the newer eBPF/auto-injection flows.
• No net-new direct dependencies were introduced beyond version bumps and replace adjustments.

[grcevski]

LGTM!