Skip to content

Clarify OBI support, compatibility, and limitations docs #9642

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
theletterf merged 3 commits into from
Apr 20, 2026
+156 −41
Merged

Clarify OBI support, compatibility, and limitations docs #9642

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
efe2d11
Update the OBI docs based on its support matrix
MrAlias Apr 13, 2026
a7462e6
Address feedback
MrAlias Apr 13, 2026
909f5ad
Merge branch 'main' into obi-support-matrix
theletterf Apr 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 44 additions & 36 deletions content/en/docs/zero-code/obi/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ cascade:
OTEL_RESOURCE_ATTRIBUTES_APPLICATION: obi
OTEL_RESOURCE_ATTRIBUTES_NAMESPACE: obi
OTEL_RESOURCE_ATTRIBUTES_POD: obi
cSpell:ignore: asyncio CAP_PERFMON uvloop
cSpell:ignore: asyncio uvloop
---

OpenTelemetry libraries provide telemetry collection for popular programming
Expand Down Expand Up @@ -85,55 +85,63 @@ For a complete list of changes and upgrade notes, see the
If you want to explore the new NGINX example, see the
[example walkthrough](https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation/tree/v0.7.0/examples/nginx).

## Requirements
## How OBI works

OBI requires the following to run:

- Linux kernel version 5.8 or later (or 4.18 for Redhat Enterprise Linux)
- An x86_64 or arm64 processor
- Runtime support for eBPF (most modern Linux distributions)
- Administrative privileges (root access) or the specific capabilities listed in
the [configuration reference](security/)
The following diagram shows the high-level OBI architecture and where eBPF
instrumentation fits into the telemetry pipeline.

![OBI eBPF architecture](./ebpf-arch.svg)

## Compatibility

OBI is tested with the following Linux distributions:
OBI supports Linux environments that meet the following requirements:

| Requirement | Supported |
| :--------------- | :-------------------------------------------------------------------- |
| CPU architecture | `amd64`, `arm64` |
| Linux kernel | `5.8+`, or RHEL-family Linux `4.18+` with the required eBPF backports |
| Kernel features | BTF |
| Privileges | Root, or the Linux capabilities required by the enabled OBI features |

OBI publishes the following supported release artifacts:

| Artifact | Supported platforms |
| :----------------------------------------------- | :--------------------------- |
| `obi` binary archive | Linux `amd64`, Linux `arm64` |
| `k8s-cache` binary archive | Linux `amd64`, Linux `arm64` |
| `otel/ebpf-instrument` container image | Linux `amd64`, Linux `arm64` |
| `otel/ebpf-instrument-k8s-cache` container image | Linux `amd64`, Linux `arm64` |

OBI can be deployed on standalone Linux hosts, in containers, and on Kubernetes
when the environment meets the requirements above.

- Ubuntu 20.04 LTS, 21.04, 22.04 LTS and 23.04
- CentOS 7, 8, and 9
- AlmaLinux 8, 9
- Rocky Linux 8, 9
- Red Hat Enterprise Linux 8, 9
- Debian 11, 12
- openSUSE Leap 15.3, 15.4
- SUSE Linux Enterprise Server 15 SP4
OBI does not support non-Linux operating systems, Linux architectures other than
`amd64` and `arm64`, Linux environments without BTF, or kernel versions earlier
than Linux `5.8` outside the documented RHEL-family `4.18+` exception.

- OBI also supports RedHat-based distributions: RHEL8, CentOS 8, Rocky8,
AlmaLinux8, and others, which ship a Kernel 4.18 that backports eBPF-related
patches.
Feature-specific support details are documented in these guides:

- For instrumenting Go programs, compile with at least Go 1.17. OBI support Go
applications built with a major **Go version no earlier than 3 versions**
behind the current stable major release.
- Administrative access rights to execute OBI.
- [Distributed traces](distributed-traces/): context propagation support,
runtime-specific requirements, and distributed tracing limitations
- [Export data](configure/export-data/): protocol, database, messaging, GenAI,
GPU, and Go library instrumentation support

## Limitations

OBI has its limitations too. It only provides generic metrics and transaction
level trace span information. Language agents and manual instrumentation is
still recommended, so that you can specify the custom attributes and events you
want to capture.
OBI provides application and protocol observability without code changes, but it
does not replace language-level instrumentation in every scenario. Use language
agents or manual instrumentation when you need custom spans,
application-specific attributes, business events, or other in-process telemetry
that eBPF-based instrumentation cannot derive automatically.

