Skip to content

feat(tracing): add telemetry span kind #5526

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
gacevicljubisa wants to merge 6 commits into
base: master
Choose a base branch
from
Open

feat(tracing): add telemetry span kind #5526

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
17411ca
fix: add client and server span kind
gacevicljubisa Jul 7, 2026
fde3f97
chore: reorder deps
gacevicljubisa Jul 7, 2026
71c3920
refactor(tracing): namespace span attributes under swarm.*
gacevicljubisa Jul 7, 2026
1361a8a
chore: revert back abi version
gacevicljubisa Jul 7, 2026
14aae27
Merge remote-tracking branch 'origin' into feat/telemetry-span-kind
gacevicljubisa Jul 9, 2026
b8a3179
refactor(tracing): use role-agnostic swarm.peer.address on both span …
gacevicljubisa Jul 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 9 additions & 12 deletions go.mod
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,18 +64,6 @@ require (
resenje.org/web v0.4.3
)

require (
github.com/cenkalti/backoff/v5 v5.0.3 // indirect
github.com/go-logr/logr v1.4.3 // indirect
github.com/go-logr/stdr v1.2.2 // indirect
github.com/grpc-ecosystem/grpc-gateway/v2 v2.28.0 // indirect
go.opentelemetry.io/auto/sdk v1.2.1 // indirect
go.opentelemetry.io/otel/metric v1.43.0 // indirect
go.opentelemetry.io/proto/otlp v1.10.0 // indirect
google.golang.org/genproto/googleapis/api v0.0.0-20260504160031-60b97b32f348 // indirect
google.golang.org/genproto/googleapis/rpc v0.0.0-20260504160031-60b97b32f348 // indirect
)

require (
filippo.io/bigmod v0.1.1-0.20260103110540-f8a47775ebe5 // indirect
filippo.io/keygen v0.0.0-20260114151900-8e2790ea4c5b // indirect
Expand All @@ -88,6 +76,7 @@ require (
github.com/bits-and-blooms/bitset v1.20.0 // indirect
github.com/btcsuite/btcd/chaincfg/chainhash v1.0.1 // indirect
github.com/caddyserver/zerossl v0.1.3 // indirect
github.com/cenkalti/backoff/v5 v5.0.3 // indirect
github.com/cespare/xxhash/v2 v2.3.0 // indirect
github.com/consensys/gnark-crypto v0.18.1 // indirect
github.com/crate-crypto/go-eth-kzg v1.5.0 // indirect
Expand All @@ -103,12 +92,15 @@ require (
github.com/gabriel-vasile/mimetype v1.4.3 // indirect
github.com/go-kit/log v0.2.1 // indirect
github.com/go-logfmt/logfmt v0.6.0 // indirect
github.com/go-logr/logr v1.4.3 // indirect
github.com/go-logr/stdr v1.2.2 // indirect
github.com/go-ole/go-ole v1.3.0 // indirect
github.com/go-playground/locales v0.14.1 // indirect
github.com/go-playground/universal-translator v0.18.1 // indirect
github.com/golang/groupcache v0.0.0-20210331224755-41bb18bfe9da // indirect
github.com/golang/snappy v1.0.0 // indirect
github.com/google/pprof v0.0.0-20250607225305-033d6d78b36a // indirect
github.com/grpc-ecosystem/grpc-gateway/v2 v2.28.0 // indirect
github.com/hashicorp/errwrap v1.1.0 // indirect
github.com/hashicorp/hcl v1.0.0 // indirect
github.com/holiman/uint256 v1.3.2 // indirect
Expand Down Expand Up @@ -188,6 +180,9 @@ require (
github.com/wlynxg/anet v0.0.5 // indirect
github.com/zeebo/blake3 v0.2.4 // indirect
go.opencensus.io v0.24.0 // indirect
go.opentelemetry.io/auto/sdk v1.2.1 // indirect
go.opentelemetry.io/otel/metric v1.43.0 // indirect
go.opentelemetry.io/proto/otlp v1.10.0 // indirect
go.uber.org/dig v1.19.0 // indirect
go.uber.org/fx v1.24.0 // indirect
go.uber.org/mock v0.5.2 // indirect
Expand All @@ -198,6 +193,8 @@ require (
golang.org/x/telemetry v0.0.0-20260409153401-be6f6cb8b1fa // indirect
golang.org/x/text v0.37.0 // indirect
golang.org/x/tools v0.44.0 // indirect
google.golang.org/genproto/googleapis/api v0.0.0-20260504160031-60b97b32f348 // indirect
google.golang.org/genproto/googleapis/rpc v0.0.0-20260504160031-60b97b32f348 // indirect
google.golang.org/protobuf v1.36.11 // indirect
gopkg.in/ini.v1 v1.67.0 // indirect
gopkg.in/yaml.v3 v3.0.1 // indirect
Expand Down
14 changes: 7 additions & 7 deletions pkg/api/bytes.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,10 +70,10 @@
default:
jsonhttp.InternalServerError(w, "cannot get or create tag")
}
tracing.RecordError(span, err, attribute.String("action", "tag.create"))
tracing.RecordError(span, err, attribute.String("swarm.operation.action", "tag.create"))

Check failure on line 73 in pkg/api/bytes.go

View check run for this annotation

SonarQubeCloud / SonarCloud Code Analysis

Define a constant instead of duplicating this literal "swarm.operation.action" 4 times. 


See more on https://sonarcloud.io/project/issues?id=ethersphere_bee&issues=AZ88VGmLvveDBTePzqMr&open=AZ88VGmLvveDBTePzqMr&pullRequest=5526
return
}
span.SetAttributes(attribute.Int64("tag_id", int64(tag)))
span.SetAttributes(attribute.Int64("swarm.tag.id", int64(tag)))
}

defer s.observeUploadSpeed(w, r, time.Now(), "bytes", deferred)
Expand All @@ -97,7 +97,7 @@
default:
jsonhttp.BadRequest(w, nil)
}
tracing.RecordError(span, err, attribute.String("action", "new.StamperPutter"))
tracing.RecordError(span, err, attribute.String("swarm.operation.action", "new.StamperPutter"))
return
}

