Skip to content

formatter: add SPAN_ID access log formatter#43997

Open
bittoby wants to merge 1 commit intoenvoyproxy:mainfrom
bittoby:feat/add-span-id-access-log-formatter
Open

formatter: add SPAN_ID access log formatter#43997
bittoby wants to merge 1 commit intoenvoyproxy:mainfrom
bittoby:feat/add-span-id-access-log-formatter

Conversation

@bittoby
Copy link

@bittoby bittoby commented Mar 18, 2026

Commit Message: formatter: add SPAN_ID access log formatter

Additional Description:
Adds a %SPAN_ID% access log command operator that returns the span ID of the active
(downstream) span for a request. This complements the existing %TRACE_ID% formatter
and enables users to correlate access log entries with specific spans in their distributed
tracing backend.

The implementation mirrors TraceIDFormatter exactly - it calls getSpanId() on the
active span from the formatter context. The getSpanId() method already exists on the
Tracing::Span interface and is implemented by several tracing providers (OpenTelemetry,
Fluentd). Providers that have not yet implemented it (Zipkin, Datadog, SkyWalking, X-Ray)
return an empty string, which the formatter handles gracefully by outputting "-".

The original issue also suggested separate %CLIENT_SPAN_ID% / %SERVER_SPAN_ID%
formatters. However, only the downstream (server) span is accessible in the access log
formatter context - the upstream (client) span lives inside the router and is not plumbed
to the log context. A single %SPAN_ID% is the correct approach given the current
architecture. Exposing the upstream span would require deeper changes and can be tracked
separately if needed.

Risk Level: Low
Testing: Added unit tests covering all three code paths: valid span ID present, no active
span set, and span present but returning empty ID (providers that don't implement it yet).
Docs Changes: Added %SPAN_ID% documentation to
docs/root/configuration/advanced/substitution_formatter.rst, placed directly after the
existing %TRACE_ID% entry.
Release Notes: Added entry to changelogs/current.yaml under the formatter area.
Platform Specific Features: N/A
Fixes #43674

@bittoby bittoby had a problem deploying to external-contributors March 18, 2026 02:41 — with GitHub Actions Error
@repokitteh-read-only
Copy link

Hi @bittoby, welcome and thank you for your contribution.

We will try to review your Pull Request as quickly as possible.

In the meantime, please take a look at the contribution guidelines if you have not done so already.

🐱

Caused by: #43997 was opened by bittoby.

see: more, trace.

Signed-off-by: bittoby <218712309+bittoby@users.noreply.github.com>
@bittoby bittoby force-pushed the feat/add-span-id-access-log-formatter branch from a916459 to c3466dc Compare March 18, 2026 02:42
@bittoby bittoby requested a deployment to external-contributors March 18, 2026 02:42 — with GitHub Actions Waiting
@bittoby
Copy link
Author

bittoby commented Mar 18, 2026

@agrawroh @basvanbeek Could you please review this PR? Welcome to any feedbacks
thank you

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.

access_log: add span id

1 participant