Skip to content

Commit efe2d11

Browse files
MrAliasMrAlias
committed
Update the OBI docs based on its support matrix
1 parent 81dc000 commit efe2d11

File tree

4 files changed

+153
-41
lines changed

4 files changed

+153
-41
lines changed

‎content/en/docs/zero-code/obi/_index.md‎

Lines changed: 44 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ cascade:
99
OTEL_RESOURCE_ATTRIBUTES_APPLICATION: obi
1010
OTEL_RESOURCE_ATTRIBUTES_NAMESPACE: obi
1111
OTEL_RESOURCE_ATTRIBUTES_POD: obi
12-
cSpell:ignore: asyncio CAP_PERFMON uvloop
12+
cSpell:ignore: asyncio uvloop
1313
---
1414

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

88-
## Requirements
88+
## How OBI works
8989

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

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

10095
## Compatibility
10196

102-
OBI is tested with the following Linux distributions:
97+
OBI supports Linux environments that meet the following requirements:
98+
99+
| Requirement | Supported |
100+
| :--------------- | :-------------------------------------------------------------------- |
101+
| CPU architecture | `amd64`, `arm64` |
102+
| Linux kernel | `5.8+`, or RHEL-family Linux `4.18+` with the required eBPF backports |
103+
| Kernel features | BTF |
104+
| Privileges | Root, or the Linux capabilities required by the enabled OBI features |
105+
106+
OBI publishes the following supported release artifacts:
107+
108+
| Artifact | Supported platforms |
109+
| :----------------------------------------------- | :--------------------------- |
110+
| `obi` binary archive | Linux `amd64`, Linux `arm64` |
111+
| `k8s-cache` binary archive | Linux `amd64`, Linux `arm64` |
112+
| `otel/ebpf-instrument` container image | Linux `amd64`, Linux `arm64` |
113+
| `otel/ebpf-instrument-k8s-cache` container image | Linux `amd64`, Linux `arm64` |
114+
115+
OBI can be deployed on standalone Linux hosts, in containers, and on Kubernetes
116+
when the environment meets the requirements above.
103117

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

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

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

122129
## Limitations
123130

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

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

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

138146
For a comprehensive list of capabilities required by OBI, refer to
139147
[Security, permissions and capabilities](security/).

‎content/en/docs/zero-code/obi/configure/collector-receiver.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -493,9 +493,9 @@ Resource usage for OBI as a Collector receiver varies significantly based on:
493493
- **Exporter configuration**: Batch sizes, queue depths, and number of backends
494494
- **Service discovery scope**: Number of processes being monitored
495495

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

500500
**Recommendations**:
501501

‎content/en/docs/zero-code/obi/configure/export-data.md‎

Lines changed: 87 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,97 @@ description:
66
and OpenTelemetry traces
77
weight: 10
88
# prettier-ignore
9-
cSpell:ignore: AsterixDB couchbase genai jackc memcached pgxpool pyserver spanmetrics
9+
cSpell:ignore: AsterixDB couchbase genai gonic jackc libcudart memcached pgxpool pyserver segmentio spanmetrics
1010
---
1111

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

