Proposal: Support upstream trace headers as request ID

[captainp1an3t]

Is your feature request related to a problem? Please describe.

When Athens runs behind a service mesh (Istio, Linkerd) or API gateway, there's no way to correlate Athens logs with distributed traces.

The service mesh injects trace headers (x-b3-traceid, traceparent) into incoming requests, but Athens ignores them and generates its own Athens-Request-ID. This results in:

• Logs showing request-id: xyz789
• Traces showing traceId: abc123
• No way to correlate a log entry with its corresponding trace span

For teams running Athens in Kubernetes with Istio/Envoy, debugging request flows across observability tools (logs in Splunk + traces in Jaeger/SignalFx) requires manual timestamp/path matching instead of a simple ID lookup.

Before (Current Behavior)

sequenceDiagram
    participant Client
    participant Istio as Istio Sidecar
    participant Athens
    participant Logs as Log Backend
    participant APM as APM/Traces

    Client->>Istio: GET /module@v1.0.0
    Note over Istio: Generates x-b3-traceid: abc123
    Istio->>Athens: Forward with trace headers
    Note over Athens: Ignores trace headers<br/>Generates own ID: xyz789
    Athens->>Logs: Log {request-id: xyz789}
    Athens->>APM: Span {traceId: abc123}
    
    Note over Logs,APM: ❌ No correlation!<br/>xyz789 ≠ abc123

Loading

After (With This Feature)

sequenceDiagram
    participant Client
    participant Istio as Istio Sidecar
    participant Athens
    participant Logs as Log Backend
    participant APM as APM/Traces

    Client->>Istio: GET /module@v1.0.0
    Note over Istio: Generates x-b3-traceid: abc123
    Istio->>Athens: Forward with trace headers
    Note over Athens: ATHENS_REQUEST_ID_SOURCE=b3<br/>Uses abc123 as request-id
    Athens->>Logs: Log {request-id: abc123}
    Athens->>APM: Span {traceId: abc123}
    
    Note over Logs,APM: ✅ Same ID everywhere!<br/>Search abc123 → find all

Loading

Describe the solution you'd like

Add a configuration option ATHENS_REQUEST_ID_SOURCE (or RequestIDSource in config.toml) that allows Athens to adopt an upstream correlation ID from incoming trace headers.

Supported values:

Value	Header	Description
athens	Athens-Request-ID	Current behavior (default)
b3	x-b3-traceid	Zipkin/Istio B3 propagation
x-request-id	x-request-id	Envoy-generated request ID
w3c	traceparent	W3C Trace Context (extracts trace-id portion)
auto	All of the above	Tries each in order, falls back to Athens header, then UUID

Default behavior remains unchanged — existing deployments continue working without modification.

Describe alternatives you've considered

1. Use Istio sidecar access logs — These contain trace headers, but correlating with Athens application logs still requires manual timestamp matching.

2. OTEL Collector log enrichment — The collector can add static labels but can't inject the correct trace ID since it doesn't know which trace a log line belongs to at collection time.

3. Correlate by pod + timestamp — Works but is error-prone and tedious for debugging.

4. Log both request-id and trace-id separately — Keep the existing Athens-generated request ID but add a separate trace-id field to logs extracted from incoming headers. This preserves semantic separation (request ID = Athens-scoped, trace ID = distributed trace-scoped) but adds complexity. For Athens' simple proxy use case where one incoming request = one response, the distinction provides little value. If Athens ever gained async operations or request fan-out, separate IDs might make sense, but this can be added later if needed.

None of these provide the simple "search by ID" workflow that adopting the upstream trace ID would enable.

Additional context

I have a working implementation with tests that I'm happy to contribute as a PR. The changes are minimal:

• Add Source type and header constants to pkg/requestid
• Modify WithRequestID middleware to accept a source parameter
• Add RequestIDSource field to config (defaults to "athens")

This is fully backwards compatible — the new behavior is opt-in via configuration.

Before I submitted, I just wanted to get a sense of whether or not it would be something the community would want and confirm I'm not lacking any other context for the original intention of adding request id in the first place.

From what I see, this was the original proposal

[captainp1an3t]

Opened #2124 for review. Happy to discuss.