Skip to content

feat(tracing): migrate from OpenTracing/Jaeger to OpenTelemetry#5456

Open
martinconic wants to merge 7 commits into
masterfrom
feat/opentelemetry-migration
Open

feat(tracing): migrate from OpenTracing/Jaeger to OpenTelemetry#5456
martinconic wants to merge 7 commits into
masterfrom
feat/opentelemetry-migration

Conversation

@martinconic
Copy link
Copy Markdown
Contributor

@martinconic martinconic commented May 11, 2026

Checklist

  • I have read the coding guide.
  • My change requires a documentation update, and I have done it.
  • I have added tests to cover my changes.
  • I have filled out the description and linked the related issues.

Description

Migrates bee's tracing stack from the archived OpenTracing API and
deprecated jaeger-client-go to the OpenTelemetry Go SDK with an
OTLP exporter. The wrapper at pkg/tracing keeps a familiar API
shape so the call-site sweep is bounded to ~8 production files plus
the test suite.

Closes #5010.

⚠️ Breaking change for operators using tracing

The Jaeger UDP agent on port :6831 is no longer the receiver. Operators
must run an OTLP-capable collector (Jaeger v2, OpenTelemetry Collector, or any
backend with an OTLP receiver) and point bee at it. Upgrading a node with the
old config keys will fail startup with an unknown parameters error.

Configuration flags

Removed:

  • tracing-endpoint (replaced by tracing-otlp-endpoint)
  • tracing-host / tracing-port (folded into tracing-otlp-endpoint)

Added:

Flag Default Meaning
tracing-otlp-endpoint 127.0.0.1:4318 OTLP collector address host:port (default port is 4318 for http, 4317 for grpc)
tracing-otlp-insecure true Disable TLS for the OTLP exporter (suitable for a local collector)
tracing-otlp-protocol http OTLP transport: http or grpc
tracing-sampling-ratio 1.0 Head-based sampling ratio in [0, 1]; 0 samples nothing, 1 samples everything

Unchanged: tracing-enable, tracing-service-name.

Nested YAML form

Tracing keys now also accept the nested form (mirroring blockchain-rpc.*):

tracing:
  enable: true
  otlp-endpoint: 127.0.0.1:4318
  otlp-insecure: true
  otlp-protocol: http
  sampling-ratio: 1.0
  service-name: bee

Flat tracing-* keys still work; if both are present in the same config file,
the nested form wins and a warning is logged.

Wire-format compatibility

Spans propagated across libp2p streams use a new versioned binary carrier, and
the standard W3C traceparent header is used over HTTP. Mixed-version peers
will start fresh traces at the boundary rather than continuing the old Jaeger
binary format.

Coordination

Requires a paired beekeeper update — the workflow at
.github/workflows/beekeeper.yml temporarily points at
BEEKEEPER_BRANCH: feat/bee-otlp-tracing-config and must be flipped back to
master before merging this PR (and after the beekeeper PR lands).

Motivation and Context (Optional)

OpenTracing is archived and jaeger-client-go is deprecated; OpenTelemetry is
the supported successor. Migrating now lets bee plug into any OTLP-capable
backend (Jaeger v2, OTel Collector, vendor agents) and unlocks adopting
semconv and tail-sampling at the collector layer in follow-up work.

AI Disclosure

  • This PR contains code that has been generated by an LLM.
  • I have reviewed the AI generated code thoroughly.
  • I possess the technical expertise to responsibly review the code generated in this PR.

@martinconic martinconic marked this pull request as ready for review May 11, 2026 15:48
@martinconic martinconic requested review from acud, akrem-chabchoub, gacevicljubisa, janos and sbackend123 and removed request for gacevicljubisa May 11, 2026 15:49
Copy link
Copy Markdown
Contributor

@sbackend123 sbackend123 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would explicitly call out in the PR description and in the docs which configuration flags were added / removed and that the tracing endpoint semantics changed. Without that, anyone still on the old configuration may be caught off guard.

Comment thread .github/workflows/beekeeper.yml
Comment thread pkg/tracing/tracing.go Outdated
Comment thread cmd/bee/cmd/cmd.go
Copy link
Copy Markdown
Member

@gacevicljubisa gacevicljubisa left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would explicitly call out in the PR description and in the docs which configuration flags were added / removed and that the tracing endpoint semantics changed. Without that, anyone still on the old configuration may be caught off guard.

Yes, I agree. Updating the node with old config will result with "unknown flag" error.
Also, this is breaking change for the tracing for the node operators who are using tracing, they will need to switch to OTLP receiver, instead of jaeger UDP agent.

Additionally, OTel has a second exporter, otlptracegrpc. It might be worth to expose a tracing-otlp-protocol: http|grpc flag (defaulting to http), so operators can choose.

Comment thread cmd/bee/cmd/cmd.go Outdated
Comment thread pkg/tracing/tracing.go Outdated
@martinconic martinconic self-assigned this May 13, 2026
@martinconic martinconic added this to the 2026 milestone May 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: use of opentracing spans and jaeger with bee

3 participants