Expand All @@ -118,7 +118,7 @@
default:
jsonhttp.InternalServerError(ow, "split write all failed")
}
tracing.RecordError(span, err, attribute.String("action", "split.WriteAll"))
tracing.RecordError(span, err, attribute.String("swarm.operation.action", "split.WriteAll"))
return
}

Expand All @@ -142,22 +142,22 @@
return
}
}
span.SetAttributes(attribute.String("root_address", encryptedReference.String()))
span.SetAttributes(attribute.String("swarm.chunk.root_address", encryptedReference.String()))

err = putter.Done(reference)
if err != nil {
logger.Debug("done split failed", "error", err)
logger.Error(nil, "done split failed")
jsonhttp.InternalServerError(ow, "done split failed")
tracing.RecordError(span, err, attribute.String("action", "putter.Done"))
tracing.RecordError(span, err, attribute.String("swarm.operation.action", "putter.Done"))
return
}

if tag != 0 {
w.Header().Set(SwarmTagHeader, fmt.Sprint(tag))
}

span.SetAttributes(attribute.Bool("success", true))
span.SetAttributes(attribute.Bool("swarm.operation.success", true))

w.Header().Set(AccessControlExposeHeaders, SwarmTagHeader)
if headers.Act {
Expand Down
16 changes: 8 additions & 8 deletions pkg/api/bzz.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -104,10 +104,10 @@
default:
jsonhttp.InternalServerError(w, "cannot get or create tag")
}
tracing.RecordError(span, err, attribute.String("action", "tag.create"))
tracing.RecordError(span, err, attribute.String("swarm.operation.action", "tag.create"))

Check failure on line 107 in pkg/api/bzz.go

View check run for this annotation

SonarQubeCloud / SonarCloud Code Analysis

Define a constant instead of duplicating this literal "swarm.operation.action" 4 times. 


See more on https://sonarcloud.io/project/issues?id=ethersphere_bee&issues=AZ88VGjpvveDBTePzqMq&open=AZ88VGjpvveDBTePzqMq&pullRequest=5526
return
}
span.SetAttributes(attribute.Int64("tag_id", int64(tag)))
span.SetAttributes(attribute.Int64("swarm.tag.id", int64(tag)))
}