While most eBPF programs require elevated privileges, OBI allows you to specify
finer grained permissions to run with minimum required permissions, such as:
`CAP_DAC_READ_SEARCH`, `CAP_SYS_PTRACE`, `CAP_PERFMON`, `CAP_BPF`,
`CAP_CHECKPOINT_RESTORE`, and others.
OBI can automatically capture network and protocol activity, but it cannot
always recover application-specific details that are not visible from eBPF
observation points.

Some OBI functionality requires further permissions, for example using the
network observability probes with Linux Traffic Control requires
`CAP_NET_ADMIN`, but it's a feature you have to optionally enable.
Some features also have additional caveats or narrower support than the core
platform requirements. For details, refer to the feature-specific documentation
for [distributed traces](distributed-traces/) and
[exported instrumentation](configure/export-data/).

For a comprehensive list of capabilities required by OBI, refer to
[Security, permissions and capabilities](security/).
Expand Down
6 changes: 3 additions & 3 deletions content/en/docs/zero-code/obi/configure/collector-receiver.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -493,9 +493,9 @@ Resource usage for OBI as a Collector receiver varies significantly based on:
- **Exporter configuration**: Batch sizes, queue depths, and number of backends
- **Service discovery scope**: Number of processes being monitored

Like [standalone OBI](/docs/zero-code/obi/), the eBPF instrumentation provides
[minimal overhead](/docs/zero-code/obi/#requirements). The Collector pipeline
adds additional resource requirements that depend on your configuration.
Like standalone OBI, the eBPF instrumentation provides minimal overhead. The
Collector pipeline adds additional resource requirements that depend on your
configuration.

**Recommendations**:

Expand Down
88 changes: 87 additions & 1 deletion content/en/docs/zero-code/obi/configure/export-data.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,97 @@ description:
and OpenTelemetry traces
weight: 10
# prettier-ignore
cSpell:ignore: AsterixDB couchbase genai jackc memcached pgxpool pyserver spanmetrics
cSpell:ignore: AsterixDB couchbase genai gonic jackc libcudart memcached pgxpool pyserver segmentio spanmetrics
---

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

## Instrumentation compatibility

OBI supports the following protocol and feature versions for traces and metrics
instrumentation:

| Area | Supported versions | Notes |
| :------------ | :------------------- | :--------------------------------------------------------------------------------------------- |
| HTTP | `1.0/1.1` | Context propagation is supported. |
| HTTP | `2.0` | Context propagation requires Go library-level instrumentation. |
| gRPC | `1.0+` | Long-lived connections started before OBI might use `*` for method names. |
| MySQL | All | Prepared statements created before OBI starts might not include query text. |
| PostgreSQL | All | Prepared statements created before OBI starts might not include query text. |
| Redis | All | Existing connections might not include database number or `db.namespace`. |
| MongoDB | `5.0+` | Compressed payloads are not supported. |
| Couchbase | All | Bucket or collection names might be unavailable when negotiation completed before OBI started. |
| Memcached | All | Supports the ASCII text protocol subset, excluding `quit` and meta commands. |
| Kafka | All | Topic name lookup might fail for fetch API versions `13+`. |
| MQTT | `3.1.1/5.0` | Payloads are not captured. |
| GraphQL | All | No additional documented version limits. |
| Elasticsearch | `7.14+` | No additional documented version limits. |
| OpenSearch | `3.0.0+` | No additional documented version limits. |
| AWS S3 | All | No additional documented version limits. |
| AWS SQS | All | No additional documented version limits. |
| SQL++ | All | No additional documented version limits. |
| GenAI | OpenAI and Anthropic | No additional documented version limits. |

Some application-level instrumentation also depends on specific runtime,
library, or server versions:

| Area | Supported versions | Notes |
| :---------------- | :--------------------------------------- | :----------------------------------------------------------------------- |
| Go applications | Go `1.17+` | Applies to Go library-level instrumentation. |
| Java applications | JDK `8+` | No additional documented runtime constraints. |
| NGINX | Validated on NGINX `1.27.5` and `1.29.7` | These are the NGINX versions currently covered by documented validation. |
Comment thread
MrAlias marked this conversation as resolved.
Outdated

### Go library instrumentation compatibility

OBI supports the following Go libraries and minimum versions for application
instrumentation:

| Library | Supported versions |
| :------------------------------- | :------------------------------ |
| `net/http` | `>= 1.17` |
| `golang.org/x/net/http2` | `>= 0.12.0` |
| `github.com/gorilla/mux` | `>= v1.5.0` |
| `github.com/gin-gonic/gin` | `>= v1.6.0`, `!= v1.7.5` |
| `google.golang.org/grpc` | `>= 1.40` |
| `net/rpc/jsonrpc` | `>= 1.17` |
| `database/sql` | `>= 1.17` |
| `github.com/go-sql-driver/mysql` | `>= v1.5.0` |
| `github.com/lib/pq` | all versions |
| `github.com/redis/go-redis/v9` | `>= v9.0.0` |
| `github.com/segmentio/kafka-go` | `>= v0.4.11` |
| `github.com/IBM/sarama` | `>= 1.37` |
| `go.mongodb.org/mongo-driver` | `v1: >= v1.10.1; v2: >= v2.0.1` |

The versions listed in these tables are the versions OBI explicitly supports.
Other versions might also work, but they are not part of the documented support
scope unless stated otherwise.

### GPU instrumentation compatibility

OBI supports GPU instrumentation when the environment meets the
[OBI compatibility requirements](/docs/zero-code/obi/#compatibility) and the
application uses a supported CUDA runtime library.

| Requirement | Supported |
| :------------------- | :----------------------------- |
| Operating system | Linux |
| CPU architecture | `amd64`, `arm64` |
| CUDA runtime library | `libcudart.so` for CUDA `7.0+` |

OBI instruments the following CUDA operations:

| Operation |
| :----------------- |
| `cudaLaunchKernel` |
| `cudaGraphLaunch` |
| `cudaMalloc` |
| `cudaMemcpy` |
| `cudaMemcpyAsync` |

GPU instrumentation only applies to applications that use the supported CUDA
runtime library and operations listed above. Other GPU APIs, frameworks, or
libraries are outside the documented support scope unless stated otherwise.

## Common metrics configuration

YAML section: `metrics`.
Expand Down
20 changes: 19 additions & 1 deletion content/en/docs/zero-code/obi/distributed-traces.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,24 @@ instead its own generated trace context. If OBI cannot find an incoming
`traceparent` context value, it generates one according to the W3C
specification.

## Compatibility

OBI supports distributed tracing and context propagation in the following
configurations:

| Area | Supported versions or environments | Notes |
| :----------------------------------- | :---------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------- |
| Network-level context propagation | Linux environments that meet the [OBI compatibility requirements](/docs/zero-code/obi/#compatibility) | Works across programming languages for HTTP and HTTPS traffic. gRPC and HTTP/2 are not supported at network level. |
| Go library-level context propagation | Go `1.18+` | Supports goroutine context propagation up to 3 nested goroutine levels. |
| Node.js async hooks | Node.js `8.0+` | Custom handling of `SIGUSR1` can interfere with context propagation. |
Comment thread
MrAlias marked this conversation as resolved.
Outdated
| Ruby Puma | Ruby applications served by Puma `5.0+` | Context propagation support requires the Puma server. |
| Java thread pools | JDK `8+` | No additional documented runtime constraints. |
| Python asyncio | Python `3.9+` with `uvloop` | Context propagation support requires the `uvloop` event loop. |

The versions listed here are the versions OBI explicitly supports for
distributed tracing features. Other versions might also work, but they are not
part of the documented support scope unless stated otherwise.
Comment thread
MrAlias marked this conversation as resolved.
Outdated

## Implementation

The trace context propagation is implemented in two different ways:
Expand Down Expand Up @@ -70,7 +88,7 @@ disrupt the TCP/IP context propagation, because the original packets are
discarded and replayed downstream. Parsing incoming trace context information
from OpenTelemetry SDK instrumented services still works.

gRPC and HTTP/2 are not supported at the moment.
gRPC and HTTP/2 are not supported at network level.

This type of context propagation works for any programming language and doesn't
require that OBI runs in `privileged` mode or has `CAP_SYS_ADMIN` granted. For
Expand Down
Loading
⚡