add request id to openai llm span attributes

braintrust-sdk/instrumentation/anthropic_2_2_0/src/main/java/dev/braintrust/instrumentation/anthropic/v2_2_0/TracingHttpClient.java

@@ -24,6 +24,9 @@
 import java.io.InputStreamReader;
 import java.io.OutputStream;
 import java.nio.charset.StandardCharsets;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.concurrent.atomic.AtomicLong;
@@ -260,10 +263,25 @@ private void onFirstByte() {
 
  private void onStreamClosed() {
  try {
+ // Scooped first and unconditionally: tagSpanFromBuffer bails on an empty body,
+ // and a failed request is both the likeliest source of one and the case where
+ // the vendor's request id is most worth having.
+ InstrumentationSemConv.tagLLMSpanIdHeaders(span, headersAsMap(delegate.headers()));
+
  byte[] bytes;
  synchronized (teeBuffer) {
  bytes = teeBuffer.toByteArray();
  }
+
+ // Recorded before tagging: the anthropic sdk raises above this layer, so the
+ // error status is ours alone to set, and losing it to a body-parsing problem is
+ // worse than losing the parsed output.
+ int statusCode = delegate.statusCode();
+ if (statusCode >= 400) {
+ InstrumentationSemConv.tagLLMSpanHttpError(
+ span, statusCode, new String(bytes, StandardCharsets.UTF_8));
+ }
+
  // tagLLMSpanResponse also emits child spans for any server-side tool calls (web
  // search, etc.) nested under the LLM span while it is still live.
  tagSpanFromBuffer(tracer, span, bytes, timeToFirstTokenNanos.get());
@@ -387,6 +405,29 @@ private static void tagSpanFromBuffer(
  }
  }
 
+ /**
+ * Adapts the anthropic sdk's {@code Headers} to the vendor-neutral shape {@link
+ * InstrumentationSemConv} consumes. Returns null on failure so a header-shape change can never
+ * take down the response tagging that follows it.
+ */
+ @Nullable
+ private static Map<String, List<String>> headersAsMap(
+ @Nullable com.anthropic.core.http.Headers headers) {
+ if (headers == null) {
+ return null;
+ }
+ try {
+ var map = new HashMap<String, List<String>>();
+ for (String name : headers.names()) {
+ map.put(name, headers.values(name));
+ }
+ return map;
+ } catch (Exception e) {
+ log.debug("could not read response headers", e);
+ return null;
+ }
+ }
+
  private static String firstNonEmptyLine(byte[] bytes) {
  int start = 0;
  for (int i = 0; i <= bytes.length; i++) {

braintrust-sdk/instrumentation/anthropic_2_2_0/src/test/java/dev/braintrust/instrumentation/anthropic/v2_2_0/BraintrustAnthropicTest.java

@@ -562,4 +562,76 @@ void testWrappedClientObjectContract() {
  wrapped.toString().contains("ContextCapturingProxy"),
  "toString should identify the proxy, got: " + wrapped);
  }
+
+ /**
+ * Anthropic returns its correlation ID as {@code request-id} (no {@code x-} prefix, unlike
+ * OpenAI) and its object ID as {@code msg_*}. Both must land on the span for streaming and
+ * non-streaming alike — the header comes off the HTTP response, the object ID out of the
+ * reassembled body, so the two travel independent paths.
+ */
+ @Test
+ @SneakyThrows
+ void testCorrelationIdsCaptured() {
+ AnthropicClient anthropicClient =
+ AnthropicOkHttpClient.builder()
+ .baseUrl(testHarness.anthropicBaseUrl())
+ .apiKey(testHarness.anthropicApiKey())
+ .build();
+
+ var request =
+ MessageCreateParams.builder()
+ .model(Model.of(TEST_MODEL))
+ .system("You are a helpful assistant")
+ .addUserMessage("What is the capital of France?")
+ .maxTokens(50)
+ .temperature(0.0)
+ .build();
+
+ anthropicClient.messages().create(request);
+ assertAnthropicIdsCaptured(testHarness.awaitExportedSpans().get(0));
+ }
+
+ @Test
+ @SneakyThrows
+ void testCorrelationIdsCapturedStreaming() {
+ AnthropicClient anthropicClient =
+ AnthropicOkHttpClient.builder()
+ .baseUrl(testHarness.anthropicBaseUrl())
+ .apiKey(testHarness.anthropicApiKey())
+ .build();
+
+ var request =
+ MessageCreateParams.builder()
+ .model(Model.of(TEST_MODEL))
+ .system("You are a helpful assistant")
+ .addUserMessage("What is the capital of France?")
+ .maxTokens(50)
+ .temperature(0.0)
+ .build();
+
+ try (var stream = anthropicClient.messages().createStreaming(request)) {
+ stream.stream().forEach(event -> {});
+ }
+ assertAnthropicIdsCaptured(testHarness.awaitExportedSpans().get(0));
+ }
+
+ /**
+ * Asserts presence only for the header: its value is an opaque vendor string, so pinning its
+ * shape would encode an assumption the provider never made.
+ */
+ private static void assertAnthropicIdsCaptured(io.opentelemetry.sdk.trace.data.SpanData span) {
+ var attributes = span.getAttributes();
+
+ String requestId = attributes.get(AttributeKey.stringKey("request-id"));
+ assertNotNull(requestId, "request-id header must be captured");
+ assertFalse(requestId.isBlank(), "request-id must not be blank");
+
+ String responseId = attributes.get(AttributeKey.stringKey("response_id"));
+ assertNotNull(responseId, "response_id must be captured from the response body");
+ assertTrue(responseId.startsWith("msg_"), "unexpected response_id: " + responseId);
+
+ assertNull(
+ attributes.get(AttributeKey.stringKey("x-request-id")),
+ "OpenAI's header name must not appear on an Anthropic span");
+ }
 }

braintrust-sdk/instrumentation/openai_2_15_0/src/main/java/dev/braintrust/instrumentation/openai/v2_15_0/TracingHttpClient.java

@@ -20,6 +20,9 @@
 import io.opentelemetry.context.Context;
 import java.io.*;
 import java.nio.charset.StandardCharsets;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.concurrent.atomic.AtomicLong;
@@ -68,7 +71,7 @@ private static ExtractedRequest extractCallerContext(HttpRequest request) {
  Context context = contextFromTraceparent(values.get(0));
  HttpRequest stripped =
  request.toBuilder()
- .replaceHeaders(ContextCapturingProxy.CONTEXT_HEADER, java.util.List.of())
+ .replaceHeaders(ContextCapturingProxy.CONTEXT_HEADER, List.of())
  .build();
  return new ExtractedRequest(stripped, context);
  }
@@ -259,6 +262,28 @@ private static void tagSpanFromBuffer(
  }
  }
 
+ /**
+ * Adapts openai-java's {@link Headers} to the vendor-neutral shape {@link
+ * InstrumentationSemConv} consumes. Returns null on failure so a header-shape change can never
+ * take down the response tagging that follows it.
+ */
+ @Nullable
+ private static Map<String, List<String>> headersAsMap(@Nullable Headers headers) {
+ if (headers == null) {
+ return null;
+ }
+ try {
+ var map = new HashMap<String, List<String>>();
+ for (String name : headers.names()) {
+ map.put(name, headers.values(name));
+ }
+ return map;
+ } catch (Exception e) {
+ log.debug("could not read response headers", e);
+ return null;
+ }
+ }
+
  private static String firstNonEmptyLine(byte[] bytes) {
  int start = 0;
  for (int i = 0; i <= bytes.length; i++) {
@@ -368,12 +393,27 @@ private void onFirstByte() {
  /** Called back by {@link TeeInputStream} when the stream is fully drained or closed. */
  private void onStreamClosed() {
  try {
+ // Scooped first and unconditionally: tagSpanFromBuffer bails on an empty body,
+ // and a failed request is both the likeliest source of one and the case where
+ // the vendor's request id is most worth having.
+ InstrumentationSemConv.tagLLMSpanIdHeaders(span, headersAsMap(delegate.headers()));
+
  // Synchronize on teeBuffer to ensure any write() that was in-flight on a
  // concurrent read thread has fully completed before we snapshot the bytes.
  byte[] bytes;
  synchronized (teeBuffer) {
  bytes = teeBuffer.toByteArray();
  }
+
+ // Recorded before tagging: openai-java raises above this layer, so the error
+ // status is ours alone to set, and losing it to a body-parsing problem is worse
+ // than losing the parsed output.
+ int statusCode = delegate.statusCode();
+ if (statusCode >= 400) {
+ InstrumentationSemConv.tagLLMSpanHttpError(
+ span, statusCode, new String(bytes, StandardCharsets.UTF_8));
+ }
+
  // tagLLMSpanResponse also emits child spans for any server-side tool calls (web
  // search, etc.) nested under the LLM span while it is still live. No-op for Chat
  // Completions responses (no `output` array).

braintrust-sdk/instrumentation/openai_2_15_0/src/test/java/dev/braintrust/instrumentation/openai/v2_15_0/BraintrustOpenAITest.java

@@ -24,6 +24,7 @@
 import dev.braintrust.TestHarness;
 import dev.braintrust.instrumentation.Instrumenter;
 import io.opentelemetry.api.common.AttributeKey;
+import io.opentelemetry.api.trace.StatusCode;
 import io.opentelemetry.sdk.trace.data.SpanData;
 import java.util.List;
 import java.util.Map;
@@ -649,5 +650,65 @@ private static void assertValidOpenAISpan(SpanData span, boolean isStreaming) {
  assertNotNull(
  attributes.get(AttributeKey.stringKey("braintrust.output_json")),
  "output must be set");
+ assertOpenAIIdsCaptured(span);
+ }
+
+ /**
+ * Both correlation IDs OpenAI hands back. Deliberately asserts only presence and the object-ID
+ * prefix: {@code x-request-id} is opaque, and OpenAI returns both {@code req_*} and bare UUIDs
+ * for it, so pinning its shape would be wrong.
+ */
+ private static void assertOpenAIIdsCaptured(SpanData span) {
+ var attributes = span.getAttributes();
+
+ String requestId = attributes.get(AttributeKey.stringKey("x-request-id"));
+ assertNotNull(requestId, "x-request-id header must be captured");
+ assertFalse(requestId.isBlank(), "x-request-id must not be blank");
+
+ String responseId = attributes.get(AttributeKey.stringKey("response_id"));
+ assertNotNull(responseId, "response_id must be captured from the response body");
+ assertTrue(
+ responseId.startsWith("resp_") || responseId.startsWith("chatcmpl-"),
+ "unexpected response_id: " + responseId);
+ }
+
+ /**
+ * A failed call is the case where the vendor's request id matters most, and the only one where
+ * it is the *sole* ID available: an error body carries no object id of its own. openai-java
+ * raises its exception above the HTTP layer we instrument, so the error status on the span is
+ * ours alone to set.
+ */
+ @Test
+ @SneakyThrows
+ void testHttpErrorTagsSpan() {
+ OpenAIClient openAIClient =
+ OpenAIOkHttpClient.builder()
+ .baseUrl(testHarness.openAiBaseUrl())
+ .apiKey(testHarness.openAiApiKey())
+ .build();
+
+ var request =
+ ChatCompletionCreateParams.builder()
+ .model("gpt-4o-mini-nonexistent-model")
+ .addUserMessage("What is the capital of France?")
+ .build();
+
+ assertThrows(Exception.class, () -> openAIClient.chat().completions().create(request));
+
+ var spans = testHarness.awaitExportedSpans();
+ assertEquals(1, spans.size());
+ var span = spans.get(0);
+
+ assertEquals(
+ StatusCode.ERROR,
+ span.getStatus().getStatusCode(),
+ "a non-2xx response must mark the span failed");
+
+ var attributes = span.getAttributes();
+ String requestId = attributes.get(AttributeKey.stringKey("x-request-id"));
+ assertNotNull(requestId, "x-request-id must still be captured on a failed call");
+ assertNull(
+ attributes.get(AttributeKey.stringKey("response_id")),
+ "an error body has no object id to capture");
  }
 }

braintrust-sdk/instrumentation/anthropic_2_2_0/src/main/java/dev/braintrust/instrumentation/anthropic/v2_2_0/TracingHttpClient.java

@@ -24,6 +24,9 @@
 import java.io.InputStreamReader;
 import java.io.OutputStream;
 import java.nio.charset.StandardCharsets;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.concurrent.atomic.AtomicLong;
@@ -260,10 +263,25 @@ private void onFirstByte() {
 
  private void onStreamClosed() {
  try {
+ // Scooped first and unconditionally: tagSpanFromBuffer bails on an empty body,
+ // and a failed request is both the likeliest source of one and the case where
+ // the vendor's request id is most worth having.
+ InstrumentationSemConv.tagLLMSpanIdHeaders(span, headersAsMap(delegate.headers()));
+
  byte[] bytes;
  synchronized (teeBuffer) {
  bytes = teeBuffer.toByteArray();
  }
+
+ // Recorded before tagging: the anthropic sdk raises above this layer, so the
+ // error status is ours alone to set, and losing it to a body-parsing problem is
+ // worse than losing the parsed output.
+ int statusCode = delegate.statusCode();
+ if (statusCode >= 400) {
+ InstrumentationSemConv.tagLLMSpanHttpError(
+ span, statusCode, new String(bytes, StandardCharsets.UTF_8));
+ }
+
  // tagLLMSpanResponse also emits child spans for any server-side tool calls (web
  // search, etc.) nested under the LLM span while it is still live.
  tagSpanFromBuffer(tracer, span, bytes, timeToFirstTokenNanos.get());
@@ -387,6 +405,29 @@ private static void tagSpanFromBuffer(
  }
  }
 
+ /**
+ * Adapts the anthropic sdk's {@code Headers} to the vendor-neutral shape {@link
+ * InstrumentationSemConv} consumes. Returns null on failure so a header-shape change can never
+ * take down the response tagging that follows it.
+ */
+ @Nullable
+ private static Map<String, List<String>> headersAsMap(
+ @Nullable com.anthropic.core.http.Headers headers) {
+ if (headers == null) {
+ return null;
+ }
+ try {
+ var map = new HashMap<String, List<String>>();
+ for (String name : headers.names()) {
+ map.put(name, headers.values(name));
+ }
+ return map;
+ } catch (Exception e) {
+ log.debug("could not read response headers", e);
+ return null;
+ }
+ }
+
  private static String firstNonEmptyLine(byte[] bytes) {
  int start = 0;
  for (int i = 0; i <= bytes.length; i++) {

braintrust-sdk/instrumentation/anthropic_2_2_0/src/test/java/dev/braintrust/instrumentation/anthropic/v2_2_0/BraintrustAnthropicTest.java

@@ -562,4 +562,76 @@ void testWrappedClientObjectContract() {
  wrapped.toString().contains("ContextCapturingProxy"),
  "toString should identify the proxy, got: " + wrapped);
  }
+
+ /**
+ * Anthropic returns its correlation ID as {@code request-id} (no {@code x-} prefix, unlike
+ * OpenAI) and its object ID as {@code msg_*}. Both must land on the span for streaming and
+ * non-streaming alike — the header comes off the HTTP response, the object ID out of the
+ * reassembled body, so the two travel independent paths.
+ */
+ @Test
+ @SneakyThrows
+ void testCorrelationIdsCaptured() {
+ AnthropicClient anthropicClient =
+ AnthropicOkHttpClient.builder()
+ .baseUrl(testHarness.anthropicBaseUrl())
+ .apiKey(testHarness.anthropicApiKey())
+ .build();
+
+ var request =
+ MessageCreateParams.builder()
+ .model(Model.of(TEST_MODEL))
+ .system("You are a helpful assistant")
+ .addUserMessage("What is the capital of France?")
+ .maxTokens(50)
+ .temperature(0.0)
+ .build();
+
+ anthropicClient.messages().create(request);
+ assertAnthropicIdsCaptured(testHarness.awaitExportedSpans().get(0));
+ }
+
+ @Test
+ @SneakyThrows
+ void testCorrelationIdsCapturedStreaming() {
+ AnthropicClient anthropicClient =
+ AnthropicOkHttpClient.builder()
+ .baseUrl(testHarness.anthropicBaseUrl())
+ .apiKey(testHarness.anthropicApiKey())
+ .build();
+
+ var request =
+ MessageCreateParams.builder()
+ .model(Model.of(TEST_MODEL))
+ .system("You are a helpful assistant")
+ .addUserMessage("What is the capital of France?")
+ .maxTokens(50)
+ .temperature(0.0)
+ .build();
+
+ try (var stream = anthropicClient.messages().createStreaming(request)) {
+ stream.stream().forEach(event -> {});
+ }
+ assertAnthropicIdsCaptured(testHarness.awaitExportedSpans().get(0));
+ }
+
+ /**
+ * Asserts presence only for the header: its value is an opaque vendor string, so pinning its
+ * shape would encode an assumption the provider never made.
+ */
+ private static void assertAnthropicIdsCaptured(io.opentelemetry.sdk.trace.data.SpanData span) {
+ var attributes = span.getAttributes();
+
+ String requestId = attributes.get(AttributeKey.stringKey("request-id"));
+ assertNotNull(requestId, "request-id header must be captured");
+ assertFalse(requestId.isBlank(), "request-id must not be blank");
+
+ String responseId = attributes.get(AttributeKey.stringKey("response_id"));
+ assertNotNull(responseId, "response_id must be captured from the response body");
+ assertTrue(responseId.startsWith("msg_"), "unexpected response_id: " + responseId);
+
+ assertNull(
+ attributes.get(AttributeKey.stringKey("x-request-id")),
+ "OpenAI's header name must not appear on an Anthropic span");
+ }
 }

braintrust-sdk/instrumentation/openai_2_15_0/src/main/java/dev/braintrust/instrumentation/openai/v2_15_0/TracingHttpClient.java

@@ -20,6 +20,9 @@
 import io.opentelemetry.context.Context;
 import java.io.*;
 import java.nio.charset.StandardCharsets;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.concurrent.atomic.AtomicLong;
@@ -68,7 +71,7 @@ private static ExtractedRequest extractCallerContext(HttpRequest request) {
  Context context = contextFromTraceparent(values.get(0));
  HttpRequest stripped =
  request.toBuilder()
- .replaceHeaders(ContextCapturingProxy.CONTEXT_HEADER, java.util.List.of())
+ .replaceHeaders(ContextCapturingProxy.CONTEXT_HEADER, List.of())
  .build();
  return new ExtractedRequest(stripped, context);
  }
@@ -259,6 +262,28 @@ private static void tagSpanFromBuffer(
  }
  }
 
+ /**
+ * Adapts openai-java's {@link Headers} to the vendor-neutral shape {@link
+ * InstrumentationSemConv} consumes. Returns null on failure so a header-shape change can never
+ * take down the response tagging that follows it.
+ */
+ @Nullable
+ private static Map<String, List<String>> headersAsMap(@Nullable Headers headers) {
+ if (headers == null) {
+ return null;
+ }
+ try {
+ var map = new HashMap<String, List<String>>();
+ for (String name : headers.names()) {
+ map.put(name, headers.values(name));
+ }
+ return map;
+ } catch (Exception e) {
+ log.debug("could not read response headers", e);
+ return null;
+ }
+ }
+
  private static String firstNonEmptyLine(byte[] bytes) {
  int start = 0;
  for (int i = 0; i <= bytes.length; i++) {
@@ -368,12 +393,27 @@ private void onFirstByte() {
  /** Called back by {@link TeeInputStream} when the stream is fully drained or closed. */
  private void onStreamClosed() {
  try {
+ // Scooped first and unconditionally: tagSpanFromBuffer bails on an empty body,
+ // and a failed request is both the likeliest source of one and the case where
+ // the vendor's request id is most worth having.
+ InstrumentationSemConv.tagLLMSpanIdHeaders(span, headersAsMap(delegate.headers()));
+
  // Synchronize on teeBuffer to ensure any write() that was in-flight on a
  // concurrent read thread has fully completed before we snapshot the bytes.
  byte[] bytes;
  synchronized (teeBuffer) {
  bytes = teeBuffer.toByteArray();
  }
+
+ // Recorded before tagging: openai-java raises above this layer, so the error
+ // status is ours alone to set, and losing it to a body-parsing problem is worse
+ // than losing the parsed output.
+ int statusCode = delegate.statusCode();
+ if (statusCode >= 400) {
+ InstrumentationSemConv.tagLLMSpanHttpError(
+ span, statusCode, new String(bytes, StandardCharsets.UTF_8));
+ }
+
  // tagLLMSpanResponse also emits child spans for any server-side tool calls (web
  // search, etc.) nested under the LLM span while it is still live. No-op for Chat
  // Completions responses (no `output` array).

braintrust-sdk/instrumentation/openai_2_15_0/src/test/java/dev/braintrust/instrumentation/openai/v2_15_0/BraintrustOpenAITest.java

@@ -24,6 +24,7 @@
 import dev.braintrust.TestHarness;
 import dev.braintrust.instrumentation.Instrumenter;
 import io.opentelemetry.api.common.AttributeKey;
+import io.opentelemetry.api.trace.StatusCode;
 import io.opentelemetry.sdk.trace.data.SpanData;
 import java.util.List;
 import java.util.Map;
@@ -649,5 +650,65 @@ private static void assertValidOpenAISpan(SpanData span, boolean isStreaming) {
  assertNotNull(
  attributes.get(AttributeKey.stringKey("braintrust.output_json")),
  "output must be set");
+ assertOpenAIIdsCaptured(span);
+ }
+
+ /**
+ * Both correlation IDs OpenAI hands back. Deliberately asserts only presence and the object-ID
+ * prefix: {@code x-request-id} is opaque, and OpenAI returns both {@code req_*} and bare UUIDs
+ * for it, so pinning its shape would be wrong.
+ */
+ private static void assertOpenAIIdsCaptured(SpanData span) {
+ var attributes = span.getAttributes();
+
+ String requestId = attributes.get(AttributeKey.stringKey("x-request-id"));
+ assertNotNull(requestId, "x-request-id header must be captured");
+ assertFalse(requestId.isBlank(), "x-request-id must not be blank");
+
+ String responseId = attributes.get(AttributeKey.stringKey("response_id"));
+ assertNotNull(responseId, "response_id must be captured from the response body");
+ assertTrue(
+ responseId.startsWith("resp_") || responseId.startsWith("chatcmpl-"),
+ "unexpected response_id: " + responseId);
+ }
+
+ /**
+ * A failed call is the case where the vendor's request id matters most, and the only one where
+ * it is the *sole* ID available: an error body carries no object id of its own. openai-java
+ * raises its exception above the HTTP layer we instrument, so the error status on the span is
+ * ours alone to set.
+ */
+ @Test
+ @SneakyThrows
+ void testHttpErrorTagsSpan() {
+ OpenAIClient openAIClient =
+ OpenAIOkHttpClient.builder()
+ .baseUrl(testHarness.openAiBaseUrl())
+ .apiKey(testHarness.openAiApiKey())
+ .build();
+
+ var request =
+ ChatCompletionCreateParams.builder()
+ .model("gpt-4o-mini-nonexistent-model")
+ .addUserMessage("What is the capital of France?")
+ .build();
+
+ assertThrows(Exception.class, () -> openAIClient.chat().completions().create(request));
+
+ var spans = testHarness.awaitExportedSpans();
+ assertEquals(1, spans.size());
+ var span = spans.get(0);
+
+ assertEquals(
+ StatusCode.ERROR,
+ span.getStatus().getStatusCode(),
+ "a non-2xx response must mark the span failed");
+
+ var attributes = span.getAttributes();
+ String requestId = attributes.get(AttributeKey.stringKey("x-request-id"));
+ assertNotNull(requestId, "x-request-id must still be captured on a failed call");
+ assertNull(
+ attributes.get(AttributeKey.stringKey("response_id")),
+ "an error body has no object id to capture");
  }
 }

braintrust-sdk/instrumentation/anthropic_2_2_0/src/main/java/dev/braintrust/instrumentation/anthropic/v2_2_0/TracingHttpClient.java

@@ -24,6 +24,9 @@
 import java.io.InputStreamReader;
 import java.io.OutputStream;
 import java.nio.charset.StandardCharsets;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.concurrent.atomic.AtomicLong;
@@ -260,10 +263,25 @@ private void onFirstByte() {
 
  private void onStreamClosed() {
  try {
+ // Scooped first and unconditionally: tagSpanFromBuffer bails on an empty body,
+ // and a failed request is both the likeliest source of one and the case where
+ // the vendor's request id is most worth having.
+ InstrumentationSemConv.tagLLMSpanIdHeaders(span, headersAsMap(delegate.headers()));
+
  byte[] bytes;
  synchronized (teeBuffer) {
  bytes = teeBuffer.toByteArray();
  }
+
+ // Recorded before tagging: the anthropic sdk raises above this layer, so the
+ // error status is ours alone to set, and losing it to a body-parsing problem is
+ // worse than losing the parsed output.
+ int statusCode = delegate.statusCode();
+ if (statusCode >= 400) {
+ InstrumentationSemConv.tagLLMSpanHttpError(
+ span, statusCode, new String(bytes, StandardCharsets.UTF_8));
+ }
+
  // tagLLMSpanResponse also emits child spans for any server-side tool calls (web
  // search, etc.) nested under the LLM span while it is still live.
  tagSpanFromBuffer(tracer, span, bytes, timeToFirstTokenNanos.get());
@@ -387,6 +405,29 @@ private static void tagSpanFromBuffer(
  }
  }
 
+ /**
+ * Adapts the anthropic sdk's {@code Headers} to the vendor-neutral shape {@link
+ * InstrumentationSemConv} consumes. Returns null on failure so a header-shape change can never
+ * take down the response tagging that follows it.
+ */
+ @Nullable
+ private static Map<String, List<String>> headersAsMap(
+ @Nullable com.anthropic.core.http.Headers headers) {
+ if (headers == null) {
+ return null;
+ }
+ try {
+ var map = new HashMap<String, List<String>>();
+ for (String name : headers.names()) {
+ map.put(name, headers.values(name));
+ }
+ return map;
+ } catch (Exception e) {
+ log.debug("could not read response headers", e);
+ return null;
+ }
+ }
+
  private static String firstNonEmptyLine(byte[] bytes) {
  int start = 0;
  for (int i = 0; i <= bytes.length; i++) {

braintrust-sdk/instrumentation/anthropic_2_2_0/src/test/java/dev/braintrust/instrumentation/anthropic/v2_2_0/BraintrustAnthropicTest.java

@@ -562,4 +562,76 @@ void testWrappedClientObjectContract() {
  wrapped.toString().contains("ContextCapturingProxy"),
  "toString should identify the proxy, got: " + wrapped);
  }
+
+ /**
+ * Anthropic returns its correlation ID as {@code request-id} (no {@code x-} prefix, unlike
+ * OpenAI) and its object ID as {@code msg_*}. Both must land on the span for streaming and
+ * non-streaming alike — the header comes off the HTTP response, the object ID out of the
+ * reassembled body, so the two travel independent paths.
+ */
+ @Test
+ @SneakyThrows
+ void testCorrelationIdsCaptured() {
+ AnthropicClient anthropicClient =
+ AnthropicOkHttpClient.builder()
+ .baseUrl(testHarness.anthropicBaseUrl())
+ .apiKey(testHarness.anthropicApiKey())
+ .build();
+
+ var request =
+ MessageCreateParams.builder()
+ .model(Model.of(TEST_MODEL))
+ .system("You are a helpful assistant")
+ .addUserMessage("What is the capital of France?")
+ .maxTokens(50)
+ .temperature(0.0)
+ .build();
+
+ anthropicClient.messages().create(request);
+ assertAnthropicIdsCaptured(testHarness.awaitExportedSpans().get(0));
+ }
+
+ @Test
+ @SneakyThrows
+ void testCorrelationIdsCapturedStreaming() {
+ AnthropicClient anthropicClient =
+ AnthropicOkHttpClient.builder()
+ .baseUrl(testHarness.anthropicBaseUrl())
+ .apiKey(testHarness.anthropicApiKey())
+ .build();
+
+ var request =
+ MessageCreateParams.builder()
+ .model(Model.of(TEST_MODEL))
+ .system("You are a helpful assistant")
+ .addUserMessage("What is the capital of France?")
+ .maxTokens(50)
+ .temperature(0.0)
+ .build();
+
+ try (var stream = anthropicClient.messages().createStreaming(request)) {
+ stream.stream().forEach(event -> {});
+ }
+ assertAnthropicIdsCaptured(testHarness.awaitExportedSpans().get(0));
+ }
+
+ /**
+ * Asserts presence only for the header: its value is an opaque vendor string, so pinning its
+ * shape would encode an assumption the provider never made.
+ */
+ private static void assertAnthropicIdsCaptured(io.opentelemetry.sdk.trace.data.SpanData span) {
+ var attributes = span.getAttributes();
+
+ String requestId = attributes.get(AttributeKey.stringKey("request-id"));
+ assertNotNull(requestId, "request-id header must be captured");
+ assertFalse(requestId.isBlank(), "request-id must not be blank");
+
+ String responseId = attributes.get(AttributeKey.stringKey("response_id"));
+ assertNotNull(responseId, "response_id must be captured from the response body");
+ assertTrue(responseId.startsWith("msg_"), "unexpected response_id: " + responseId);
+
+ assertNull(
+ attributes.get(AttributeKey.stringKey("x-request-id")),
+ "OpenAI's header name must not appear on an Anthropic span");
+ }
 }

braintrust-sdk/instrumentation/openai_2_15_0/src/main/java/dev/braintrust/instrumentation/openai/v2_15_0/TracingHttpClient.java

@@ -20,6 +20,9 @@
 import io.opentelemetry.context.Context;
 import java.io.*;
 import java.nio.charset.StandardCharsets;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.concurrent.atomic.AtomicLong;
@@ -68,7 +71,7 @@ private static ExtractedRequest extractCallerContext(HttpRequest request) {
  Context context = contextFromTraceparent(values.get(0));
  HttpRequest stripped =
  request.toBuilder()
- .replaceHeaders(ContextCapturingProxy.CONTEXT_HEADER, java.util.List.of())
+ .replaceHeaders(ContextCapturingProxy.CONTEXT_HEADER, List.of())
  .build();
  return new ExtractedRequest(stripped, context);
  }
@@ -259,6 +262,28 @@ private static void tagSpanFromBuffer(
  }
  }
 
+ /**
+ * Adapts openai-java's {@link Headers} to the vendor-neutral shape {@link
+ * InstrumentationSemConv} consumes. Returns null on failure so a header-shape change can never
+ * take down the response tagging that follows it.
+ */
+ @Nullable
+ private static Map<String, List<String>> headersAsMap(@Nullable Headers headers) {
+ if (headers == null) {
+ return null;
+ }
+ try {
+ var map = new HashMap<String, List<String>>();
+ for (String name : headers.names()) {
+ map.put(name, headers.values(name));
+ }
+ return map;
+ } catch (Exception e) {
+ log.debug("could not read response headers", e);
+ return null;
+ }
+ }
+
  private static String firstNonEmptyLine(byte[] bytes) {
  int start = 0;
  for (int i = 0; i <= bytes.length; i++) {
@@ -368,12 +393,27 @@ private void onFirstByte() {
  /** Called back by {@link TeeInputStream} when the stream is fully drained or closed. */
  private void onStreamClosed() {
  try {
+ // Scooped first and unconditionally: tagSpanFromBuffer bails on an empty body,
+ // and a failed request is both the likeliest source of one and the case where
+ // the vendor's request id is most worth having.
+ InstrumentationSemConv.tagLLMSpanIdHeaders(span, headersAsMap(delegate.headers()));
+
  // Synchronize on teeBuffer to ensure any write() that was in-flight on a
  // concurrent read thread has fully completed before we snapshot the bytes.
  byte[] bytes;
  synchronized (teeBuffer) {
  bytes = teeBuffer.toByteArray();
  }
+
+ // Recorded before tagging: openai-java raises above this layer, so the error
+ // status is ours alone to set, and losing it to a body-parsing problem is worse
+ // than losing the parsed output.
+ int statusCode = delegate.statusCode();
+ if (statusCode >= 400) {
+ InstrumentationSemConv.tagLLMSpanHttpError(
+ span, statusCode, new String(bytes, StandardCharsets.UTF_8));
+ }
+
  // tagLLMSpanResponse also emits child spans for any server-side tool calls (web
  // search, etc.) nested under the LLM span while it is still live. No-op for Chat
  // Completions responses (no `output` array).

braintrust-sdk/instrumentation/openai_2_15_0/src/test/java/dev/braintrust/instrumentation/openai/v2_15_0/BraintrustOpenAITest.java

@@ -24,6 +24,7 @@
 import dev.braintrust.TestHarness;
 import dev.braintrust.instrumentation.Instrumenter;
 import io.opentelemetry.api.common.AttributeKey;
+import io.opentelemetry.api.trace.StatusCode;
 import io.opentelemetry.sdk.trace.data.SpanData;
 import java.util.List;
 import java.util.Map;
@@ -649,5 +650,65 @@ private static void assertValidOpenAISpan(SpanData span, boolean isStreaming) {
  assertNotNull(
  attributes.get(AttributeKey.stringKey("braintrust.output_json")),
  "output must be set");
+ assertOpenAIIdsCaptured(span);
+ }
+
+ /**
+ * Both correlation IDs OpenAI hands back. Deliberately asserts only presence and the object-ID
+ * prefix: {@code x-request-id} is opaque, and OpenAI returns both {@code req_*} and bare UUIDs
+ * for it, so pinning its shape would be wrong.
+ */
+ private static void assertOpenAIIdsCaptured(SpanData span) {
+ var attributes = span.getAttributes();
+
+ String requestId = attributes.get(AttributeKey.stringKey("x-request-id"));
+ assertNotNull(requestId, "x-request-id header must be captured");
+ assertFalse(requestId.isBlank(), "x-request-id must not be blank");
+
+ String responseId = attributes.get(AttributeKey.stringKey("response_id"));
+ assertNotNull(responseId, "response_id must be captured from the response body");
+ assertTrue(
+ responseId.startsWith("resp_") || responseId.startsWith("chatcmpl-"),
+ "unexpected response_id: " + responseId);
+ }
+
+ /**
+ * A failed call is the case where the vendor's request id matters most, and the only one where
+ * it is the *sole* ID available: an error body carries no object id of its own. openai-java
+ * raises its exception above the HTTP layer we instrument, so the error status on the span is
+ * ours alone to set.
+ */
+ @Test
+ @SneakyThrows
+ void testHttpErrorTagsSpan() {
+ OpenAIClient openAIClient =
+ OpenAIOkHttpClient.builder()
+ .baseUrl(testHarness.openAiBaseUrl())
+ .apiKey(testHarness.openAiApiKey())
+ .build();
+
+ var request =
+ ChatCompletionCreateParams.builder()
+ .model("gpt-4o-mini-nonexistent-model")
+ .addUserMessage("What is the capital of France?")
+ .build();
+
+ assertThrows(Exception.class, () -> openAIClient.chat().completions().create(request));
+
+ var spans = testHarness.awaitExportedSpans();
+ assertEquals(1, spans.size());
+ var span = spans.get(0);
+
+ assertEquals(
+ StatusCode.ERROR,
+ span.getStatus().getStatusCode(),
+ "a non-2xx response must mark the span failed");
+
+ var attributes = span.getAttributes();
+ String requestId = attributes.get(AttributeKey.stringKey("x-request-id"));
+ assertNotNull(requestId, "x-request-id must still be captured on a failed call");
+ assertNull(
+ attributes.get(AttributeKey.stringKey("response_id")),
+ "an error body has no object id to capture");
  }
 }

braintrust-sdk/instrumentation/anthropic_2_2_0/src/main/java/dev/braintrust/instrumentation/anthropic/v2_2_0/TracingHttpClient.java

@@ -24,6 +24,9 @@
 import java.io.InputStreamReader;
 import java.io.OutputStream;
 import java.nio.charset.StandardCharsets;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.concurrent.atomic.AtomicLong;
@@ -260,10 +263,25 @@ private void onFirstByte() {
 
  private void onStreamClosed() {
  try {
+ // Scooped first and unconditionally: tagSpanFromBuffer bails on an empty body,
+ // and a failed request is both the likeliest source of one and the case where
+ // the vendor's request id is most worth having.
+ InstrumentationSemConv.tagLLMSpanIdHeaders(span, headersAsMap(delegate.headers()));
+
  byte[] bytes;
  synchronized (teeBuffer) {
  bytes = teeBuffer.toByteArray();
  }
+
+ // Recorded before tagging: the anthropic sdk raises above this layer, so the
+ // error status is ours alone to set, and losing it to a body-parsing problem is
+ // worse than losing the parsed output.
+ int statusCode = delegate.statusCode();
+ if (statusCode >= 400) {
+ InstrumentationSemConv.tagLLMSpanHttpError(
+ span, statusCode, new String(bytes, StandardCharsets.UTF_8));
+ }
+
  // tagLLMSpanResponse also emits child spans for any server-side tool calls (web
  // search, etc.) nested under the LLM span while it is still live.
  tagSpanFromBuffer(tracer, span, bytes, timeToFirstTokenNanos.get());
@@ -387,6 +405,29 @@ private static void tagSpanFromBuffer(
  }
  }
 
+ /**
+ * Adapts the anthropic sdk's {@code Headers} to the vendor-neutral shape {@link
+ * InstrumentationSemConv} consumes. Returns null on failure so a header-shape change can never
+ * take down the response tagging that follows it.
+ */
+ @Nullable
+ private static Map<String, List<String>> headersAsMap(
+ @Nullable com.anthropic.core.http.Headers headers) {
+ if (headers == null) {
+ return null;
+ }
+ try {
+ var map = new HashMap<String, List<String>>();
+ for (String name : headers.names()) {
+ map.put(name, headers.values(name));
+ }
+ return map;
+ } catch (Exception e) {
+ log.debug("could not read response headers", e);
+ return null;
+ }
+ }
+
  private static String firstNonEmptyLine(byte[] bytes) {
  int start = 0;
  for (int i = 0; i <= bytes.length; i++) {

braintrust-sdk/instrumentation/anthropic_2_2_0/src/test/java/dev/braintrust/instrumentation/anthropic/v2_2_0/BraintrustAnthropicTest.java

@@ -562,4 +562,76 @@ void testWrappedClientObjectContract() {
  wrapped.toString().contains("ContextCapturingProxy"),
  "toString should identify the proxy, got: " + wrapped);
  }
+
+ /**
+ * Anthropic returns its correlation ID as {@code request-id} (no {@code x-} prefix, unlike
+ * OpenAI) and its object ID as {@code msg_*}. Both must land on the span for streaming and
+ * non-streaming alike — the header comes off the HTTP response, the object ID out of the
+ * reassembled body, so the two travel independent paths.
+ */
+ @Test
+ @SneakyThrows
+ void testCorrelationIdsCaptured() {
+ AnthropicClient anthropicClient =
+ AnthropicOkHttpClient.builder()
+ .baseUrl(testHarness.anthropicBaseUrl())
+ .apiKey(testHarness.anthropicApiKey())
+ .build();
+
+ var request =
+ MessageCreateParams.builder()
+ .model(Model.of(TEST_MODEL))
+ .system("You are a helpful assistant")
+ .addUserMessage("What is the capital of France?")
+ .maxTokens(50)
+ .temperature(0.0)
+ .build();
+
+ anthropicClient.messages().create(request);
+ assertAnthropicIdsCaptured(testHarness.awaitExportedSpans().get(0));
+ }
+
+ @Test
+ @SneakyThrows
+ void testCorrelationIdsCapturedStreaming() {
+ AnthropicClient anthropicClient =
+ AnthropicOkHttpClient.builder()
+ .baseUrl(testHarness.anthropicBaseUrl())
+ .apiKey(testHarness.anthropicApiKey())
+ .build();
+
+ var request =
+ MessageCreateParams.builder()
+ .model(Model.of(TEST_MODEL))
+ .system("You are a helpful assistant")
+ .addUserMessage("What is the capital of France?")
+ .maxTokens(50)
+ .temperature(0.0)
+ .build();
+
+ try (var stream = anthropicClient.messages().createStreaming(request)) {
+ stream.stream().forEach(event -> {});
+ }
+ assertAnthropicIdsCaptured(testHarness.awaitExportedSpans().get(0));
+ }
+
+ /**
+ * Asserts presence only for the header: its value is an opaque vendor string, so pinning its
+ * shape would encode an assumption the provider never made.
+ */
+ private static void assertAnthropicIdsCaptured(io.opentelemetry.sdk.trace.data.SpanData span) {
+ var attributes = span.getAttributes();
+
+ String requestId = attributes.get(AttributeKey.stringKey("request-id"));
+ assertNotNull(requestId, "request-id header must be captured");
+ assertFalse(requestId.isBlank(), "request-id must not be blank");
+
+ String responseId = attributes.get(AttributeKey.stringKey("response_id"));
+ assertNotNull(responseId, "response_id must be captured from the response body");
+ assertTrue(responseId.startsWith("msg_"), "unexpected response_id: " + responseId);
+
+ assertNull(
+ attributes.get(AttributeKey.stringKey("x-request-id")),
+ "OpenAI's header name must not appear on an Anthropic span");
+ }
 }

braintrust-sdk/instrumentation/openai_2_15_0/src/main/java/dev/braintrust/instrumentation/openai/v2_15_0/TracingHttpClient.java

@@ -20,6 +20,9 @@
 import io.opentelemetry.context.Context;
 import java.io.*;
 import java.nio.charset.StandardCharsets;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.concurrent.atomic.AtomicLong;
@@ -68,7 +71,7 @@ private static ExtractedRequest extractCallerContext(HttpRequest request) {
  Context context = contextFromTraceparent(values.get(0));
  HttpRequest stripped =
  request.toBuilder()
- .replaceHeaders(ContextCapturingProxy.CONTEXT_HEADER, java.util.List.of())
+ .replaceHeaders(ContextCapturingProxy.CONTEXT_HEADER, List.of())
  .build();
  return new ExtractedRequest(stripped, context);
  }
@@ -259,6 +262,28 @@ private static void tagSpanFromBuffer(
  }
  }
 
+ /**
+ * Adapts openai-java's {@link Headers} to the vendor-neutral shape {@link
+ * InstrumentationSemConv} consumes. Returns null on failure so a header-shape change can never
+ * take down the response tagging that follows it.
+ */
+ @Nullable
+ private static Map<String, List<String>> headersAsMap(@Nullable Headers headers) {
+ if (headers == null) {
+ return null;
+ }
+ try {
+ var map = new HashMap<String, List<String>>();
+ for (String name : headers.names()) {
+ map.put(name, headers.values(name));
+ }
+ return map;
+ } catch (Exception e) {
+ log.debug("could not read response headers", e);
+ return null;
+ }
+ }
+
  private static String firstNonEmptyLine(byte[] bytes) {
  int start = 0;
  for (int i = 0; i <= bytes.length; i++) {
@@ -368,12 +393,27 @@ private void onFirstByte() {
  /** Called back by {@link TeeInputStream} when the stream is fully drained or closed. */
  private void onStreamClosed() {
  try {
+ // Scooped first and unconditionally: tagSpanFromBuffer bails on an empty body,
+ // and a failed request is both the likeliest source of one and the case where
+ // the vendor's request id is most worth having.
+ InstrumentationSemConv.tagLLMSpanIdHeaders(span, headersAsMap(delegate.headers()));
+
  // Synchronize on teeBuffer to ensure any write() that was in-flight on a
  // concurrent read thread has fully completed before we snapshot the bytes.
  byte[] bytes;
  synchronized (teeBuffer) {
  bytes = teeBuffer.toByteArray();
  }
+
+ // Recorded before tagging: openai-java raises above this layer, so the error
+ // status is ours alone to set, and losing it to a body-parsing problem is worse
+ // than losing the parsed output.
+ int statusCode = delegate.statusCode();
+ if (statusCode >= 400) {
+ InstrumentationSemConv.tagLLMSpanHttpError(
+ span, statusCode, new String(bytes, StandardCharsets.UTF_8));
+ }
+
  // tagLLMSpanResponse also emits child spans for any server-side tool calls (web
  // search, etc.) nested under the LLM span while it is still live. No-op for Chat
  // Completions responses (no `output` array).

braintrust-sdk/instrumentation/openai_2_15_0/src/test/java/dev/braintrust/instrumentation/openai/v2_15_0/BraintrustOpenAITest.java

@@ -24,6 +24,7 @@
 import dev.braintrust.TestHarness;
 import dev.braintrust.instrumentation.Instrumenter;
 import io.opentelemetry.api.common.AttributeKey;
+import io.opentelemetry.api.trace.StatusCode;
 import io.opentelemetry.sdk.trace.data.SpanData;
 import java.util.List;
 import java.util.Map;
@@ -649,5 +650,65 @@ private static void assertValidOpenAISpan(SpanData span, boolean isStreaming) {
  assertNotNull(
  attributes.get(AttributeKey.stringKey("braintrust.output_json")),
  "output must be set");
+ assertOpenAIIdsCaptured(span);
+ }
+
+ /**
+ * Both correlation IDs OpenAI hands back. Deliberately asserts only presence and the object-ID
+ * prefix: {@code x-request-id} is opaque, and OpenAI returns both {@code req_*} and bare UUIDs
+ * for it, so pinning its shape would be wrong.
+ */
+ private static void assertOpenAIIdsCaptured(SpanData span) {
+ var attributes = span.getAttributes();
+
+ String requestId = attributes.get(AttributeKey.stringKey("x-request-id"));
+ assertNotNull(requestId, "x-request-id header must be captured");
+ assertFalse(requestId.isBlank(), "x-request-id must not be blank");
+
+ String responseId = attributes.get(AttributeKey.stringKey("response_id"));
+ assertNotNull(responseId, "response_id must be captured from the response body");
+ assertTrue(
+ responseId.startsWith("resp_") || responseId.startsWith("chatcmpl-"),
+ "unexpected response_id: " + responseId);
+ }
+
+ /**
+ * A failed call is the case where the vendor's request id matters most, and the only one where
+ * it is the *sole* ID available: an error body carries no object id of its own. openai-java
+ * raises its exception above the HTTP layer we instrument, so the error status on the span is
+ * ours alone to set.
+ */
+ @Test
+ @SneakyThrows
+ void testHttpErrorTagsSpan() {
+ OpenAIClient openAIClient =
+ OpenAIOkHttpClient.builder()
+ .baseUrl(testHarness.openAiBaseUrl())
+ .apiKey(testHarness.openAiApiKey())
+ .build();
+
+ var request =
+ ChatCompletionCreateParams.builder()
+ .model("gpt-4o-mini-nonexistent-model")
+ .addUserMessage("What is the capital of France?")
+ .build();
+
+ assertThrows(Exception.class, () -> openAIClient.chat().completions().create(request));
+
+ var spans = testHarness.awaitExportedSpans();
+ assertEquals(1, spans.size());
+ var span = spans.get(0);
+
+ assertEquals(
+ StatusCode.ERROR,
+ span.getStatus().getStatusCode(),
+ "a non-2xx response must mark the span failed");
+
+ var attributes = span.getAttributes();
+ String requestId = attributes.get(AttributeKey.stringKey("x-request-id"));
+ assertNotNull(requestId, "x-request-id must still be captured on a failed call");
+ assertNull(
+ attributes.get(AttributeKey.stringKey("response_id")),
+ "an error body has no object id to capture");
  }
 }

braintrust-sdk/instrumentation/anthropic_2_2_0/src/main/java/dev/braintrust/instrumentation/anthropic/v2_2_0/TracingHttpClient.java

@@ -24,6 +24,9 @@
 import java.io.InputStreamReader;
 import java.io.OutputStream;
 import java.nio.charset.StandardCharsets;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.concurrent.atomic.AtomicLong;
@@ -260,10 +263,25 @@ private void onFirstByte() {
 
  private void onStreamClosed() {
  try {
+ // Scooped first and unconditionally: tagSpanFromBuffer bails on an empty body,
+ // and a failed request is both the likeliest source of one and the case where
+ // the vendor's request id is most worth having.
+ InstrumentationSemConv.tagLLMSpanIdHeaders(span, headersAsMap(delegate.headers()));
+
  byte[] bytes;
  synchronized (teeBuffer) {
  bytes = teeBuffer.toByteArray();
  }
+
+ // Recorded before tagging: the anthropic sdk raises above this layer, so the
+ // error status is ours alone to set, and losing it to a body-parsing problem is
+ // worse than losing the parsed output.
+ int statusCode = delegate.statusCode();
+ if (statusCode >= 400) {
+ InstrumentationSemConv.tagLLMSpanHttpError(
+ span, statusCode, new String(bytes, StandardCharsets.UTF_8));
+ }
+
  // tagLLMSpanResponse also emits child spans for any server-side tool calls (web
  // search, etc.) nested under the LLM span while it is still live.
  tagSpanFromBuffer(tracer, span, bytes, timeToFirstTokenNanos.get());
@@ -387,6 +405,29 @@ private static void tagSpanFromBuffer(
  }
  }
 
+ /**
+ * Adapts the anthropic sdk's {@code Headers} to the vendor-neutral shape {@link
+ * InstrumentationSemConv} consumes. Returns null on failure so a header-shape change can never
+ * take down the response tagging that follows it.
+ */
+ @Nullable
+ private static Map<String, List<String>> headersAsMap(
+ @Nullable com.anthropic.core.http.Headers headers) {
+ if (headers == null) {
+ return null;
+ }
+ try {
+ var map = new HashMap<String, List<String>>();
+ for (String name : headers.names()) {
+ map.put(name, headers.values(name));
+ }
+ return map;
+ } catch (Exception e) {
+ log.debug("could not read response headers", e);
+ return null;
+ }
+ }
+
  private static String firstNonEmptyLine(byte[] bytes) {
  int start = 0;
  for (int i = 0; i <= bytes.length; i++) {

braintrust-sdk/instrumentation/anthropic_2_2_0/src/test/java/dev/braintrust/instrumentation/anthropic/v2_2_0/BraintrustAnthropicTest.java

@@ -562,4 +562,76 @@ void testWrappedClientObjectContract() {
  wrapped.toString().contains("ContextCapturingProxy"),
  "toString should identify the proxy, got: " + wrapped);
  }
+
+ /**
+ * Anthropic returns its correlation ID as {@code request-id} (no {@code x-} prefix, unlike
+ * OpenAI) and its object ID as {@code msg_*}. Both must land on the span for streaming and
+ * non-streaming alike — the header comes off the HTTP response, the object ID out of the
+ * reassembled body, so the two travel independent paths.
+ */
+ @Test
+ @SneakyThrows
+ void testCorrelationIdsCaptured() {
+ AnthropicClient anthropicClient =
+ AnthropicOkHttpClient.builder()
+ .baseUrl(testHarness.anthropicBaseUrl())
+ .apiKey(testHarness.anthropicApiKey())
+ .build();
+
+ var request =
+ MessageCreateParams.builder()
+ .model(Model.of(TEST_MODEL))
+ .system("You are a helpful assistant")
+ .addUserMessage("What is the capital of France?")
+ .maxTokens(50)
+ .temperature(0.0)
+ .build();
+
+ anthropicClient.messages().create(request);
+ assertAnthropicIdsCaptured(testHarness.awaitExportedSpans().get(0));
+ }
+
+ @Test
+ @SneakyThrows
+ void testCorrelationIdsCapturedStreaming() {
+ AnthropicClient anthropicClient =
+ AnthropicOkHttpClient.builder()
+ .baseUrl(testHarness.anthropicBaseUrl())
+ .apiKey(testHarness.anthropicApiKey())
+ .build();
+
+ var request =
+ MessageCreateParams.builder()
+ .model(Model.of(TEST_MODEL))
+ .system("You are a helpful assistant")
+ .addUserMessage("What is the capital of France?")
+ .maxTokens(50)
+ .temperature(0.0)
+ .build();
+
+ try (var stream = anthropicClient.messages().createStreaming(request)) {
+ stream.stream().forEach(event -> {});
+ }
+ assertAnthropicIdsCaptured(testHarness.awaitExportedSpans().get(0));
+ }
+
+ /**
+ * Asserts presence only for the header: its value is an opaque vendor string, so pinning its
+ * shape would encode an assumption the provider never made.
+ */
+ private static void assertAnthropicIdsCaptured(io.opentelemetry.sdk.trace.data.SpanData span) {
+ var attributes = span.getAttributes();
+
+ String requestId = attributes.get(AttributeKey.stringKey("request-id"));
+ assertNotNull(requestId, "request-id header must be captured");
+ assertFalse(requestId.isBlank(), "request-id must not be blank");
+
+ String responseId = attributes.get(AttributeKey.stringKey("response_id"));
+ assertNotNull(responseId, "response_id must be captured from the response body");
+ assertTrue(responseId.startsWith("msg_"), "unexpected response_id: " + responseId);
+
+ assertNull(
+ attributes.get(AttributeKey.stringKey("x-request-id")),
+ "OpenAI's header name must not appear on an Anthropic span");
+ }
 }

braintrust-sdk/instrumentation/openai_2_15_0/src/main/java/dev/braintrust/instrumentation/openai/v2_15_0/TracingHttpClient.java

@@ -20,6 +20,9 @@
 import io.opentelemetry.context.Context;
 import java.io.*;
 import java.nio.charset.StandardCharsets;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.concurrent.atomic.AtomicLong;
@@ -68,7 +71,7 @@ private static ExtractedRequest extractCallerContext(HttpRequest request) {
  Context context = contextFromTraceparent(values.get(0));
  HttpRequest stripped =
  request.toBuilder()
- .replaceHeaders(ContextCapturingProxy.CONTEXT_HEADER, java.util.List.of())
+ .replaceHeaders(ContextCapturingProxy.CONTEXT_HEADER, List.of())
  .build();
  return new ExtractedRequest(stripped, context);
  }
@@ -259,6 +262,28 @@ private static void tagSpanFromBuffer(
  }
  }
 
+ /**
+ * Adapts openai-java's {@link Headers} to the vendor-neutral shape {@link
+ * InstrumentationSemConv} consumes. Returns null on failure so a header-shape change can never
+ * take down the response tagging that follows it.
+ */
+ @Nullable
+ private static Map<String, List<String>> headersAsMap(@Nullable Headers headers) {
+ if (headers == null) {
+ return null;
+ }
+ try {
+ var map = new HashMap<String, List<String>>();
+ for (String name : headers.names()) {
+ map.put(name, headers.values(name));
+ }
+ return map;
+ } catch (Exception e) {
+ log.debug("could not read response headers", e);
+ return null;
+ }
+ }
+
  private static String firstNonEmptyLine(byte[] bytes) {
  int start = 0;
  for (int i = 0; i <= bytes.length; i++) {
@@ -368,12 +393,27 @@ private void onFirstByte() {
  /** Called back by {@link TeeInputStream} when the stream is fully drained or closed. */
  private void onStreamClosed() {
  try {
+ // Scooped first and unconditionally: tagSpanFromBuffer bails on an empty body,
+ // and a failed request is both the likeliest source of one and the case where
+ // the vendor's request id is most worth having.
+ InstrumentationSemConv.tagLLMSpanIdHeaders(span, headersAsMap(delegate.headers()));
+
  // Synchronize on teeBuffer to ensure any write() that was in-flight on a
  // concurrent read thread has fully completed before we snapshot the bytes.
  byte[] bytes;
  synchronized (teeBuffer) {
  bytes = teeBuffer.toByteArray();
  }
+
+ // Recorded before tagging: openai-java raises above this layer, so the error
+ // status is ours alone to set, and losing it to a body-parsing problem is worse
+ // than losing the parsed output.
+ int statusCode = delegate.statusCode();
+ if (statusCode >= 400) {
+ InstrumentationSemConv.tagLLMSpanHttpError(
+ span, statusCode, new String(bytes, StandardCharsets.UTF_8));
+ }
+
  // tagLLMSpanResponse also emits child spans for any server-side tool calls (web
  // search, etc.) nested under the LLM span while it is still live. No-op for Chat
  // Completions responses (no `output` array).

braintrust-sdk/instrumentation/openai_2_15_0/src/test/java/dev/braintrust/instrumentation/openai/v2_15_0/BraintrustOpenAITest.java

@@ -24,6 +24,7 @@
 import dev.braintrust.TestHarness;
 import dev.braintrust.instrumentation.Instrumenter;
 import io.opentelemetry.api.common.AttributeKey;
+import io.opentelemetry.api.trace.StatusCode;
 import io.opentelemetry.sdk.trace.data.SpanData;
 import java.util.List;
 import java.util.Map;
@@ -649,5 +650,65 @@ private static void assertValidOpenAISpan(SpanData span, boolean isStreaming) {
  assertNotNull(
  attributes.get(AttributeKey.stringKey("braintrust.output_json")),
  "output must be set");
+ assertOpenAIIdsCaptured(span);
+ }
+
+ /**
+ * Both correlation IDs OpenAI hands back. Deliberately asserts only presence and the object-ID
+ * prefix: {@code x-request-id} is opaque, and OpenAI returns both {@code req_*} and bare UUIDs
+ * for it, so pinning its shape would be wrong.
+ */
+ private static void assertOpenAIIdsCaptured(SpanData span) {
+ var attributes = span.getAttributes();
+
+ String requestId = attributes.get(AttributeKey.stringKey("x-request-id"));
+ assertNotNull(requestId, "x-request-id header must be captured");
+ assertFalse(requestId.isBlank(), "x-request-id must not be blank");
+
+ String responseId = attributes.get(AttributeKey.stringKey("response_id"));
+ assertNotNull(responseId, "response_id must be captured from the response body");
+ assertTrue(
+ responseId.startsWith("resp_") || responseId.startsWith("chatcmpl-"),
+ "unexpected response_id: " + responseId);
+ }
+
+ /**
+ * A failed call is the case where the vendor's request id matters most, and the only one where
+ * it is the *sole* ID available: an error body carries no object id of its own. openai-java
+ * raises its exception above the HTTP layer we instrument, so the error status on the span is
+ * ours alone to set.
+ */
+ @Test
+ @SneakyThrows
+ void testHttpErrorTagsSpan() {
+ OpenAIClient openAIClient =
+ OpenAIOkHttpClient.builder()
+ .baseUrl(testHarness.openAiBaseUrl())
+ .apiKey(testHarness.openAiApiKey())
+ .build();
+
+ var request =
+ ChatCompletionCreateParams.builder()
+ .model("gpt-4o-mini-nonexistent-model")
+ .addUserMessage("What is the capital of France?")
+ .build();
+
+ assertThrows(Exception.class, () -> openAIClient.chat().completions().create(request));
+
+ var spans = testHarness.awaitExportedSpans();
+ assertEquals(1, spans.size());
+ var span = spans.get(0);
+
+ assertEquals(
+ StatusCode.ERROR,
+ span.getStatus().getStatusCode(),
+ "a non-2xx response must mark the span failed");
+
+ var attributes = span.getAttributes();
+ String requestId = attributes.get(AttributeKey.stringKey("x-request-id"));
+ assertNotNull(requestId, "x-request-id must still be captured on a failed call");
+ assertNull(
+ attributes.get(AttributeKey.stringKey("response_id")),
+ "an error body has no object id to capture");
  }
 }

braintrust-sdk/instrumentation/anthropic_2_2_0/src/main/java/dev/braintrust/instrumentation/anthropic/v2_2_0/TracingHttpClient.java

@@ -24,6 +24,9 @@
 import java.io.InputStreamReader;
 import java.io.OutputStream;
 import java.nio.charset.StandardCharsets;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.concurrent.atomic.AtomicLong;
@@ -260,10 +263,25 @@ private void onFirstByte() {
 
  private void onStreamClosed() {
  try {
+ // Scooped first and unconditionally: tagSpanFromBuffer bails on an empty body,
+ // and a failed request is both the likeliest source of one and the case where
+ // the vendor's request id is most worth having.
+ InstrumentationSemConv.tagLLMSpanIdHeaders(span, headersAsMap(delegate.headers()));
+
  byte[] bytes;
  synchronized (teeBuffer) {
  bytes = teeBuffer.toByteArray();
  }
+
+ // Recorded before tagging: the anthropic sdk raises above this layer, so the
+ // error status is ours alone to set, and losing it to a body-parsing problem is
+ // worse than losing the parsed output.
+ int statusCode = delegate.statusCode();
+ if (statusCode >= 400) {
+ InstrumentationSemConv.tagLLMSpanHttpError(
+ span, statusCode, new String(bytes, StandardCharsets.UTF_8));
+ }
+
  // tagLLMSpanResponse also emits child spans for any server-side tool calls (web
  // search, etc.) nested under the LLM span while it is still live.
  tagSpanFromBuffer(tracer, span, bytes, timeToFirstTokenNanos.get());
@@ -387,6 +405,29 @@ private static void tagSpanFromBuffer(
  }
  }
 
+ /**
+ * Adapts the anthropic sdk's {@code Headers} to the vendor-neutral shape {@link
+ * InstrumentationSemConv} consumes. Returns null on failure so a header-shape change can never
+ * take down the response tagging that follows it.
+ */
+ @Nullable
+ private static Map<String, List<String>> headersAsMap(
+ @Nullable com.anthropic.core.http.Headers headers) {
+ if (headers == null) {
+ return null;
+ }
+ try {
+ var map = new HashMap<String, List<String>>();
+ for (String name : headers.names()) {
+ map.put(name, headers.values(name));
+ }
+ return map;
+ } catch (Exception e) {
+ log.debug("could not read response headers", e);
+ return null;
+ }
+ }
+
  private static String firstNonEmptyLine(byte[] bytes) {
  int start = 0;
  for (int i = 0; i <= bytes.length; i++) {

braintrust-sdk/instrumentation/anthropic_2_2_0/src/test/java/dev/braintrust/instrumentation/anthropic/v2_2_0/BraintrustAnthropicTest.java

@@ -562,4 +562,76 @@ void testWrappedClientObjectContract() {
  wrapped.toString().contains("ContextCapturingProxy"),
  "toString should identify the proxy, got: " + wrapped);
  }
+
+ /**
+ * Anthropic returns its correlation ID as {@code request-id} (no {@code x-} prefix, unlike
+ * OpenAI) and its object ID as {@code msg_*}. Both must land on the span for streaming and
+ * non-streaming alike — the header comes off the HTTP response, the object ID out of the
+ * reassembled body, so the two travel independent paths.
+ */
+ @Test
+ @SneakyThrows
+ void testCorrelationIdsCaptured() {
+ AnthropicClient anthropicClient =
+ AnthropicOkHttpClient.builder()
+ .baseUrl(testHarness.anthropicBaseUrl())
+ .apiKey(testHarness.anthropicApiKey())
+ .build();
+
+ var request =
+ MessageCreateParams.builder()
+ .model(Model.of(TEST_MODEL))
+ .system("You are a helpful assistant")
+ .addUserMessage("What is the capital of France?")
+ .maxTokens(50)
+ .temperature(0.0)
+ .build();
+
+ anthropicClient.messages().create(request);
+ assertAnthropicIdsCaptured(testHarness.awaitExportedSpans().get(0));
+ }
+
+ @Test
+ @SneakyThrows
+ void testCorrelationIdsCapturedStreaming() {
+ AnthropicClient anthropicClient =
+ AnthropicOkHttpClient.builder()
+ .baseUrl(testHarness.anthropicBaseUrl())
+ .apiKey(testHarness.anthropicApiKey())
+ .build();
+
+ var request =
+ MessageCreateParams.builder()
+ .model(Model.of(TEST_MODEL))
+ .system("You are a helpful assistant")
+ .addUserMessage("What is the capital of France?")
+ .maxTokens(50)
+ .temperature(0.0)
+ .build();
+
+ try (var stream = anthropicClient.messages().createStreaming(request)) {
+ stream.stream().forEach(event -> {});
+ }
+ assertAnthropicIdsCaptured(testHarness.awaitExportedSpans().get(0));
+ }
+
+ /**
+ * Asserts presence only for the header: its value is an opaque vendor string, so pinning its
+ * shape would encode an assumption the provider never made.
+ */
+ private static void assertAnthropicIdsCaptured(io.opentelemetry.sdk.trace.data.SpanData span) {
+ var attributes = span.getAttributes();
+
+ String requestId = attributes.get(AttributeKey.stringKey("request-id"));
+ assertNotNull(requestId, "request-id header must be captured");
+ assertFalse(requestId.isBlank(), "request-id must not be blank");
+
+ String responseId = attributes.get(AttributeKey.stringKey("response_id"));
+ assertNotNull(responseId, "response_id must be captured from the response body");
+ assertTrue(responseId.startsWith("msg_"), "unexpected response_id: " + responseId);
+
+ assertNull(
+ attributes.get(AttributeKey.stringKey("x-request-id")),
+ "OpenAI's header name must not appear on an Anthropic span");
+ }
 }

braintrust-sdk/instrumentation/openai_2_15_0/src/main/java/dev/braintrust/instrumentation/openai/v2_15_0/TracingHttpClient.java

@@ -20,6 +20,9 @@
 import io.opentelemetry.context.Context;
 import java.io.*;
 import java.nio.charset.StandardCharsets;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.concurrent.atomic.AtomicLong;
@@ -68,7 +71,7 @@ private static ExtractedRequest extractCallerContext(HttpRequest request) {
  Context context = contextFromTraceparent(values.get(0));
  HttpRequest stripped =
  request.toBuilder()
- .replaceHeaders(ContextCapturingProxy.CONTEXT_HEADER, java.util.List.of())
+ .replaceHeaders(ContextCapturingProxy.CONTEXT_HEADER, List.of())
  .build();
  return new ExtractedRequest(stripped, context);
  }
@@ -259,6 +262,28 @@ private static void tagSpanFromBuffer(
  }
  }
 
+ /**
+ * Adapts openai-java's {@link Headers} to the vendor-neutral shape {@link
+ * InstrumentationSemConv} consumes. Returns null on failure so a header-shape change can never
+ * take down the response tagging that follows it.
+ */
+ @Nullable
+ private static Map<String, List<String>> headersAsMap(@Nullable Headers headers) {
+ if (headers == null) {
+ return null;
+ }
+ try {
+ var map = new HashMap<String, List<String>>();
+ for (String name : headers.names()) {
+ map.put(name, headers.values(name));
+ }
+ return map;
+ } catch (Exception e) {
+ log.debug("could not read response headers", e);
+ return null;
+ }
+ }
+
  private static String firstNonEmptyLine(byte[] bytes) {
  int start = 0;
  for (int i = 0; i <= bytes.length; i++) {
@@ -368,12 +393,27 @@ private void onFirstByte() {
  /** Called back by {@link TeeInputStream} when the stream is fully drained or closed. */
  private void onStreamClosed() {
  try {
+ // Scooped first and unconditionally: tagSpanFromBuffer bails on an empty body,
+ // and a failed request is both the likeliest source of one and the case where
+ // the vendor's request id is most worth having.
+ InstrumentationSemConv.tagLLMSpanIdHeaders(span, headersAsMap(delegate.headers()));
+
  // Synchronize on teeBuffer to ensure any write() that was in-flight on a
  // concurrent read thread has fully completed before we snapshot the bytes.
  byte[] bytes;
  synchronized (teeBuffer) {
  bytes = teeBuffer.toByteArray();
  }
+
+ // Recorded before tagging: openai-java raises above this layer, so the error
+ // status is ours alone to set, and losing it to a body-parsing problem is worse
+ // than losing the parsed output.
+ int statusCode = delegate.statusCode();
+ if (statusCode >= 400) {
+ InstrumentationSemConv.tagLLMSpanHttpError(
+ span, statusCode, new String(bytes, StandardCharsets.UTF_8));
+ }
+
  // tagLLMSpanResponse also emits child spans for any server-side tool calls (web
  // search, etc.) nested under the LLM span while it is still live. No-op for Chat
  // Completions responses (no `output` array).

braintrust-sdk/instrumentation/openai_2_15_0/src/test/java/dev/braintrust/instrumentation/openai/v2_15_0/BraintrustOpenAITest.java

@@ -24,6 +24,7 @@
 import dev.braintrust.TestHarness;
 import dev.braintrust.instrumentation.Instrumenter;
 import io.opentelemetry.api.common.AttributeKey;
+import io.opentelemetry.api.trace.StatusCode;
 import io.opentelemetry.sdk.trace.data.SpanData;
 import java.util.List;
 import java.util.Map;
@@ -649,5 +650,65 @@ private static void assertValidOpenAISpan(SpanData span, boolean isStreaming) {
  assertNotNull(
  attributes.get(AttributeKey.stringKey("braintrust.output_json")),
  "output must be set");
+ assertOpenAIIdsCaptured(span);
+ }
+
+ /**
+ * Both correlation IDs OpenAI hands back. Deliberately asserts only presence and the object-ID
+ * prefix: {@code x-request-id} is opaque, and OpenAI returns both {@code req_*} and bare UUIDs
+ * for it, so pinning its shape would be wrong.
+ */
+ private static void assertOpenAIIdsCaptured(SpanData span) {
+ var attributes = span.getAttributes();
+
+ String requestId = attributes.get(AttributeKey.stringKey("x-request-id"));
+ assertNotNull(requestId, "x-request-id header must be captured");
+ assertFalse(requestId.isBlank(), "x-request-id must not be blank");
+
+ String responseId = attributes.get(AttributeKey.stringKey("response_id"));
+ assertNotNull(responseId, "response_id must be captured from the response body");
+ assertTrue(
+ responseId.startsWith("resp_") || responseId.startsWith("chatcmpl-"),
+ "unexpected response_id: " + responseId);
+ }
+
+ /**
+ * A failed call is the case where the vendor's request id matters most, and the only one where
+ * it is the *sole* ID available: an error body carries no object id of its own. openai-java
+ * raises its exception above the HTTP layer we instrument, so the error status on the span is
+ * ours alone to set.
+ */
+ @Test
+ @SneakyThrows
+ void testHttpErrorTagsSpan() {
+ OpenAIClient openAIClient =
+ OpenAIOkHttpClient.builder()
+ .baseUrl(testHarness.openAiBaseUrl())
+ .apiKey(testHarness.openAiApiKey())
+ .build();
+
+ var request =
+ ChatCompletionCreateParams.builder()
+ .model("gpt-4o-mini-nonexistent-model")
+ .addUserMessage("What is the capital of France?")
+ .build();
+
+ assertThrows(Exception.class, () -> openAIClient.chat().completions().create(request));
+
+ var spans = testHarness.awaitExportedSpans();
+ assertEquals(1, spans.size());
+ var span = spans.get(0);
+
+ assertEquals(
+ StatusCode.ERROR,
+ span.getStatus().getStatusCode(),
+ "a non-2xx response must mark the span failed");
+
+ var attributes = span.getAttributes();
+ String requestId = attributes.get(AttributeKey.stringKey("x-request-id"));
+ assertNotNull(requestId, "x-request-id must still be captured on a failed call");
+ assertNull(
+ attributes.get(AttributeKey.stringKey("response_id")),
+ "an error body has no object id to capture");
  }
 }

braintrust-sdk/instrumentation/anthropic_2_2_0/src/main/java/dev/braintrust/instrumentation/anthropic/v2_2_0/TracingHttpClient.java

@@ -24,6 +24,9 @@
 import java.io.InputStreamReader;
 import java.io.OutputStream;
 import java.nio.charset.StandardCharsets;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.concurrent.atomic.AtomicLong;
@@ -260,10 +263,25 @@ private void onFirstByte() {
 
  private void onStreamClosed() {
  try {
+ // Scooped first and unconditionally: tagSpanFromBuffer bails on an empty body,
+ // and a failed request is both the likeliest source of one and the case where
+ // the vendor's request id is most worth having.
+ InstrumentationSemConv.tagLLMSpanIdHeaders(span, headersAsMap(delegate.headers()));
+
  byte[] bytes;
  synchronized (teeBuffer) {
  bytes = teeBuffer.toByteArray();
  }
+
+ // Recorded before tagging: the anthropic sdk raises above this layer, so the
+ // error status is ours alone to set, and losing it to a body-parsing problem is
+ // worse than losing the parsed output.
+ int statusCode = delegate.statusCode();
+ if (statusCode >= 400) {
+ InstrumentationSemConv.tagLLMSpanHttpError(
+ span, statusCode, new String(bytes, StandardCharsets.UTF_8));
+ }
+
  // tagLLMSpanResponse also emits child spans for any server-side tool calls (web
  // search, etc.) nested under the LLM span while it is still live.
  tagSpanFromBuffer(tracer, span, bytes, timeToFirstTokenNanos.get());
@@ -387,6 +405,29 @@ private static void tagSpanFromBuffer(
  }
  }
 
+ /**
+ * Adapts the anthropic sdk's {@code Headers} to the vendor-neutral shape {@link
+ * InstrumentationSemConv} consumes. Returns null on failure so a header-shape change can never
+ * take down the response tagging that follows it.
+ */
+ @Nullable
+ private static Map<String, List<String>> headersAsMap(
+ @Nullable com.anthropic.core.http.Headers headers) {
+ if (headers == null) {
+ return null;
+ }
+ try {
+ var map = new HashMap<String, List<String>>();
+ for (String name : headers.names()) {
+ map.put(name, headers.values(name));
+ }
+ return map;
+ } catch (Exception e) {
+ log.debug("could not read response headers", e);
+ return null;
+ }
+ }
+
  private static String firstNonEmptyLine(byte[] bytes) {
  int start = 0;
  for (int i = 0; i <= bytes.length; i++) {

braintrust-sdk/instrumentation/anthropic_2_2_0/src/test/java/dev/braintrust/instrumentation/anthropic/v2_2_0/BraintrustAnthropicTest.java

@@ -562,4 +562,76 @@ void testWrappedClientObjectContract() {
  wrapped.toString().contains("ContextCapturingProxy"),
  "toString should identify the proxy, got: " + wrapped);
  }
+
+ /**
+ * Anthropic returns its correlation ID as {@code request-id} (no {@code x-} prefix, unlike
+ * OpenAI) and its object ID as {@code msg_*}. Both must land on the span for streaming and
+ * non-streaming alike — the header comes off the HTTP response, the object ID out of the
+ * reassembled body, so the two travel independent paths.
+ */
+ @Test
+ @SneakyThrows
+ void testCorrelationIdsCaptured() {
+ AnthropicClient anthropicClient =
+ AnthropicOkHttpClient.builder()
+ .baseUrl(testHarness.anthropicBaseUrl())
+ .apiKey(testHarness.anthropicApiKey())
+ .build();
+
+ var request =
+ MessageCreateParams.builder()
+ .model(Model.of(TEST_MODEL))
+ .system("You are a helpful assistant")
+ .addUserMessage("What is the capital of France?")
+ .maxTokens(50)
+ .temperature(0.0)
+ .build();
+
+ anthropicClient.messages().create(request);
+ assertAnthropicIdsCaptured(testHarness.awaitExportedSpans().get(0));
+ }
+
+ @Test
+ @SneakyThrows
+ void testCorrelationIdsCapturedStreaming() {
+ AnthropicClient anthropicClient =
+ AnthropicOkHttpClient.builder()
+ .baseUrl(testHarness.anthropicBaseUrl())
+ .apiKey(testHarness.anthropicApiKey())
+ .build();
+
+ var request =
+ MessageCreateParams.builder()
+ .model(Model.of(TEST_MODEL))
+ .system("You are a helpful assistant")
+ .addUserMessage("What is the capital of France?")
+ .maxTokens(50)
+ .temperature(0.0)
+ .build();
+
+ try (var stream = anthropicClient.messages().createStreaming(request)) {
+ stream.stream().forEach(event -> {});
+ }
+ assertAnthropicIdsCaptured(testHarness.awaitExportedSpans().get(0));
+ }
+
+ /**
+ * Asserts presence only for the header: its value is an opaque vendor string, so pinning its
+ * shape would encode an assumption the provider never made.
+ */
+ private static void assertAnthropicIdsCaptured(io.opentelemetry.sdk.trace.data.SpanData span) {
+ var attributes = span.getAttributes();
+
+ String requestId = attributes.get(AttributeKey.stringKey("request-id"));
+ assertNotNull(requestId, "request-id header must be captured");
+ assertFalse(requestId.isBlank(), "request-id must not be blank");
+
+ String responseId = attributes.get(AttributeKey.stringKey("response_id"));
+ assertNotNull(responseId, "response_id must be captured from the response body");
+ assertTrue(responseId.startsWith("msg_"), "unexpected response_id: " + responseId);
+
+ assertNull(
+ attributes.get(AttributeKey.stringKey("x-request-id")),
+ "OpenAI's header name must not appear on an Anthropic span");
+ }
 }

braintrust-sdk/instrumentation/openai_2_15_0/src/main/java/dev/braintrust/instrumentation/openai/v2_15_0/TracingHttpClient.java

@@ -20,6 +20,9 @@
 import io.opentelemetry.context.Context;
 import java.io.*;
 import java.nio.charset.StandardCharsets;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.concurrent.atomic.AtomicLong;
@@ -68,7 +71,7 @@ private static ExtractedRequest extractCallerContext(HttpRequest request) {
  Context context = contextFromTraceparent(values.get(0));
  HttpRequest stripped =
  request.toBuilder()
- .replaceHeaders(ContextCapturingProxy.CONTEXT_HEADER, java.util.List.of())
+ .replaceHeaders(ContextCapturingProxy.CONTEXT_HEADER, List.of())
  .build();
  return new ExtractedRequest(stripped, context);
  }
@@ -259,6 +262,28 @@ private static void tagSpanFromBuffer(
  }
  }
 
+ /**
+ * Adapts openai-java's {@link Headers} to the vendor-neutral shape {@link
+ * InstrumentationSemConv} consumes. Returns null on failure so a header-shape change can never
+ * take down the response tagging that follows it.
+ */
+ @Nullable
+ private static Map<String, List<String>> headersAsMap(@Nullable Headers headers) {
+ if (headers == null) {
+ return null;
+ }
+ try {
+ var map = new HashMap<String, List<String>>();
+ for (String name : headers.names()) {
+ map.put(name, headers.values(name));
+ }
+ return map;
+ } catch (Exception e) {
+ log.debug("could not read response headers", e);
+ return null;
+ }
+ }
+
  private static String firstNonEmptyLine(byte[] bytes) {
  int start = 0;
  for (int i = 0; i <= bytes.length; i++) {
@@ -368,12 +393,27 @@ private void onFirstByte() {
  /** Called back by {@link TeeInputStream} when the stream is fully drained or closed. */
  private void onStreamClosed() {
  try {
+ // Scooped first and unconditionally: tagSpanFromBuffer bails on an empty body,
+ // and a failed request is both the likeliest source of one and the case where
+ // the vendor's request id is most worth having.
+ InstrumentationSemConv.tagLLMSpanIdHeaders(span, headersAsMap(delegate.headers()));
+
  // Synchronize on teeBuffer to ensure any write() that was in-flight on a
  // concurrent read thread has fully completed before we snapshot the bytes.
  byte[] bytes;
  synchronized (teeBuffer) {
  bytes = teeBuffer.toByteArray();
  }
+
+ // Recorded before tagging: openai-java raises above this layer, so the error
+ // status is ours alone to set, and losing it to a body-parsing problem is worse
+ // than losing the parsed output.
+ int statusCode = delegate.statusCode();
+ if (statusCode >= 400) {
+ InstrumentationSemConv.tagLLMSpanHttpError(
+ span, statusCode, new String(bytes, StandardCharsets.UTF_8));
+ }
+
  // tagLLMSpanResponse also emits child spans for any server-side tool calls (web
  // search, etc.) nested under the LLM span while it is still live. No-op for Chat
  // Completions responses (no `output` array).

braintrust-sdk/instrumentation/openai_2_15_0/src/test/java/dev/braintrust/instrumentation/openai/v2_15_0/BraintrustOpenAITest.java

@@ -24,6 +24,7 @@
 import dev.braintrust.TestHarness;
 import dev.braintrust.instrumentation.Instrumenter;
 import io.opentelemetry.api.common.AttributeKey;
+import io.opentelemetry.api.trace.StatusCode;
 import io.opentelemetry.sdk.trace.data.SpanData;
 import java.util.List;
 import java.util.Map;
@@ -649,5 +650,65 @@ private static void assertValidOpenAISpan(SpanData span, boolean isStreaming) {
  assertNotNull(
  attributes.get(AttributeKey.stringKey("braintrust.output_json")),
  "output must be set");
+ assertOpenAIIdsCaptured(span);
+ }
+
+ /**
+ * Both correlation IDs OpenAI hands back. Deliberately asserts only presence and the object-ID
+ * prefix: {@code x-request-id} is opaque, and OpenAI returns both {@code req_*} and bare UUIDs
+ * for it, so pinning its shape would be wrong.
+ */
+ private static void assertOpenAIIdsCaptured(SpanData span) {
+ var attributes = span.getAttributes();
+
+ String requestId = attributes.get(AttributeKey.stringKey("x-request-id"));
+ assertNotNull(requestId, "x-request-id header must be captured");
+ assertFalse(requestId.isBlank(), "x-request-id must not be blank");
+
+ String responseId = attributes.get(AttributeKey.stringKey("response_id"));
+ assertNotNull(responseId, "response_id must be captured from the response body");
+ assertTrue(
+ responseId.startsWith("resp_") || responseId.startsWith("chatcmpl-"),
+ "unexpected response_id: " + responseId);
+ }
+
+ /**
+ * A failed call is the case where the vendor's request id matters most, and the only one where
+ * it is the *sole* ID available: an error body carries no object id of its own. openai-java
+ * raises its exception above the HTTP layer we instrument, so the error status on the span is
+ * ours alone to set.
+ */
+ @Test
+ @SneakyThrows
+ void testHttpErrorTagsSpan() {
+ OpenAIClient openAIClient =
+ OpenAIOkHttpClient.builder()
+ .baseUrl(testHarness.openAiBaseUrl())
+ .apiKey(testHarness.openAiApiKey())
+ .build();
+
+ var request =
+ ChatCompletionCreateParams.builder()
+ .model("gpt-4o-mini-nonexistent-model")
+ .addUserMessage("What is the capital of France?")
+ .build();
+
+ assertThrows(Exception.class, () -> openAIClient.chat().completions().create(request));
+
+ var spans = testHarness.awaitExportedSpans();
+ assertEquals(1, spans.size());
+ var span = spans.get(0);
+
+ assertEquals(
+ StatusCode.ERROR,
+ span.getStatus().getStatusCode(),
+ "a non-2xx response must mark the span failed");
+
+ var attributes = span.getAttributes();
+ String requestId = attributes.get(AttributeKey.stringKey("x-request-id"));
+ assertNotNull(requestId, "x-request-id must still be captured on a failed call");
+ assertNull(
+ attributes.get(AttributeKey.stringKey("response_id")),
+ "an error body has no object id to capture");
  }
 }

braintrust-sdk/instrumentation/anthropic_2_2_0/src/main/java/dev/braintrust/instrumentation/anthropic/v2_2_0/TracingHttpClient.java

@@ -24,6 +24,9 @@
 import java.io.InputStreamReader;
 import java.io.OutputStream;
 import java.nio.charset.StandardCharsets;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.concurrent.atomic.AtomicLong;
@@ -260,10 +263,25 @@ private void onFirstByte() {
 
  private void onStreamClosed() {
  try {
+ // Scooped first and unconditionally: tagSpanFromBuffer bails on an empty body,
+ // and a failed request is both the likeliest source of one and the case where
+ // the vendor's request id is most worth having.
+ InstrumentationSemConv.tagLLMSpanIdHeaders(span, headersAsMap(delegate.headers()));
+
  byte[] bytes;
  synchronized (teeBuffer) {
  bytes = teeBuffer.toByteArray();
  }
+
+ // Recorded before tagging: the anthropic sdk raises above this layer, so the
+ // error status is ours alone to set, and losing it to a body-parsing problem is
+ // worse than losing the parsed output.
+ int statusCode = delegate.statusCode();
+ if (statusCode >= 400) {
+ InstrumentationSemConv.tagLLMSpanHttpError(
+ span, statusCode, new String(bytes, StandardCharsets.UTF_8));
+ }
+
  // tagLLMSpanResponse also emits child spans for any server-side tool calls (web
  // search, etc.) nested under the LLM span while it is still live.
  tagSpanFromBuffer(tracer, span, bytes, timeToFirstTokenNanos.get());
@@ -387,6 +405,29 @@ private static void tagSpanFromBuffer(
  }
  }
 
+ /**
+ * Adapts the anthropic sdk's {@code Headers} to the vendor-neutral shape {@link
+ * InstrumentationSemConv} consumes. Returns null on failure so a header-shape change can never
+ * take down the response tagging that follows it.
+ */
+ @Nullable
+ private static Map<String, List<String>> headersAsMap(
+ @Nullable com.anthropic.core.http.Headers headers) {
+ if (headers == null) {
+ return null;
+ }
+ try {
+ var map = new HashMap<String, List<String>>();
+ for (String name : headers.names()) {
+ map.put(name, headers.values(name));
+ }
+ return map;
+ } catch (Exception e) {
+ log.debug("could not read response headers", e);
+ return null;
+ }
+ }
+
  private static String firstNonEmptyLine(byte[] bytes) {
  int start = 0;
  for (int i = 0; i <= bytes.length; i++) {

braintrust-sdk/instrumentation/anthropic_2_2_0/src/test/java/dev/braintrust/instrumentation/anthropic/v2_2_0/BraintrustAnthropicTest.java

@@ -562,4 +562,76 @@ void testWrappedClientObjectContract() {
  wrapped.toString().contains("ContextCapturingProxy"),
  "toString should identify the proxy, got: " + wrapped);
  }
+
+ /**
+ * Anthropic returns its correlation ID as {@code request-id} (no {@code x-} prefix, unlike
+ * OpenAI) and its object ID as {@code msg_*}. Both must land on the span for streaming and
+ * non-streaming alike — the header comes off the HTTP response, the object ID out of the
+ * reassembled body, so the two travel independent paths.
+ */
+ @Test
+ @SneakyThrows
+ void testCorrelationIdsCaptured() {
+ AnthropicClient anthropicClient =
+ AnthropicOkHttpClient.builder()
+ .baseUrl(testHarness.anthropicBaseUrl())
+ .apiKey(testHarness.anthropicApiKey())
+ .build();
+
+ var request =
+ MessageCreateParams.builder()
+ .model(Model.of(TEST_MODEL))
+ .system("You are a helpful assistant")
+ .addUserMessage("What is the capital of France?")
+ .maxTokens(50)
+ .temperature(0.0)
+ .build();
+
+ anthropicClient.messages().create(request);
+ assertAnthropicIdsCaptured(testHarness.awaitExportedSpans().get(0));
+ }
+
+ @Test
+ @SneakyThrows
+ void testCorrelationIdsCapturedStreaming() {
+ AnthropicClient anthropicClient =
+ AnthropicOkHttpClient.builder()
+ .baseUrl(testHarness.anthropicBaseUrl())
+ .apiKey(testHarness.anthropicApiKey())
+ .build();
+
+ var request =
+ MessageCreateParams.builder()
+ .model(Model.of(TEST_MODEL))
+ .system("You are a helpful assistant")
+ .addUserMessage("What is the capital of France?")
+ .maxTokens(50)
+ .temperature(0.0)
+ .build();
+
+ try (var stream = anthropicClient.messages().createStreaming(request)) {
+ stream.stream().forEach(event -> {});
+ }
+ assertAnthropicIdsCaptured(testHarness.awaitExportedSpans().get(0));
+ }
+
+ /**
+ * Asserts presence only for the header: its value is an opaque vendor string, so pinning its
+ * shape would encode an assumption the provider never made.
+ */
+ private static void assertAnthropicIdsCaptured(io.opentelemetry.sdk.trace.data.SpanData span) {
+ var attributes = span.getAttributes();
+
+ String requestId = attributes.get(AttributeKey.stringKey("request-id"));
+ assertNotNull(requestId, "request-id header must be captured");
+ assertFalse(requestId.isBlank(), "request-id must not be blank");
+
+ String responseId = attributes.get(AttributeKey.stringKey("response_id"));
+ assertNotNull(responseId, "response_id must be captured from the response body");
+ assertTrue(responseId.startsWith("msg_"), "unexpected response_id: " + responseId);
+
+ assertNull(
+ attributes.get(AttributeKey.stringKey("x-request-id")),
+ "OpenAI's header name must not appear on an Anthropic span");
+ }
 }

braintrust-sdk/instrumentation/openai_2_15_0/src/main/java/dev/braintrust/instrumentation/openai/v2_15_0/TracingHttpClient.java

@@ -20,6 +20,9 @@
 import io.opentelemetry.context.Context;
 import java.io.*;
 import java.nio.charset.StandardCharsets;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.concurrent.atomic.AtomicLong;
@@ -68,7 +71,7 @@ private static ExtractedRequest extractCallerContext(HttpRequest request) {
  Context context = contextFromTraceparent(values.get(0));
  HttpRequest stripped =
  request.toBuilder()
- .replaceHeaders(ContextCapturingProxy.CONTEXT_HEADER, java.util.List.of())
+ .replaceHeaders(ContextCapturingProxy.CONTEXT_HEADER, List.of())
  .build();
  return new ExtractedRequest(stripped, context);
  }
@@ -259,6 +262,28 @@ private static void tagSpanFromBuffer(
  }
  }
 
+ /**
+ * Adapts openai-java's {@link Headers} to the vendor-neutral shape {@link
+ * InstrumentationSemConv} consumes. Returns null on failure so a header-shape change can never
+ * take down the response tagging that follows it.
+ */
+ @Nullable
+ private static Map<String, List<String>> headersAsMap(@Nullable Headers headers) {
+ if (headers == null) {
+ return null;
+ }
+ try {
+ var map = new HashMap<String, List<String>>();
+ for (String name : headers.names()) {
+ map.put(name, headers.values(name));
+ }
+ return map;
+ } catch (Exception e) {
+ log.debug("could not read response headers", e);
+ return null;
+ }
+ }
+
  private static String firstNonEmptyLine(byte[] bytes) {
  int start = 0;
  for (int i = 0; i <= bytes.length; i++) {
@@ -368,12 +393,27 @@ private void onFirstByte() {
  /** Called back by {@link TeeInputStream} when the stream is fully drained or closed. */
  private void onStreamClosed() {
  try {
+ // Scooped first and unconditionally: tagSpanFromBuffer bails on an empty body,
+ // and a failed request is both the likeliest source of one and the case where
+ // the vendor's request id is most worth having.
+ InstrumentationSemConv.tagLLMSpanIdHeaders(span, headersAsMap(delegate.headers()));
+
  // Synchronize on teeBuffer to ensure any write() that was in-flight on a
  // concurrent read thread has fully completed before we snapshot the bytes.
  byte[] bytes;
  synchronized (teeBuffer) {
  bytes = teeBuffer.toByteArray();
  }
+
+ // Recorded before tagging: openai-java raises above this layer, so the error
+ // status is ours alone to set, and losing it to a body-parsing problem is worse
+ // than losing the parsed output.
+ int statusCode = delegate.statusCode();
+ if (statusCode >= 400) {
+ InstrumentationSemConv.tagLLMSpanHttpError(
+ span, statusCode, new String(bytes, StandardCharsets.UTF_8));
+ }
+
  // tagLLMSpanResponse also emits child spans for any server-side tool calls (web
  // search, etc.) nested under the LLM span while it is still live. No-op for Chat
  // Completions responses (no `output` array).

braintrust-sdk/instrumentation/openai_2_15_0/src/test/java/dev/braintrust/instrumentation/openai/v2_15_0/BraintrustOpenAITest.java

@@ -24,6 +24,7 @@
 import dev.braintrust.TestHarness;
 import dev.braintrust.instrumentation.Instrumenter;
 import io.opentelemetry.api.common.AttributeKey;
+import io.opentelemetry.api.trace.StatusCode;
 import io.opentelemetry.sdk.trace.data.SpanData;
 import java.util.List;
 import java.util.Map;
@@ -649,5 +650,65 @@ private static void assertValidOpenAISpan(SpanData span, boolean isStreaming) {
  assertNotNull(
  attributes.get(AttributeKey.stringKey("braintrust.output_json")),
  "output must be set");
+ assertOpenAIIdsCaptured(span);
+ }
+
+ /**
+ * Both correlation IDs OpenAI hands back. Deliberately asserts only presence and the object-ID
+ * prefix: {@code x-request-id} is opaque, and OpenAI returns both {@code req_*} and bare UUIDs
+ * for it, so pinning its shape would be wrong.
+ */
+ private static void assertOpenAIIdsCaptured(SpanData span) {
+ var attributes = span.getAttributes();
+
+ String requestId = attributes.get(AttributeKey.stringKey("x-request-id"));
+ assertNotNull(requestId, "x-request-id header must be captured");
+ assertFalse(requestId.isBlank(), "x-request-id must not be blank");
+
+ String responseId = attributes.get(AttributeKey.stringKey("response_id"));
+ assertNotNull(responseId, "response_id must be captured from the response body");
+ assertTrue(
+ responseId.startsWith("resp_") || responseId.startsWith("chatcmpl-"),
+ "unexpected response_id: " + responseId);
+ }
+
+ /**
+ * A failed call is the case where the vendor's request id matters most, and the only one where
+ * it is the *sole* ID available: an error body carries no object id of its own. openai-java
+ * raises its exception above the HTTP layer we instrument, so the error status on the span is
+ * ours alone to set.
+ */
+ @Test
+ @SneakyThrows
+ void testHttpErrorTagsSpan() {
+ OpenAIClient openAIClient =
+ OpenAIOkHttpClient.builder()
+ .baseUrl(testHarness.openAiBaseUrl())
+ .apiKey(testHarness.openAiApiKey())
+ .build();
+
+ var request =
+ ChatCompletionCreateParams.builder()
+ .model("gpt-4o-mini-nonexistent-model")
+ .addUserMessage("What is the capital of France?")
+ .build();
+
+ assertThrows(Exception.class, () -> openAIClient.chat().completions().create(request));
+
+ var spans = testHarness.awaitExportedSpans();
+ assertEquals(1, spans.size());
+ var span = spans.get(0);
+
+ assertEquals(
+ StatusCode.ERROR,
+ span.getStatus().getStatusCode(),
+ "a non-2xx response must mark the span failed");
+
+ var attributes = span.getAttributes();
+ String requestId = attributes.get(AttributeKey.stringKey("x-request-id"));
+ assertNotNull(requestId, "x-request-id must still be captured on a failed call");
+ assertNull(
+ attributes.get(AttributeKey.stringKey("response_id")),
+ "an error body has no object id to capture");
  }
 }