putter, err := s.newStamperPutter(ctx, putterOptions{
Expand All @@ -129,7 +129,7 @@
default:
jsonhttp.BadRequest(w, nil)
}
tracing.RecordError(span, err, attribute.String("action", "new.StamperPutter"))
tracing.RecordError(span, err, attribute.String("swarm.operation.action", "new.StamperPutter"))
return
}

Expand Down Expand Up @@ -221,7 +221,7 @@
default:
jsonhttp.InternalServerError(w, errFileStore)
}
tracing.RecordError(span, err, attribute.String("action", "file.store"))
tracing.RecordError(span, err, attribute.String("swarm.operation.action", "file.store"))
return
}

Expand Down Expand Up @@ -330,17 +330,17 @@
logger.Debug("done split failed", "reference", manifestReference, "error", err)
logger.Error(nil, "done split failed")
jsonhttp.InternalServerError(w, "done split failed")
tracing.RecordError(span, err, attribute.String("action", "putter.Done"))
tracing.RecordError(span, err, attribute.String("swarm.operation.action", "putter.Done"))
return
}
span.SetAttributes(
attribute.Bool("success", true),
attribute.String("root_address", reference.String()),
attribute.Bool("swarm.operation.success", true),
attribute.String("swarm.chunk.root_address", reference.String()),
)

if tagID != 0 {
w.Header().Set(SwarmTagHeader, fmt.Sprint(tagID))
span.SetAttributes(attribute.Int64("tag_id", int64(tagID)))
span.SetAttributes(attribute.Int64("swarm.tag.id", int64(tagID)))
}
w.Header().Set(ETagHeader, fmt.Sprintf("%q", reference.String()))
w.Header().Set(AccessControlExposeHeaders, SwarmTagHeader)
Expand Down
6 changes: 3 additions & 3 deletions pkg/api/dirs.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -95,7 +95,7 @@ func (s *Service) dirUploadHandler(
default:
jsonhttp.InternalServerError(w, errDirectoryStore)
}
tracing.RecordError(span, err, attribute.String("action", "dir.store"))
tracing.RecordError(span, err, attribute.String("swarm.operation.action", "dir.store"))
return
}

Expand Down Expand Up @@ -125,13 +125,13 @@ func (s *Service) dirUploadHandler(
logger.Debug("store dir failed", "error", err)
logger.Error(nil, "store dir failed")
jsonhttp.InternalServerError(w, errDirectoryStore)
tracing.RecordError(span, err, attribute.String("action", "putter.Done"))
tracing.RecordError(span, err, attribute.String("swarm.operation.action", "putter.Done"))
return
}

