Component donation: OBI (eBPF-based Zero-Code Instrumentation) Receiver

[MrAlias]

This is not a standard request to add a receiver directly into collector-contrib. The core issue is build integration: OBI requires generated eBPF artifacts that are not committed to its git history, so a plain go get build is not possible without a pre-build generation step.

I am asking for guidance on integrating OBI into collector-releases (and the otelcol-contrib distribution), specifically whether a submodule-based integration is acceptable in this repo and workable in CI.

Note

TL;DR:

• OBI needs generated eBPF artifacts that are not in git, so builds require a pre-generation step.
• OBI does not require CGO, so it does not need the same distribution restrictions as the eBPF profiler.
• OBI can already be built into a collector (see the OBI repo example: https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation/tree/main/examples/otel-collector), so this is about upstreaming build integration.
• I am asking how best to integrate OBI into collector-releases (and the otelcol-contrib distribution), including whether submodules are acceptable here.
• The contrib-donation option is included only to show why it is currently not viable for OBI's build model.

Building and distributing outside this repository

• I understand I can use and distribute my component outside of this repository.

Existing component implementation

https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation

Components covering similar use cases

No direct equivalents - OBI is unique in being an OpenTelemetry project providing zero-code instrumentation via eBPF. Comparable external projects include Grafana Beyla and Pixie, but OBI is the OpenTelemetry-native option (open-telemetry org, OTel semantic conventions, and a Collector receiver), which is why it should be included rather than those projects.

Related receivers:

• Standard instrumentation receivers (e.g., jaegerreceiver, zipkinreceiver) require application-level SDKs
• hostmetricsreceiver provides host-level metrics but not application tracing
• ebpf-profiler (separate distribution) provides continuous profiling, not tracing/metrics

The purpose and use-cases of the component

Purpose

Enable distributed tracing and metrics for applications without modifying code or deploying SDKs. Particularly valuable for:

• Legacy applications where code changes are difficult/impossible
• Polyglot environments with inconsistent instrumentation
• Quick proof-of-concept observability deployments
• Applications with vendor SDKs that can't be instrumented

Use Cases

1. Zero-code observability: Deploy collector as a DaemonSet and automatically instrument applications
2. Protocol support: HTTP/1.1, HTTP/2, gRPC, databases (MySQL, PostgreSQL, Redis, MongoDB), messaging (Kafka, RabbitMQ). Full, authoritative list in OBI docs: https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation/blob/main/devdocs/features.md
3. Kubernetes integration: Automatic service discovery and pod/container attribute enrichment
4. Standard telemetry: Generates OpenTelemetry-compliant traces and metrics

Collector components enhance OBI telemetry with standard pipeline features such as resource enrichment (resourcedetectionprocessor, k8sattributesprocessor), safety and efficiency (memorylimiterprocessor, batchprocessor), and shaping (attributesprocessor, transformprocessor) before export. This provides needed functionality without OBI having to re-implement those features.

Example configuration for the component

receivers:
  obi:
    open_port: "8000"
    # Additional OBI configuration here.
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

processors:
  batch:
    timeout: 1s
    send_batch_size: 1024

exporters:
  debug:
    verbosity: detailed
  otlp/jaeger:
    endpoint: localhost:14317
    tls:
      insecure: true

service:
  pipelines:
    traces:
      receivers: [otlp, obi]
      processors: [batch]
      exporters: [otlp/jaeger, debug]
  telemetry:
    logs:
      level: debug

Source: https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation/blob/main/examples/otel-collector/config.yaml

Telemetry data types supported

trace and metrics (so far)

Code Owners

• https://github.com/MrAlias
• https://github.com/NimrodAvni78

Sponsor (optional)

@dashpole

Integration Approach

OBI in an existing OTel component that has an existing collector receiver. It has unique build requirements in that it needs binary files generated prior to building. These files are not tracked in the source-code and therefore cannot be integrated directly as a standard component.

Instead, I propose integration via the distribution. Below are all the option considered though for completeness.

Option A: Add to otelcol-contrib distribution (Recommended)

Keep OBI in its upstream repo and integrate it into the otelcol-contrib distribution via collector-releases (submodule + replace + generation).

Prototype branch

Rationale

• OBI is a general-purpose receiver for application observability
• Works with standard collector components (no curation needed)
• Follows typical deployment patterns (daemonset, gateway)
• Similar to other receivers in purpose and scope

Implementation

• Working PoC: open-telemetry/opentelemetry-collector-releases@main...USER:obi-integration
• Uses git submodule + replace directive + manifest import: field
• Makefile targets for eBPF artifact generation (make generate-obi)
• Successfully tested build with OBI included

