Skip to content

Add baggage tag fields to spans with OpenTelemetry and document gRPC baggage propagation - #51597

Open
o-shevchenko wants to merge 1 commit into
spring-projects:mainfrom
o-shevchenko:gh-49832
Open

Add baggage tag fields to spans with OpenTelemetry and document gRPC baggage propagation#51597
o-shevchenko wants to merge 1 commit into
spring-projects:mainfrom
o-shevchenko:gh-49832

Conversation

@o-shevchenko

@o-shevchenko o-shevchenko commented Sep 6, 2026

Copy link
Copy Markdown

This PR replaces the original proposal (auto-configured gRPC baggage interceptors). While porting it from spring-projects/spring-grpc#369 I verified the behaviour end-to-end on main and on 4.1.1, and it turned out that Spring Boot already propagates baggage over gRPC out of the box — see the details below. What remained is a tagging gap that is not gRPC-specific, plus missing documentation. Related to #49832.

What already works (no code change needed)

With spring.grpc.{server,client}.observation.enabled (default) and Micrometer Tracing configured, ObservationGrpcServerInterceptor / ObservationGrpcClientInterceptor hand the gRPC metadata to PropagatingReceiver/SenderTracingObservationHandler, which run the same Propagator chain as HTTP. A probe with the in-process transport, the OTel SDK and W3C propagation showed, for both main and 4.1.1:

  • server: the W3C baggage header and the individual management.tracing.baggage.remote-fields keys are extracted and visible via Tracer#getBaggage inside unary and server-streaming methods, no leaks between calls
  • client: current baggage is written as baggage header and as individual remote-field keys, plus traceparent

The only prerequisite is micrometer-core on the classpath (the interceptors live there); without it, gRPC gets no observation and therefore no propagation, silently.

What did not work: tag fields

management.tracing.baggage.tag-fields were not applied to the span of an incoming request unless the application itself called tracer.getBaggage(...). That is micrometer-metrics/tracing#933 — the OTel bridge builds the span's parent Context from Context.current() and drops the extracted baggage, so SpanProcessor#onStart never sees it. I've proposed a fix for the bridge in micrometer-metrics/tracing#1548.

Changes in this PR

  • OpenTelemetryPropagationConfigurations: register Micrometer's BaggageTaggingSpanProcessor when baggage is enabled and at least one tag field is configured (@ConditionalOnMissingBean, so a custom bean backs off). Today this tags spans that start while baggage is current (client and internal spans); together with the bridge fix it also covers server spans of incoming requests.
  • gRPC reference docs: new server "Observability" section and an extended client one describing that trace context and baggage (W3C header + remote fields) are propagated by the auto-configured observation interceptors, the micrometer-core prerequisite, and the spring.grpc.*.observation.enabled switches.
  • Tracing reference docs: mention tag-fields and gRPC in the Baggage section.
  • Tests for the new bean (conditions, back-off, and a functional check that a span started with baggage in scope is tagged).

With OpenTelemetry, fields listed in management.tracing.baggage.tag-fields
only became span tags when the application itself touched the baggage
through the Tracer API. Baggage that arrived with a request was
propagated correctly, but spans were not tagged with it (see
micrometer-metrics/tracing#933).

This commit registers Micrometer Tracing's BaggageTaggingSpanProcessor
whenever baggage is enabled and at least one tag field is configured, so
that spans are tagged with the baggage that is present in their parent
context. A custom BaggageTaggingSpanProcessor bean backs off the
auto-configured one.

The gRPC reference documentation now describes that trace context and
baggage are propagated over gRPC metadata by the auto-configured
Micrometer observation interceptors, including the W3C baggage header
and the individual metadata keys listed in
management.tracing.baggage.remote-fields, and that this requires
micrometer-core on the classpath. The baggage section of the tracing
documentation now mentions tag fields and gRPC.

See spring-projectsgh-49832

Signed-off-by: Oleksandr Shevchenko <oleksandr.shevchenko@datarobot.com>
@o-shevchenko o-shevchenko changed the title Add auto-configuration for baggage propagation over gRPC Add baggage tag fields to spans with OpenTelemetry and document gRPC baggage propagation Sep 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

status: waiting-for-triage An issue we've not yet triaged

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants