add a Parent-Request-Id header (#1365)

add a Parent-Request-Id header

Author: bjlaub

changelog/@unreleased/pr-1365.v2.yml

@@ -0,0 +1,5 @@
+type: improvement
+improvement:
+  description: add a Parent-Request-Id header
+  links:
+  - https://github.com/palantir/tracing-java/pull/1365

tracing-api/src/main/java/com/palantir/tracing/api/TraceHttpHeaders.java

@@ -16,7 +16,7 @@
 
 package com.palantir.tracing.api;
 
-/** Zipkin-compatible HTTP header names. */
+/** HTTP header names used by tracing-java. */
 public interface TraceHttpHeaders {
     String TRACE_ID = "X-B3-TraceId";
     /**
@@ -39,4 +39,12 @@ public interface TraceHttpHeaders {
      */
     @Deprecated
     String ORIGINATING_SPAN_ID = "X-OrigSpanId";
+
+    /**
+     * The {@code Parent-Request-Id} header represents the requestId of the caller, if present.
+     * This provides a direct causal connection between requests up a call stack. This can be an advantage
+     * over traceId which provides a broad set of data without information to understand the call
+     * pathing unless spans are sampled.
+     */
+    String PARENT_REQUEST_ID = "Parent-Request-Id";
 }

tracing/src/main/java/com/palantir/tracing/Tracers.java

@@ -278,6 +278,10 @@ public static <T> void addTracingHeaders(
         if (forUserAgent.isPresent()) {
             tracingHeadersEnrichingFunction.addHeader(TraceHttpHeaders.FOR_USER_AGENT, forUserAgent.get(), state);
         }
+        Optional<String> requestId = traceMetadata.getRequestId();
+        if (requestId.isPresent()) {
+            tracingHeadersEnrichingFunction.addHeader(TraceHttpHeaders.PARENT_REQUEST_ID, requestId.get(), state);
+        }
     }
 
     private static final class ListenableFutureSpanListener implements Runnable {

tracing/src/test/java/com/palantir/tracing/TracersTest.java

@@ -907,6 +907,32 @@ public void testAddTracingHeaders_populates() {
                         "X-B3-TraceId", "defaultTraceId",
                         "X-B3-Sampled", "1"));
         assertThat(headers).containsKey("X-B3-SpanId");
+        // no requestId set when span type is local
+        assertThat(headers).doesNotContainKey("Parent-Request-Id");
+    }
+
+    @Test
+    public void testAddTracingHeaders_addsParentRequestId() {
+        // need to set span type to SERVER_INCOMING to generate a requestId
+        Tracer.initTraceWithSpan(
+                Observability.SAMPLE,
+                "defaultTraceId",
+                Optional.of("forUserAgent"),
+                "rootOperation",
+                SpanType.SERVER_INCOMING);
+        Optional<TraceMetadata> traceMetadata = Tracer.maybeGetTraceMetadata();
+        assertThat(traceMetadata).isPresent();
+
+        Optional<String> requestId = traceMetadata.get().getRequestId();
+        assertThat(requestId).isPresent();
+
+        Map<String, String> headers = new HashMap<>();
+        TracingHeadersEnrichingFunction<Map<String, String>> enrichingFunction =
+                (headerName, headerValue, state) -> state.put(headerName, headerValue);
+
+        Tracers.addTracingHeaders(headers, enrichingFunction);
+
+        assertThat(headers).containsEntry("Parent-Request-Id", requestId.get());
     }
 
     private static Callable<Void> newTraceExpectingCallable(String expectedOperation) {