if tag != 0 {
w.Header().Set(SwarmTagHeader, fmt.Sprint(tag))
span.SetAttributes(attribute.Bool("success", true))
span.SetAttributes(attribute.Bool("swarm.operation.success", true))
}
w.Header().Set(AccessControlExposeHeaders, SwarmTagHeader)
if act {
Expand Down
9 changes: 5 additions & 4 deletions pkg/pingpong/pingpong.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ import (
"github.com/ethersphere/bee/v2/pkg/swarm"
"github.com/ethersphere/bee/v2/pkg/tracing"
"go.opentelemetry.io/otel/attribute"
"go.opentelemetry.io/otel/trace"
)

// loggerName is the tree path name of the logger for this package.
Expand Down Expand Up @@ -65,8 +66,8 @@ func (s *Service) Protocol() p2p.ProtocolSpec {
}

func (s *Service) Ping(ctx context.Context, address swarm.Address, msgs ...string) (rtt time.Duration, err error) {
span, _, ctx := s.tracer.StartSpanFromContext(ctx, "pingpong-p2p-ping", s.logger)
span.SetAttributes(attribute.String("peer_address", address.String()))
span, _, ctx := s.tracer.StartSpanFromContext(ctx, "pingpong-p2p-ping", s.logger, trace.WithSpanKind(trace.SpanKindClient))
span.SetAttributes(attribute.String("swarm.peer.address", address.String()))
defer span.End()

start := time.Now()
Expand Down Expand Up @@ -105,8 +106,8 @@ func (s *Service) handler(ctx context.Context, p p2p.Peer, stream p2p.Stream) er
w, r := protobuf.NewWriterAndReader(stream)
defer stream.FullClose()

span, _, ctx := s.tracer.StartSpanFromContext(ctx, "pingpong-p2p-handler", s.logger)
span.SetAttributes(attribute.String("peer_address", p.Address.String()))
span, _, ctx := s.tracer.StartSpanFromContext(ctx, "pingpong-p2p-handler", s.logger, trace.WithSpanKind(trace.SpanKindServer))
span.SetAttributes(attribute.String("swarm.peer.address", p.Address.String()))
defer span.End()

var ping pb.Ping
Expand Down
2 changes: 1 addition & 1 deletion pkg/pusher/pusher.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -171,7 +171,7 @@ func (s *Service) chunksWorker(startupStabilizer stabilization.Subscriber) {
s.metrics.ErrorTime.Observe(time.Since(startTime).Seconds())
tracing.RecordError(op.Span, err)
} else {
op.Span.SetAttributes(attribute.Bool("success", true))
op.Span.SetAttributes(attribute.Bool("swarm.operation.success", true))
}

s.metrics.SyncTime.Observe(time.Since(startTime).Seconds())
Expand Down
22 changes: 11 additions & 11 deletions pkg/pushsync/pushsync.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -207,10 +207,10 @@ func (ps *PushSync) handler(ctx context.Context, p p2p.Peer, stream p2p.Stream)
chunk := swarm.NewChunk(swarm.NewAddress(ch.Address), ch.Data)
chunkAddress := chunk.Address()

span, _, ctx := ps.tracer.StartSpanFromContext(ctx, "pushsync-handler", ps.logger, trace.WithAttributes(
attribute.String("address", chunkAddress.String()),
attribute.Int64("tag_id", int64(chunk.TagID())),
attribute.String("sender_address", p.Address.String()),
span, _, ctx := ps.tracer.StartSpanFromContext(ctx, "pushsync-handler", ps.logger, trace.WithSpanKind(trace.SpanKindServer), trace.WithAttributes(
attribute.String("swarm.chunk.address", chunkAddress.String()),
attribute.Int64("swarm.tag.id", int64(chunk.TagID())),
attribute.String("swarm.peer.address", p.Address.String()),
))

var (
Expand All @@ -222,11 +222,11 @@ func (ps *PushSync) handler(ctx context.Context, p p2p.Peer, stream p2p.Stream)
if err != nil {
tracing.RecordError(span, err)
} else {
attrs := []attribute.KeyValue{attribute.Bool("success", true)}
attrs := []attribute.KeyValue{attribute.Bool("swarm.operation.success", true)}
if stored {
attrs = append(attrs,
attribute.Bool("stored", true),
attribute.String("reason", reason),
attribute.Bool("swarm.chunk.stored", true),
attribute.String("swarm.chunk.store_reason", reason),
)
}
span.SetAttributes(attrs...)
Expand Down Expand Up @@ -539,15 +539,15 @@ func (ps *PushSync) push(parentCtx context.Context, resultChan chan<- receiptRes

now := time.Now()

spanInner, _, _ := ps.tracer.FollowSpanFromContext(context.WithoutCancel(parentCtx), "push-chunk-async", ps.logger, trace.WithAttributes(
attribute.String("address", ch.Address().String()),
spanInner, _, _ := ps.tracer.FollowSpanFromContext(context.WithoutCancel(parentCtx), "push-chunk-async", ps.logger, trace.WithSpanKind(trace.SpanKindClient), trace.WithAttributes(
attribute.String("swarm.chunk.address", ch.Address().String()),
))

defer func() {
if err != nil {
tracing.RecordError(spanInner, err)
} else {
spanInner.SetAttributes(attribute.Bool("success", true))
spanInner.SetAttributes(attribute.Bool("swarm.operation.success", true))
}
spanInner.End()
select {
Expand All @@ -558,7 +558,7 @@ func (ps *PushSync) push(parentCtx context.Context, resultChan chan<- receiptRes

defer action.Cleanup()

spanInner.SetAttributes(attribute.String("peer_address", peer.String()))
spanInner.SetAttributes(attribute.String("swarm.peer.address", peer.String()))

@martinconic martinconic Jul 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

The server handler tags the remote as swarm.peer.sender_address while here the client tags the remote peer as the generic swarm.peer.address. Should we have here something like swarm.peer.target_address ?

@gacevicljubisa gacevicljubisa Jul 9, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Good catch on asymmetry. And after some digging, my opinion is that it would be better to drop the role, and use added span kind we just introduced. That way on the client push span, the peer is the destination, and on the server handler span, the peer is the source. This way, spans are role agnostic. What do you think?


receipt, err = ps.pushChunkToPeer(tracing.WithContext(ctx, spanInner.SpanContext()), peer, ch)
if err != nil {
Expand Down
14 changes: 7 additions & 7 deletions pkg/retrieval/retrieval.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -258,8 +258,8 @@ func (s *Service) RetrieveChunk(ctx context.Context, chunkAddr, sourcePeerAddr s
inflight++

go func() {
span, _, ctx := s.tracer.FollowSpanFromContext(spanCtx, "retrieve-chunk", s.logger, trace.WithAttributes(
attribute.String("address", chunkAddr.String()),
span, _, ctx := s.tracer.FollowSpanFromContext(spanCtx, "retrieve-chunk", s.logger, trace.WithSpanKind(trace.SpanKindClient), trace.WithAttributes(
attribute.String("swarm.chunk.address", chunkAddr.String()),
))
defer span.End()
s.retrieveChunk(ctx, quit, chunkAddr, peer, resultC, action, span)
Expand Down Expand Up @@ -309,7 +309,7 @@ func (s *Service) retrieveChunk(ctx context.Context, quit chan struct{}, chunkAd
tracing.RecordError(span, err)
s.metrics.TotalErrors.Inc()
} else {
span.SetAttributes(attribute.Bool("success", true))
span.SetAttributes(attribute.Bool("swarm.operation.success", true))
}
select {
case result <- retrievalResult{err: err, chunk: chunk, peer: peer}:
Expand Down Expand Up @@ -450,16 +450,16 @@ func (s *Service) handler(p2pctx context.Context, p p2p.Peer, stream p2p.Stream)

var forwarded bool

span, _, ctx := s.tracer.StartSpanFromContext(ctx, "handle-retrieve-chunk", s.logger, trace.WithAttributes(
attribute.String("address", addr.String()),
span, _, ctx := s.tracer.StartSpanFromContext(ctx, "handle-retrieve-chunk", s.logger, trace.WithSpanKind(trace.SpanKindServer), trace.WithAttributes(
attribute.String("swarm.chunk.address", addr.String()),
))
defer func() {
if err != nil {
tracing.RecordError(span, err)
} else {
span.SetAttributes(attribute.Bool("success", true))
span.SetAttributes(attribute.Bool("swarm.operation.success", true))
}
span.SetAttributes(attribute.Bool("forwarded", forwarded))
span.SetAttributes(attribute.Bool("swarm.chunk.forwarded", forwarded))
span.End()
}()

Expand Down
6 changes: 3 additions & 3 deletions pkg/storer/netstore.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ func (db *DB) DirectUpload() PutterSession {
defer func() { <-db.directUploadLimiter }()

span, logger, ctx := db.tracer.FollowSpanFromContext(ctx, "put-direct-upload", db.logger)
span.SetAttributes(attribute.String("address", ch.Address().String()))
span.SetAttributes(attribute.String("swarm.chunk.address", ch.Address().String()))
defer func() {
if err != nil {
tracing.RecordError(span, err)
Expand Down Expand Up @@ -84,12 +84,12 @@ func (db *DB) Download(cache bool) storage.Getter {
return getterWithMetrics{
storage.GetterFunc(func(ctx context.Context, address swarm.Address) (ch swarm.Chunk, err error) {
span, logger, ctx := db.tracer.StartSpanFromContext(ctx, "get-chunk", db.logger)
span.SetAttributes(attribute.String("address", address.String()))
span.SetAttributes(attribute.String("swarm.chunk.address", address.String()))
defer func() {
if err != nil {
tracing.RecordError(span, err)
} else {
span.SetAttributes(attribute.Bool("success", true))
span.SetAttributes(attribute.Bool("swarm.operation.success", true))
}
span.End()
}()
Expand Down
Loading