v9 (current) v8
Edit Page

Auditing RESTHeart

Distributed Tracing Headers Support

RESTHeart supports distributed tracing integration with systems like Zipkin, Jaeger, and other OpenTelemetry-compatible platforms. This feature automatically captures and displays configured tracing headers in request logs, making it easy to correlate requests across distributed systems.

This implements issues #287 and #587.

How It Works

RESTHeart automatically:

  • Captures incoming tracing headers from HTTP requests

  • Displays them in the request logs for easy correlation

  • Echoes all captured headers back in HTTP responses

  • Generates fallback trace IDs when no headers are present

  • Makes headers available in SLF4J MDC for custom logging configurations

This implementation makes it possible to correlate logged exceptions with the corresponding request log, even when the thread handling the message is re-used shortly after. It handles all headers mentioned in b3-propagation, as well as headers used by Jaeger and OpenTelemetry.

Configuration

To enable tracing headers in your logs, configure the tracing-headers option in restheart.yml:

logging:
  tracing-headers:
    - x-b3-traceid      # Zipkin headers, see https://github.com/openzipkin/b3-propagation
    - x-b3-spanid
    - x-b3-parentspanid
    - x-b3-sampled
    - uber-trace-id     # Jaeger header, see https://www.jaegertracing.io/docs/client-libraries/#trace-span-identity
    - traceparent       # OpenCensus/W3C headers, see https://github.com/w3c/distributed-tracing
    - tracestate
    - x-request-id      # Custom request ID header
Note
 The first configured header found in an incoming request becomes the primary trace ID displayed in logs.

Log Output Examples

When tracing headers are present in requests:

[x-b3-traceid: 7f8a3d2c, x-request-id: abc123] ⚬ GET http://localhost:8080/ping => status=200 elapsed=56ms

When no headers are present (fallback behavior):

[trace-id: 0001] ⚬ GET http://localhost:8080/ping => status=200 elapsed=56ms

Performance

The implementation is optimized for production use with:

  • Cached HttpString instances for efficient header lookups

  • Fast paths for requests without tracing headers

  • Minimal memory allocation patterns

Warning
 For development purposes only, use requests-log-level: 2 cautiously as it logs sensitive information including Authorization and Auth-Token headers.