> ## Documentation Index
> Fetch the complete documentation index at: https://docs.odigos.io/llms.txt
> Use this file to discover all available pages before exploring further.
# OpenTelemetry eBPF Instrumentation (OBI)
> OBI is OpenTelemetry’s eBPF-based auto-instrumentation.
Odigos can run **[OpenTelemetry eBPF Instrumentation (OBI)](https://opentelemetry.io/docs/zero-code/obi)** for workloads where the `opentelemetry-ebpf-instrumentation` distro is selected or a Metrics `InstrumentationRule` is configured.
Upstream concepts, requirements, and capabilities.
Source, releases, and issues.
## Traces
OBI tracing can be enabled by selecting it as a container override for specific workloads. This can be configured either
from the Odigos UI or directly on a [Source object](/oss/pipeline/sources/introduction).
### Enabling OBI from the UI
Select the source you want to instrument. In the source drawer, click the edit (pencil) icon next to the
detected container.
In the **Otel Distro Name** drop-down, choose **`opentelemetry-ebpf-instrumentation`** and click the check
mark to save.
After refreshing, the detected container should report that it is instrumented with
`opentelemetry-ebpf-instrumentation`.
To remove OBI instrumentation, open the runtime override config again and click the delete (trash) icon
next to the **Otel Distro Name** field.
By default, OBI does not need to restart your containers to begin instrumenting them. Because of this,
choosing OBI as your container override will not trigger a pod restart. In some cases, however, your
specific application may still require a pod restart (for example, when switching from a pre-existing
instrumentation to OBI or vice-versa). You can trigger a pod restart using the **Restart** button in the
source drawer.
### Enabling OBI from a Source object
If editing a [Source object](/oss/pipeline/sources/introduction) directly, OBI is enabled through the
`containerOverrides` field. For example:
```yaml theme={null}
apiVersion: odigos.io/v1alpha1
kind: Source
metadata:
name: my-workload
namespace: default
spec:
workload:
kind: DaemonSet
name: sample-app
namespace: default
containerOverrides:
- containerName: foo
otelDistroName: opentelemetry-ebpf-instrumentation
```
In this case, `containerName` is the name of the container to instrument in this workload, and the required
`otelDistroName` is **`opentelemetry-ebpf-instrumentation`**.
### Trace support
When OBI is the selected distro, odiglet attaches the process to OBI's trace selector when instrumentation loads and
removes it when instrumentation stops. OBI captures distributed traces for supported protocols (HTTP, gRPC, databases,
messaging, and more) without code changes. DNS lookup traces are enabled by default when using the OBI distro.
Learn more in the upstream docs:
Context propagation, compatibility, and Kubernetes requirements.
Protocol, database, messaging, and Go library instrumentation coverage.
Odigos configures OBI header-based context propagation (`context_propagation: headers`). For encrypted traffic and
multi-service propagation limits, see the upstream distributed tracing guide linked above.
### Limitations
OBI's instrumentation is based on HTTP header propagation. For encrypted traffic, context propagation will not work unless both
workloads (client and server) are instrumented with OBI as explained in [the official OBI docs](https://opentelemetry.io/docs/zero-code/obi/distributed-traces/#context-propagation-at-network-level).
## Metrics
Upstream OBI is split into several observability pipelines. In Odigos, each signal is wired independently so
traces and metrics can be enabled without requiring the same distro or lifecycle on every process.
| Signal | OBI pipeline | Enabled in Odigos when | Applies to |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| **Traces** | [AppO11y](https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation/tree/main/pkg/appolly) (application protocol tracing) | The `opentelemetry-ebpf-instrumentation` distro is selected for the container. DNS lookup traces are included by default for the OBI distro | Processes instrumented with the OBI distro only |
| **Network metrics** | [NetO11y](https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation/tree/main/pkg/netolly) (point-to-point flow bytes) and [StatsO11y](https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation/tree/main/pkg/statsolly) (TCP statistics such as RTT and failed connections) | An [InstrumentationRule](/oss/pipeline/rules/introduction) with `networkMetrics` set (optionally scoped via `scopes`) | Any process, regardless of language or distro (Go, Java, OBI, etc.) |
All OBI telemetry that Odigos collects is exported over OTLP to the odiglet node collector (`localhost:4317`), then
follows the same Odigos pipeline as other workload telemetry.
For consistency and discoverability alongside other Odigos telemetry, the node collector rewrites the
`obi` prefix of OBI metric names to `odigos`. Metrics named `obi.*` are exported as `odigos.*` (and the
Prometheus form `obi_*` as `odigos_*`). For example, `obi.network.flow.bytes` is exported as
`odigos.network.flow.bytes`. Metric names referenced in the OBI documentation below use the `obi`
prefix; account for this rename when building dashboards or queries.
OBI does not need to be selected as the traces distro for an app to use OBI metrics, see below.
### Configuration
**Network metrics infrastructure (cluster-wide):** OBI network flow collection requires odiglet `hostNetwork`. Enable the
infrastructure in Helm by setting `metricsSources.networkMetrics.enabled` to `true` (it defaults to disabled):
```yaml theme={null}
metricsSources:
networkMetrics:
enabled: true
```
**Enabling network metrics:** Create an `InstrumentationRule` in the Odigos installation namespace (typically
`odigos-system`) with a `networkMetrics` block. See [Network Metrics](/oss/pipeline/rules/networkmetrics) for configuration options,
examples, and verification steps.
Multiple rules merge with OR semantics (if any rule enables a signal, it is enabled). Workload scoping via `scopes` is
optional — omit it to apply cluster-wide.
### Network metrics
Network metrics describe bytes sent and received between endpoints (pods, services, nodes, and related Kubernetes
metadata), along with TCP-level statistics such as round-trip time and failed connection attempts. Enable cluster
infrastructure with `metricsSources.networkMetrics.enabled: true`, then enable collection with an
InstrumentationRule `networkMetrics` block (cluster-wide or scoped via `scopes`).
Network metrics are collected per process. In environments where a workload runs many processes,
enabling network metrics can significantly increase the number of emitted metric series and the
overall cardinality of your metrics. Monitor your metrics cardinality after enabling network metrics,
and scope the rule via `scopes` to limit it to the workloads that need it.
Flow and inter-zone metric families, attributes, and aggregation behavior.
OpenTelemetry and Prometheus names for `obi.network.flow.bytes` and related series.
### Stats metrics
Stats metrics (`obi.stat.tcp.rtt`, `obi.stat.tcp.failed.connections`, and related series) are collected together with network flow metrics when the Network Metrics rule is enabled.
Metric names and attributes for `obi.stat.tcp.rtt`, `obi.stat.tcp.failed.connections`, and related series.
How OBI groups metrics into `network`, `stats`, `stats_tcp_rtt`, and related feature flags.
Network flow and TCP stats metrics export interval defaults to 60 seconds.