feat(tracing): migrate from OpenTracing/Jaeger to OpenTelemetry by martinconic · Pull Request #5456 · ethersphere/bee

martinconic · 2026-05-11T10:02:45Z

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.

sbackend123

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.

gacevicljubisa

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.

…onfig

…migration # Conflicts: # cmd/bee/cmd/start.go

gacevicljubisa

I have suggested some change, comments are mostly suggestions, not blockers, but overal looks good. It would be great if certificate loading logic is tested and validated.

Also, please edit the PR desc, to match the implementation for tracing-otlp-insecure flag, and add tracing-otlp-ca-file to table.

gacevicljubisa · 2026-05-28T09:43:47Z

-	}
+// httpPropagator carries trace context across HTTP via the W3C TraceContext
+// standard headers (traceparent, tracestate).
+var httpPropagator propagation.TextMapPropagator = propagation.TraceContext{}


maybe move to the top with the other package-level vars

gacevicljubisa · 2026-05-28T09:45:58Z

+	}
+
+	ratio := o.SamplingRatio
+	if ratio < 0 {


mybe to add: if ratio > 1 { ratio = 1 }

gacevicljubisa · 2026-05-28T09:48:10Z

-	if t == nil {
-		t = noopTracer
+// Supported OTLP transport values for Options.Protocol.
+const (


also, move this to the top

gacevicljubisa · 2026-05-28T10:01:50Z


-	headers[p2p.HeaderNameTracingSpanContext] = b.Bytes()
+// AddContextHeader serialises the active span context into the bee p2p header.
+// It is safe to call on a nil receiver.


Delete this claim from all methods, or add the gurd:

if t == nil { t = noopTracer }

because Tracer is exposed and it can be used without constructor.

gacevicljubisa · 2026-05-28T10:06:47Z

+	if parent := FromContext(ctx); parent.IsValid() {
+		ctx = trace.ContextWithSpanContext(ctx, parent)
 	}


FromContext reads using trace.SpanContextFromContext(ctx). Setting it with trace.ContextWithSpanContext(ctx, parent) writes to the same context key value pair.

I think this can be removed?

martinconic added 2 commits May 11, 2026 13:01

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

0d2cf40

fix: linter issues

c99fd5e

martinconic mentioned this pull request May 11, 2026

feat(config): support new bee OTLP tracing flags ethersphere/beekeeper#585

Merged

test: testing with beekeeper changes

d7f3a13

martinconic marked this pull request as ready for review May 11, 2026 15:48

martinconic requested review from acud, akrem-chabchoub, gacevicljubisa, janos and sbackend123 and removed request for gacevicljubisa May 11, 2026 15:49

sbackend123 reviewed May 12, 2026

View reviewed changes

Comment thread .github/workflows/beekeeper.yml Outdated

gacevicljubisa reviewed May 12, 2026

View reviewed changes

Comment thread pkg/tracing/tracing.go Outdated

gacevicljubisa reviewed May 12, 2026

View reviewed changes

Comment thread cmd/bee/cmd/cmd.go

gacevicljubisa reviewed May 12, 2026

View reviewed changes

fix(tracing): address PR review — protocol flag, sampling 0, nested c…

fe49f93

…onfig

martinconic requested review from gacevicljubisa and sbackend123 May 12, 2026 19:13

fix: go mod

1be8864

gacevicljubisa requested changes May 13, 2026

View reviewed changes

Comment thread cmd/bee/cmd/cmd.go Outdated

Comment thread pkg/tracing/tracing.go Outdated

martinconic added 2 commits May 13, 2026 10:21

fix(tracing): require endpoint, secure-by-default TLS, CA bundle flag

b981f5e

test(p2p/libp2p): set dead endpoint for tracer in TestTracing

6701b50

martinconic requested a review from gacevicljubisa May 13, 2026 07:41

martinconic self-assigned this May 13, 2026

martinconic added this to the 2026 milestone May 13, 2026

janos reviewed May 15, 2026

View reviewed changes

Comment thread pkg/tracing/tracing.go Outdated

Comment thread pkg/tracing/tracing.go Outdated

refactor(tracing): unexport package-internal constants

560a77c

martinconic requested a review from janos May 15, 2026 12:36

janos approved these changes May 15, 2026

View reviewed changes

akrem-chabchoub approved these changes May 18, 2026

View reviewed changes

martinconic added 2 commits May 18, 2026 16:01

chore: revert beekeeper to master branch

376e4a8

Merge remote-tracking branch 'origin/master' into feat/opentelemetry-…

9f5c4b9

…migration # Conflicts: # cmd/bee/cmd/start.go

martinconic mentioned this pull request May 27, 2026

feat(config): support new bee OTLP tracing flags ethersphere/beekeeper#595

Closed

gacevicljubisa approved these changes May 28, 2026

View reviewed changes

martinconic mentioned this pull request May 28, 2026

feat(config): support new bee OTLP tracing flags ethersphere/beekeeper#598

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

martinconic commented May 11, 2026 •

edited

Loading

Uh oh!

sbackend123 left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gacevicljubisa left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gacevicljubisa left a comment •

edited

Loading

Uh oh!

gacevicljubisa May 28, 2026

Uh oh!

gacevicljubisa May 28, 2026

Uh oh!

gacevicljubisa May 28, 2026

Uh oh!

gacevicljubisa May 28, 2026

Uh oh!

gacevicljubisa May 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

martinconic commented May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Checklist

Description

⚠️ Breaking change for operators using tracing

Configuration flags

Nested YAML form

Wire-format compatibility

Coordination

Motivation and Context (Optional)

AI Disclosure

Uh oh!

sbackend123 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gacevicljubisa left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gacevicljubisa left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gacevicljubisa May 28, 2026

Choose a reason for hiding this comment

Uh oh!

gacevicljubisa May 28, 2026

Choose a reason for hiding this comment

Uh oh!

gacevicljubisa May 28, 2026

Choose a reason for hiding this comment

Uh oh!

gacevicljubisa May 28, 2026

Choose a reason for hiding this comment

Uh oh!

gacevicljubisa May 28, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

martinconic commented May 11, 2026 •

edited

Loading

gacevicljubisa left a comment •

edited

Loading