14+
## Instrumentation compatibility
15+
16+
OBI supports the following protocol and feature versions for traces and metrics
17+
instrumentation:
18+
19+
| Area | Supported versions | Notes |
20+
| :------------ | :------------------- | :--------------------------------------------------------------------------------------------- |
21+
| HTTP | `1.0/1.1` | Context propagation is supported. |
22+
| HTTP | `2.0` | Context propagation requires Go library-level instrumentation. |
23+
| gRPC | `1.0+` | Long-lived connections started before OBI might use `*` for method names. |
24+
| MySQL | All | Prepared statements created before OBI starts might not include query text. |
25+
| PostgreSQL | All | Prepared statements created before OBI starts might not include query text. |
26+
| Redis | All | Existing connections might not include database number or `db.namespace`. |
27+
| MongoDB | `5.0+` | Compressed payloads are not supported. |
28+
| Couchbase | All | Bucket or collection names might be unavailable when negotiation completed before OBI started. |
29+
| Memcached | All | Supports the ASCII text protocol subset, excluding `quit` and meta commands. |
30+
| Kafka | All | Topic name lookup might fail for fetch API versions `13+`. |
31+
| MQTT | `3.1.1/5.0` | Payloads are not captured. |
32+
| GraphQL | All | No additional documented version limits. |
33+
| Elasticsearch | `7.14+` | No additional documented version limits. |
34+
| OpenSearch | `3.0.0+` | No additional documented version limits. |
35+
| AWS S3 | All | No additional documented version limits. |
36+
| AWS SQS | All | No additional documented version limits. |
37+
| SQL++ | All | No additional documented version limits. |
38+
| GenAI | OpenAI and Anthropic | No additional documented version limits. |
39+
40+
Some application-level instrumentation also depends on specific runtime,
41+
library, or server versions:
42+
43+
| Area | Supported versions | Notes |
44+
| :---------------- | :--------------------------------------- | :----------------------------------------------------------------------- |
45+
| Go applications | Go `1.17+` | Applies to Go library-level instrumentation. |
46+
| Java applications | JDK `8+` | No additional documented runtime constraints. |
47+
| NGINX | Validated on NGINX `1.27.5` and `1.29.7` | These are the NGINX versions currently covered by documented validation. |
48+
49+
### Go library instrumentation compatibility
50+
51+
OBI supports the following Go libraries and minimum versions for application
52+
instrumentation:
53+
54+
| Library | Supported versions |
55+
| :------------------------------- | :------------------------------ |
56+
| `net/http` | `>= 1.17` |
57+
| `golang.org/x/net/http2` | `>= 0.12.0` |
58+
| `github.com/gorilla/mux` | `>= v1.5.0` |
59+
| `github.com/gin-gonic/gin` | `>= v1.6.0`, `!= v1.7.5` |
60+
| `google.golang.org/grpc` | `>= 1.40` |
61+
| `net/rpc/jsonrpc` | `>= 1.17` |
62+
| `database/sql` | `>= 1.17` |
63+
| `github.com/go-sql-driver/mysql` | `>= v1.5.0` |
64+
| `github.com/lib/pq` | all versions |
65+
| `github.com/redis/go-redis/v9` | `>= v9.0.0` |
66+
| `github.com/segmentio/kafka-go` | `>= v0.4.11` |
67+
| `github.com/IBM/sarama` | `>= 1.37` |
68+
| `go.mongodb.org/mongo-driver` | `v1: >= v1.10.1; v2: >= v2.0.1` |
69+
70+
The versions listed in these tables are the versions OBI explicitly supports.
71+
Other versions might also work, but they are not part of the documented support
72+
scope unless stated otherwise.
73+
74+
### GPU instrumentation compatibility
75+
76+
OBI supports GPU instrumentation when the environment meets the
77+
[OBI compatibility requirements](/docs/zero-code/obi/#compatibility) and the
78+
application uses a supported CUDA runtime library.
79+
80+
| Requirement | Supported |
81+
| :------------------- | :----------------------------- |
82+
| Operating system | Linux |
83+
| CPU architecture | `amd64`, `arm64` |
84+
| CUDA runtime library | `libcudart.so` for CUDA `7.0+` |
85+
86+
OBI instruments the following CUDA operations:
87+
88+
| Operation |
89+
| :----------------- |
90+
| `cudaLaunchKernel` |
91+
| `cudaGraphLaunch` |
92+
| `cudaMalloc` |
93+
| `cudaMemcpy` |
94+
| `cudaMemcpyAsync` |
95+
96+
GPU instrumentation only applies to applications that use the supported CUDA
97+
runtime library and operations listed above. Other GPU APIs, frameworks, or
98+
libraries are outside the documented support scope unless stated otherwise.
99+
14100
## Common metrics configuration
15101

16102
YAML section: `metrics`.

‎content/en/docs/zero-code/obi/distributed-traces.md‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,24 @@ instead its own generated trace context. If OBI cannot find an incoming
2424
`traceparent` context value, it generates one according to the W3C
2525
specification.
2626

27+
## Compatibility
28+
29+
OBI supports distributed tracing and context propagation in the following
30+
configurations:
31+
32+
| Area | Supported versions or environments | Notes |
33+
| :----------------------------------- | :---------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------- |
34+
| 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. |
35+
| Go library-level context propagation | Go `1.18+` | Supports goroutine context propagation up to 3 nested goroutine levels. |
36+
| Node.js async hooks | Node.js `8.0+` | Custom handling of `SIGUSR1` can interfere with context propagation. |
37+
| Ruby Puma | Ruby applications served by Puma `5.0+` | Context propagation support requires the Puma server. |
38+
| Java thread pools | JDK `8+` | No additional documented runtime constraints. |
39+
| Python asyncio | Python `3.9+` with `uvloop` | Context propagation support requires the `uvloop` event loop. |
40+
41+
The versions listed here are the versions OBI explicitly supports for
42+
distributed tracing features. Other versions might also work, but they are not
43+
part of the documented support scope unless stated otherwise.
44+
2745
## Implementation
2846

2947
The trace context propagation is implemented in two different ways:
@@ -70,7 +88,7 @@ disrupt the TCP/IP context propagation, because the original packets are
7088
discarded and replayed downstream. Parsing incoming trace context information
7189
from OpenTelemetry SDK instrumented services still works.
7290
73-
gRPC and HTTP/2 are not supported at the moment.
91+
gRPC and HTTP/2 are not supported at network level.
7492
7593
This type of context propagation works for any programming language and doesn't
7694
require that OBI runs in `privileged` mode or has `CAP_SYS_ADMIN` granted. For

0 commit comments

Comments
 (0)
⚡