eSignet-Thunder: Add Trace ID Support in Logs and Outbound Requests

[rachik-hue]

Observability Header Propagation

Summary

Add trace context propagation to esignet-service so that every inbound request is assigned a trace ID and every outbound HTTP call to downstream services (MOSIP IDA, Sunbird Registry, JWKS endpoint) carries the same trace headers. MOSIP uses B3 headers for distributed tracing; this feature ensures esignet participates in that trace chain.

Reference implementations: thunder (Go HTTP middleware pattern). Use these as the source of truth for how trace context is extracted from inbound requests and forwarded on outbound calls.

---

Goals

• Extract B3 trace headers from every inbound HTTP request and make them available for the duration of that request.
• Generate a new trace ID when none is present in the inbound request.
• Forward B3 headers on every outbound HTTP call made by esignet to downstream services.
• Use OpenTelemetry for B3 propagation so the logic is standards-compliant.

---

Non-Goals

• Sending traces to a collector (Jaeger, Zipkin, OTLP) — propagation only, no exporter.
• Creating OpenTelemetry spans or metrics.
• Changing the access log middleware (traceId in access logs is covered in access-log-middleware.md).
• Propagating W3C traceparent headers — MOSIP ecosystem uses B3 exclusively.
• Header propagation for non-HTTP transports (gRPC, message queues).

---

Acceptance Criteria

1. An inbound request carrying B3 headers results in the same X-B3-TraceId appearing on all downstream outbound calls made during that request's handling.

2. An inbound request with no B3 headers results in a newly generated trace ID being used for all downstream calls.

3. The following B3 headers are propagated on every outbound HTTP call:

   Header	Description
   X-B3-TraceId	64-bit or 128-bit trace ID, hex-encoded
   X-B3-SpanId	64-bit span ID, hex-encoded
   X-B3-ParentSpanId	Parent span ID if available
   X-B3-Sampled	Sampling flag (0 or 1)

4. All outbound HTTP calls to MOSIP IDA, Sunbird Registry, and the JWKS endpoint carry the B3 trace headers.

5. The trace context extraction runs before all route handlers.

6. Unit tests cover: B3 headers present on inbound → same headers forwarded outbound; no inbound headers → generated trace ID forwarded outbound.

---

Known Edge Cases / Risks

B3 single-header vs multi-header format

MOSIP services may expect multi-header B3 format (X-B3-TraceId, X-B3-SpanId, etc.) rather than the single-header format (b3: {traceId}-{spanId}-{flags}). Confirm which format MOSIP downstream services accept before implementation.

Sampling decision

If no X-B3-Sampled flag is present on the inbound request, a default must be chosen. Defaulting to 1 (sample all) may generate noise in downstream systems; confirm the expected default with the MOSIP team.

JWKS calls are not per-request

The JWKS client fetches keys on a background schedule, not per inbound request, so there is no user request context to propagate. B3 header injection on these calls does not contribute to a user-facing trace chain.

Context not passed on some outbound calls

Several outbound HTTP calls in the MOSIP IDA integration do not carry request context, so trace data cannot reach them without fixing context propagation first. This is a prerequisite for full B3 header coverage.