Overview
OpenTelemetry eBPF Instrumentation (OBI) v1.0.0 is the project's first stable core release. OBI collects OpenTelemetry traces and metrics from Linux applications using eBPF, without requiring application source changes. It provides visibility into application requests, dependencies, and network activity, with Linux amd64 and arm64 binary archives and container images.
The 1.0 milestone establishes a compatibility baseline for configuration, documented deployment interfaces, supported environments, and telemetry explicitly classified as stable. Users can plan upgrades within the v1 release line against those defined guarantees and the limitations below.
For deployment, follow the standalone installation guide or container installation guide, check the support matrix, and pin deployments to v1.0.0.
This release promotes the instrumentation validated in v1.0.0-rc.2, including the functionality and fixes shipped in v0.15.2, and establishes the compatibility contract tracked in the stable OBI 1.0 milestone.
The v1 compatibility contract
Starting with v1.0.0, the following surfaces receive the compatibility guarantees agreed in the stable OBI 1.0 milestone and release PR:
- Config v2, its generated schema, and the supported subset of OpenTelemetry declarative configuration.
- Documented CLI flags, environment variables, release binaries, and container image behavior.
- Telemetry entries classified as
stable, including their OTLP and built-in Prometheus representations, as defined in TELEMETRY.md. - Supported environments, upgrades, and deprecation rules documented in the support matrix and v1 versioning policy.
For these stable surfaces, minor releases may add backward-compatible functionality, patches preserve compatibility, and incompatible changes require a new major version. The detailed rules are in the v1 versioning policy.
Go library consumers: the public Go API of the root go.opentelemetry.io/obi module is outside the stable surfaces declared for this milestone. Its v1.0.0 module tag does not extend the guarantees above to every exported Go package or symbol. The Collector receiver continues on its separate v0 release line; see the explicit version-selection command below.
Policy documentation: the tagged README, VERSIONING.md, and support matrix retain introductory wording from the pre-v1 Development phase. For v1.0.0, the stable-surface declaration above and the policy's after-v1 compatibility rules apply to the listed surfaces. The release epic records the policy-wording follow-up.
Signal and attribute stability classifications apply independently. Telemetry classified as development, alpha, beta, or release candidate remains outside the stable contract. Network flow attribute names remain excluded pending semantic-convention alignment.
Highlights and changes since RC2
- Carries forward manual span capture through the embedded Go Auto SDK, expanded .NET route harvesting and CPU/heap metrics, and AWS Route53 endpoint name resolution.
- Includes the BPF verifier, trace-context injection, metric-label collision, duplicate
target.info, and Collector receiver lifecycle fixes described in the v0.15.2 notes. - Compared with RC2, updates the release version and module dependencies and publishes the
1.0.0telemetry schema. Release preparation also backports schema-lint and bpftool setup fixes for current Ubuntu runners, a MongoDB CI fixture pin, and the Docker Hub ECS mock reference. These are release/CI changes; the instrumentation is promoted from RC2. (#3972, #3940, #3810, #3792)
Configuration and upgrade guidance
Config v2 is the v1 configuration contract. Standalone loading, the validation/migration CLI, and Collector receiver support have been available since v0.11.0. Config v1 remains supported for backward compatibility, but is frozen and receives no bug fixes or new features.
Follow the Config v1 to v2 migration guide and supported Config v2 reference. Review unsupported mappings and manual migration cases, explicitly wire environment overrides into v2, and compare a canary before rollout. Full per-process declarative configuration parity remains deferred; see the Config v2 release gate.
The Collector receiver remains the separate module go.opentelemetry.io/obi/collector on its independent v0 release line. This release tags only core v1.0.0; receiver users should use collector/v0.15.2. To use that receiver with the stable core, select both versions explicitly:
go get go.opentelemetry.io/obi/collector@v0.15.2 go.opentelemetry.io/obi@v1.0.0Users upgrading from RC1 or versions before v0.15.2 should review the v0.15.2 release-impacting changes before upgrading dashboards, alerts, or processors. Those changes include span names and rpc.method values, default metric attributes and Prometheus labels, and the removal of PrometheusConfig.Registry. In Config v2, a protocol's enabled.metrics: false also suppresses its span metrics and service graphs in both exporters.
Telemetry schema
The emitted schema URL advances from 0.15.2 to the published 1.0.0 schema. The schema preserves the existing transformation history; this release preparation introduces no additional rename transformations. Schema transformations cannot translate every conditional rename, removal, or Prometheus-specific change.
Known operational limitations
These documented issues remain in v1.0.0 and should be considered when planning a rollout:
- Missing application metrics after Pod startup or restart: application metrics can intermittently remain absent until OBI restarts. Restarting OBI is the documented recovery observed for this symptom; the root cause has not been confirmed. Check metric emission after workload restarts during a canary.
- Span timestamp ordering: child spans can intermittently start before their parents, including in same-node traces. The cause remains unknown, and no workaround is documented. Account for this limitation when interpreting trace timing.
- Service identity and service graphs: port-based discovery can select a helper or port-forwarder instead of the workload. Use executable-path, container, or Kubernetes selectors when multiple processes expose the same port. Service graphs can also show
outgoingdestinations or separate Kubernetes and OpenTelemetry identities when metadata is unavailable or cannot be mapped. When combining Prometheus service-graph series from multiple OBI instances, preserve the scrape target'sinstancelabel or an equivalent external label.
See the known telemetry emission limitations and protocol/runtime support matrix for the full conditions and limitations. Stability protects the documented shape and meaning of telemetry when emitted; enabled features, protocol support, and available runtime metadata still determine which signals and attributes appear. Full telemetry-registry coverage and full declarative configuration parity remain follow-up work.
Artifacts and known SBOM limitations
Linux amd64 and arm64 binary archives include obi, LICENSE, NOTICE, and third-party notices. The source-generated archive includes the tagged source, generated BPF bindings/objects, and the embedded Java agent JAR. Archives, CycloneDX SBOMs, and SHA256SUMS each have a Cosign signature bundle. Verify them and the main container images from the tagged repository:
./scripts/verify-draft-release.sh v1.0.0Both binary SBOMs identify the OBI module as v1.0.0. The archive SBOMs still report the embedded Java agent's version as UNKNOWN and omit its Byte Buddy dependencies. For Java dependency analysis, also consume obi-java-agent-v1.0.0.cyclonedx.json and its signature bundle. That companion SBOM identifies the agent as v1.0.0 and lists byte-buddy and byte-buddy-agent at 1.18.14-jdk5.
Signature verification establishes authenticity and integrity; consumers requiring a complete Java dependency inventory must also use the companion SBOM.
What's Changed
General
Dependencies
- Update grafana/otel-lgtm Docker tag to v0.37.0 by @renovate[bot] in #3776
- Update dependency laravel/framework to v13.37.0 by @renovate[bot] in #3772
- Update nginx:1.31.7-alpine Docker digest to 892bb21 by @renovate[bot] in #3766
Full Changelog: v0.15.2...v1.0.0