Build Requirements

• eBPF code generation (via make docker-generate in OBI repo)
• Requires Docker, takes 2-5 minutes (cacheable)
• Does NOT require CGO (uses //go:build linux)
• Generated artifacts needed before Go compilation

Trade-offs

• Correct location for general-purpose receivers
• Maximum distribution and discoverability
• Git submodule in releases repo (first external component via submodule)
• Build-time generation requirement
• CI workflow updates needed

Option B: Donate OBI to collector-contrib repository

Copy OBI into collector-contrib as a donated receiver and make it part of the repo.

Rationale

• Standard path for new receivers (see CONTRIBUTING.md)
• Code lives in the primary collector-contrib repo
• Maximum integration with community development practices
• Automatic inclusion in distributions

Challenges

• eBPF artifacts not in git: OBI's generated eBPF code (~50MB) is not checked into the repository
• Build requirement: requires make docker-generate before Go compilation
• Breaks standard workflow: can't go get and build without pre-generation step
• Docker dependency: generation requires Docker, complicates local development
• Code duplication: donating to contrib would require copying the collector package from the OBI repo, which duplicates upstream code and adds long-term maintenance overhead
• Divergence risk: would need to fork OBI or vendor generated artifacts

Why This Doesn't Work

The collector-contrib repository expects components to be buildable as standard Go modules. OBI's architecture separates eBPF source (in C) from generated Go code. The generated artifacts are:

1. Platform-specific (different for each Linux kernel version)
2. Large (~50MB of generated code)
3. Not appropriate for version control (per OBI project policy)
4. Require Docker for generation

This would break the standard go build workflow that all other receivers follow.

Alternatives Considered

• Fork and vendor artifacts: creates maintenance burden, diverges from upstream
• Check in generated code: not current OBI practice, large git bloat
• Require generation step: breaks Go module ecosystem expectations

Option C: Separate otelcol-obi distribution

Create a dedicated distribution that packages OBI separately from otelcol-contrib.

Rationale

• Similar to otelcol-ebpf-profiler distribution
• Isolates build complexity
• Could combine with future eBPF-based receivers

Concerns

• Doesn't meet distribution criteria Create CODEOWNERS #1: "specific purpose with minimal overlap"
• OBI provides general application observability (not specialized like ebpf-profiler's system-wide profiling)
• No need for component curation (works with all standard components)
• Creates fragmentation for users

Related Documentation

• OBI repo overview and setup: https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation
• OBI collector example: https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation/tree/main/examples/otel-collector
• OBI protocol support list: https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation/blob/main/devdocs/features.md

Questions for Maintainers

1. Submodule policy: is a git submodule acceptable in collector-releases for external components that require build-time generation?
2. Codegen policy: is eBPF generation materially different from other codegen in the project in terms of review or maintenance expectations?
3. Generation step viability: is the OBI eBPF generation step viable for this repository (tooling, maintenance expectations)?
4. Platform support: OBI is Linux-only (uses //go:build linux). Is this acceptable given existing Linux-only receivers?

Timeline

Targeting completion before KubeCon EU 2026, while prioritizing a correct integration path.

Tip

_{React with 👍 to help prioritize this issue. Please use comments to provide useful context, avoiding +1 or me too, to help us triage it. Learn more here.}

[MrAlias]

Sponsor updated to @dashpole 🎉

[atoulme]

1. Submodule policy: is a git submodule acceptable in collector-releases for external components that require build-time generation?
   probably not. I like it tagged and clean. Submodules have caused a lot of pain in most of my time in OSS development.
2. Codegen policy: is eBPF generation materially different from other codegen in the project in terms of review or maintenance expectations?
   I don't see a big problem there.
3. Generation step viability: is the OBI eBPF generation step viable for this repository (tooling, maintenance expectations)?
   We need more info on this, but we use code generation heavily throughout.
4. Platform support: OBI is Linux-only (uses //go:build linux). Is this acceptable given existing Linux-only receivers?
   that is fine. See journaldreceiver for a take on this. The receiver will fail to start on Windows. So there is a _other.go variant you build for non-linux systems to make it explicitly fail.

[MrAlias]

1. probably not. I like it tagged and clean. Submodules have caused a lot of pain in most of my time in OSS development.

@atoulme is your suggestion to download the OBI released zip file and run make generate in that as a build step?

To be clear, OBI does not ship complete source. The eBPF objects need to be added with a generate step.

[MrAlias]

WIP: open-telemetry/opentelemetry-collector-releases#1386