add request id to openai llm span attributes#172

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Andrew Kent (realark) merged 2 commits into from
Aug 27, 2026
Merged

add request id to openai llm span attributes #172

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e49d40a
VCR
realark Aug 26, 2026
4bbcc2e
tag vendor ids on openai and anthropic llm spans
realark Aug 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion AGENTS.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -160,11 +160,12 @@ VCR_MODE=record ./gradlew :braintrust-sdk:test --tests 'dev.braintrust.devserver
- when running btx, use the spec filter to target what is specifically under development: `VCR_MODE=off ./gradlew :btx:test -Pbtx.spec.filter=openai/prompt_cach --rerun`
- don't reformat the whole repo, but do run `./gradlew spotlessApply` on files you changed before committing. the pre-commit hook and `./gradlew check` both run `spotlessCheck`, which fails on unformatted code.

## Gotchas
## Misc Tips and Best Practices

- **don't hand-edit cassettes.** they're content-hashed and guarded against committed secrets. a failing VCR test means the recorded interaction changed — re-record it (see the VCR section), don't patch the json.
- **`braintrust-api` is generated code.** don't edit sources under it by hand; it's regenerated from the braintrust openapi spec pinned as `braintrustOpenApiRef` in gradle.properties.
- **there are no version constants to bump.** the sdk version is derived from git tags at build time (`generateVersion()` in build.gradle) and written into braintrust.properties. "bump the version" is not a source change.
- When adding test cases, favor adding to the test file of the module being changed rather than making a new file. For example, if you fix a bug in the `Foo` module, add the test case to `FooTest.java` instead of making a new file, `FooTestMyBuggyCase.java`

## Releasing

Expand Down
117 changes: 117 additions & 0 deletions ..._0/src/main/java/dev/braintrust/instrumentation/anthropic/v2_2_0/ResponseReassembler.java
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
package dev.braintrust.instrumentation.anthropic.v2_2_0;

import com.anthropic.helpers.MessageAccumulator;
import com.anthropic.models.messages.RawMessageStreamEvent;
import dev.braintrust.json.BraintrustJsonMapper;
import java.io.BufferedReader;
import java.io.ByteArrayInputStream;
import java.io.InputStreamReader;
import java.nio.charset.StandardCharsets;
import javax.annotation.Nullable;
import lombok.extern.slf4j.Slf4j;

/**
* Turns the raw bytes of an Anthropic response into a single JSON document the semconv layer can
* tag.
*
* <p>All of the wire-format bookkeeping lives here — SSE-vs-plain-JSON detection and chunk
* reassembly — so that {@code TracingHttpClient} is left holding only the span lifecycle and one
* flat call into {@code InstrumentationSemConv}.
*/
@Slf4j
class ResponseReassembler {

private ResponseReassembler() {}

/**
* A reassembled response body plus the timing that belongs with it.
*
* <p>{@code body} is null when there was nothing usable to reassemble — an empty response, or
* one we couldn't parse. Callers should still tag the response in that case; the headers remain
* worth recording.
*
* <p>{@code timeToFirstTokenNanos} is only populated for a stream, since a non-streaming
* response has no first token to time.
*/
record Result(@Nullable String body, @Nullable Long timeToFirstTokenNanos) {
static final Result EMPTY = new Result(null, null);
}

/** Detects the wire format and reassembles accordingly. Never throws. */
static Result reassemble(byte[] bytes, long timeToFirstTokenNanos) {
if (bytes.length == 0) {
return Result.EMPTY;
}
try {
String firstLine = firstNonEmptyLine(bytes);
// Anthropic SSE starts with "event: message_start\ndata: ..." so we detect either
// prefix. OpenAI SSE starts directly with "data:".
boolean isSse =
firstLine != null
&& (firstLine.startsWith("data:") || firstLine.startsWith("event:"));
if (isSse) {
return new Result(reassembleSse(bytes), timeToFirstTokenNanos);
}
// Non-streaming: plain Message JSON — pass it whole, no time_to_first_token
return new Result(new String(bytes, StandardCharsets.UTF_8), null);
} catch (Exception e) {
log.error("Could not reassemble Anthropic response buffer", e);
return Result.EMPTY;
}
}

@Nullable
private static String firstNonEmptyLine(byte[] bytes) {
int start = 0;
for (int i = 0; i <= bytes.length; i++) {
if (i == bytes.length || bytes[i] == '\n') {
String line = new String(bytes, start, i - start, StandardCharsets.UTF_8).strip();
if (!line.isEmpty()) return line;
start = i + 1;
}
}
return null;
}

/**
* Anthropic SSE wire format has named events:
*
* <pre>
* event: message_start
* data: {"type":"message_start","message":{...}}
*
* event: content_block_delta
* data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hi"}}
* </pre>
*
* We only need the {@code data:} lines — the event name is redundant with the {@code type}
* field inside the JSON. Feed each data payload to {@link MessageAccumulator} and serialize the
* assembled {@link com.anthropic.models.messages.Message}.
*/
@Nullable
private static String reassembleSse(byte[] sseBytes) {
try {
var mapper = BraintrustJsonMapper.get();
var reader =
new BufferedReader(
new InputStreamReader(
new ByteArrayInputStream(sseBytes), StandardCharsets.UTF_8));
var accumulator = MessageAccumulator.create();
String line;
while ((line = reader.readLine()) != null) {
if (!line.startsWith("data:")) continue;
String data = line.substring("data:".length()).strip();
if (data.isEmpty()) continue;
try {
accumulator.accumulate(mapper.readValue(data, RawMessageStreamEvent.class));
} catch (Exception ignored) {
// skip unrecognized event types (e.g. ping)
}
}
return BraintrustJsonMapper.toJson(accumulator.message());
} catch (Exception e) {
log.error("Could not parse Anthropic SSE buffer to tag streaming span output", e);
return null;
}
}
}
141 changes: 54 additions & 87 deletions ..._2_0/src/main/java/dev/braintrust/instrumentation/anthropic/v2_2_0/TracingHttpClient.java
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -5,25 +5,22 @@
import com.anthropic.core.http.HttpRequest;
import com.anthropic.core.http.HttpRequestBody;
import com.anthropic.core.http.HttpResponse;
import com.anthropic.helpers.MessageAccumulator;
import com.anthropic.models.messages.RawMessageStreamEvent;
import dev.braintrust.bootstrap.BraintrustBridge;
import dev.braintrust.instrumentation.InstrumentationSemConv;
import dev.braintrust.json.BraintrustJsonMapper;
import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.SpanContext;
import io.opentelemetry.api.trace.TraceFlags;
import io.opentelemetry.api.trace.TraceState;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.context.Context;
import java.io.BufferedReader;
import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;
import java.io.InputStream;
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;
Expand DownExpand Up@@ -125,7 +122,9 @@ public void close() {
bufferedRequest.baseUrl() != null ? bufferedRequest.baseUrl() : "",
bufferedRequest.pathSegments(),
bufferedRequest.method().name(),
inputJson);
inputJson,
null,
headersAsMap(bufferedRequest.headers()));

var response = underlying.execute(bufferedRequest, requestOptions);
return new TeeingStreamHttpResponse(response, span, tracer);
Expand DownExpand Up@@ -153,7 +152,9 @@ public void close() {
bufferedRequest.baseUrl() != null ? bufferedRequest.baseUrl() : "",
bufferedRequest.pathSegments(),
bufferedRequest.method().name(),
inputJson);
inputJson,
null,
headersAsMap(bufferedRequest.headers()));
return underlying
.executeAsync(bufferedRequest, requestOptions)
.thenApply(
Expand DownExpand Up@@ -264,9 +265,39 @@ private void onStreamClosed() {
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.
// Anything outside 2xx, not just 4xx/5xx: both vendor SDKs treat success as
// exactly 200..299, so a final 3xx that the http client did not follow (a 304, or
// a redirect with no usable Location) is raised to the caller as an
// UnexpectedStatusCodeException and must mark the span failed too.
int statusCode = delegate.statusCode();
if (statusCode < 200 || statusCode >= 300) {
InstrumentationSemConv.tagLLMSpanHttpError(
span, statusCode, new String(bytes, StandardCharsets.UTF_8));
}

// Wire-format bookkeeping lives in ResponseReassembler; this hands semconv
// everything the response carried in one flat call. A null body (empty or
// unparseable response) still tags the headers.
// 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());
try {
var reassembled =
ResponseReassembler.reassemble(bytes, timeToFirstTokenNanos.get());
InstrumentationSemConv.tagLLMSpanResponse(
tracer,
span,
InstrumentationSemConv.PROVIDER_NAME_ANTHROPIC,
reassembled.body(),
reassembled.timeToFirstTokenNanos(),
headersAsMap(delegate.headers()));
} catch (Exception e) {
// Observability must never change the response behavior seen by the caller.
log.error("Could not tag span from response buffer", e);
}
} finally {
span.end();
}
Expand DownExpand Up@@ -360,89 +391,25 @@ private void notifyClosed() {
// Span tagging from buffered bytes
// -------------------------------------------------------------------------

private static void tagSpanFromBuffer(
Tracer tracer, Span span, byte[] bytes, Long timeToFirstTokenNanos) {
if (bytes.length == 0) return;
try {
String firstLine = firstNonEmptyLine(bytes);
// Anthropic SSE starts with "event: message_start\ndata: ..." so we detect
// either prefix. OpenAI SSE starts directly with "data:".
boolean isSse =
firstLine != null
&& (firstLine.startsWith("data:") || firstLine.startsWith("event:"));
if (isSse) {
tagSpanFromSseBytes(tracer, span, bytes, timeToFirstTokenNanos);
} else {
// Non-streaming: plain Message JSON — pass it whole, no time_to_first_token
String responseJson = new String(bytes, StandardCharsets.UTF_8);
InstrumentationSemConv.tagLLMSpanResponse(
tracer,
span,
InstrumentationSemConv.PROVIDER_NAME_ANTHROPIC,
responseJson,
null);
}
} catch (Exception e) {
log.error("Could not tag span from Anthropic response buffer", e);
}
}

private static String firstNonEmptyLine(byte[] bytes) {
int start = 0;
for (int i = 0; i <= bytes.length; i++) {
if (i == bytes.length || bytes[i] == '\n') {
String line = new String(bytes, start, i - start, StandardCharsets.UTF_8).strip();
if (!line.isEmpty()) return line;
start = i + 1;
}
}
return null;
}

/**
* Anthropic SSE wire format has named events:
*
* <pre>
* event: message_start
* data: {"type":"message_start","message":{...}}
*
* event: content_block_delta
* data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hi"}}
* </pre>
*
* We only need the {@code data:} lines — the event name is redundant with the {@code type}
* field inside the JSON. Feed each data payload to {@link MessageAccumulator} and serialize the
* assembled {@link com.anthropic.models.messages.Message} for the span.
* Adapts the anthropic sdk's {@code Headers} to the vendor-neutral shape {@link
* InstrumentationSemConv} consumes. Returns an empty map on failure so a header-shape change
* can never take down the tagging that follows it.
*/
private static void tagSpanFromSseBytes(
Tracer tracer, Span span, byte[] sseBytes, Long timeToFirstTokenNanos) {
private static Map<String, List<String>> headersAsMap(
@Nullable com.anthropic.core.http.Headers headers) {
if (headers == null) {
return Map.of();
}
try {
var mapper = BraintrustJsonMapper.get();
var reader =
new BufferedReader(
new InputStreamReader(
new ByteArrayInputStream(sseBytes), StandardCharsets.UTF_8));
var accumulator = MessageAccumulator.create();
String line;
while ((line = reader.readLine()) != null) {
if (!line.startsWith("data:")) continue;
String data = line.substring("data:".length()).strip();
if (data.isEmpty()) continue;
try {
accumulator.accumulate(mapper.readValue(data, RawMessageStreamEvent.class));
} catch (Exception ignored) {
// skip unrecognized event types (e.g. ping)
}
var map = new HashMap<String, List<String>>();
for (String name : headers.names()) {
map.put(name, headers.values(name));
}
String assembledMessageJson = BraintrustJsonMapper.toJson(accumulator.message());
InstrumentationSemConv.tagLLMSpanResponse(
tracer,
span,
InstrumentationSemConv.PROVIDER_NAME_ANTHROPIC,
assembledMessageJson,
timeToFirstTokenNanos);
return map;
} catch (Exception e) {
log.error("Could not parse Anthropic SSE buffer to tag streaming span output", e);
log.debug("could not read headers", e);
return Map.of();
}
}
}
2 changes: 2 additions & 0 deletions .../dev/braintrust/instrumentation/anthropic/v2_2_0/auto/AnthropicInstrumentationModule.java
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -36,6 +36,8 @@ public List<String> getHelperClassNames() {
MANUAL_INSTRUMENTATION_PACKAGE + "TracingHttpClient$ExtractedRequest",
MANUAL_INSTRUMENTATION_PACKAGE + "BraintrustAnthropic",
MANUAL_INSTRUMENTATION_PACKAGE + "ContextCapturingProxy",
MANUAL_INSTRUMENTATION_PACKAGE + "ResponseReassembler",
MANUAL_INSTRUMENTATION_PACKAGE + "ResponseReassembler$Result",
"dev.braintrust.json.BraintrustJsonMapper",
"dev.braintrust.instrumentation.InstrumentationSemConv");
}
Expand Down
Loading
Loading
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Add copy buttons to all 
 blocks\n(function() {\n function addCopyButtons() {\n document.querySelectorAll('pre code').forEach(function(codeBlock) {\n if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;\n codeBlock.parentElement.setAttribute('data-copy-added', 'true');\n \n var btn = document.createElement('button');\n btn.textContent = 'Copy';\n btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';\n btn.onmouseover = function() { this.style.opacity = '1'; };\n btn.onmouseout = function() { this.style.opacity = '0.7'; };\n btn.onclick = function() {\n navigator.clipboard.writeText(codeBlock.textContent).then(function() {\n btn.textContent = 'Copied!';\n setTimeout(function() { btn.textContent = 'Copy'; }, 1500);\n });\n };\n codeBlock.parentElement.style.position = 'relative';\n codeBlock.parentElement.appendChild(btn);\n });\n }\n \n addCopyButtons();\n \n // Re-run on dynamic content\n var observer = new MutationObserver(addCopyButtons);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Add Copy Buttons to Code Blocks");
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '

Skip to content
 add request id to openai llm span attributes#172

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

Andrew Kent (realark)
merged 2 commits into

from

Aug 27, 2026
 Merged


add request id to openai llm span attributes
#172
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
e49d40a

VCR


realark Aug 26, 2026
4bbcc2e

tag vendor ids on openai and anthropic llm spans


realark Aug 26, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


3 changes: 2 additions & 1 deletion
AGENTS.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -160,11 +160,12 @@ VCR_MODE=record ./gradlew :braintrust-sdk:test --tests 'dev.braintrust.devserver
- when running btx, use the spec filter to target what is specifically under development: `VCR_MODE=off ./gradlew :btx:test -Pbtx.spec.filter=openai/prompt_cach --rerun`
- don't reformat the whole repo, but do run `./gradlew spotlessApply` on files you changed before committing. the pre-commit hook and `./gradlew check` both run `spotlessCheck`, which fails on unformatted code.

## Gotchas
## Misc Tips and Best Practices

- **don't hand-edit cassettes.** they're content-hashed and guarded against committed secrets. a failing VCR test means the recorded interaction changed — re-record it (see the VCR section), don't patch the json.
- **`braintrust-api` is generated code.** don't edit sources under it by hand; it's regenerated from the braintrust openapi spec pinned as `braintrustOpenApiRef` in gradle.properties.
- **there are no version constants to bump.** the sdk version is derived from git tags at build time (`generateVersion()` in build.gradle) and written into braintrust.properties. "bump the version" is not a source change.
- When adding test cases, favor adding to the test file of the module being changed rather than making a new file. For example, if you fix a bug in the `Foo` module, add the test case to `FooTest.java` instead of making a new file, `FooTestMyBuggyCase.java`

## Releasing

Expand Down

117 changes: 117 additions & 0 deletions
..._0/src/main/java/dev/braintrust/instrumentation/anthropic/v2_2_0/ResponseReassembler.java

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
package dev.braintrust.instrumentation.anthropic.v2_2_0;

import com.anthropic.helpers.MessageAccumulator;
import com.anthropic.models.messages.RawMessageStreamEvent;
import dev.braintrust.json.BraintrustJsonMapper;
import java.io.BufferedReader;
import java.io.ByteArrayInputStream;
import java.io.InputStreamReader;
import java.nio.charset.StandardCharsets;
import javax.annotation.Nullable;
import lombok.extern.slf4j.Slf4j;

/**
 * Turns the raw bytes of an Anthropic response into a single JSON document the semconv layer can
 * tag.
 *
 * <p>All of the wire-format bookkeeping lives here — SSE-vs-plain-JSON detection and chunk
 * reassembly — so that {@code TracingHttpClient} is left holding only the span lifecycle and one
 * flat call into {@code InstrumentationSemConv}.
 */
@Slf4j
class ResponseReassembler {

 private ResponseReassembler() {}

 /**
 * A reassembled response body plus the timing that belongs with it.
 *
 * <p>{@code body} is null when there was nothing usable to reassemble — an empty response, or
 * one we couldn't parse. Callers should still tag the response in that case; the headers remain
 * worth recording.
 *
 * <p>{@code timeToFirstTokenNanos} is only populated for a stream, since a non-streaming
 * response has no first token to time.
 */
 record Result(@Nullable String body, @Nullable Long timeToFirstTokenNanos) {
 static final Result EMPTY = new Result(null, null);
 }

 /** Detects the wire format and reassembles accordingly. Never throws. */
 static Result reassemble(byte[] bytes, long timeToFirstTokenNanos) {
 if (bytes.length == 0) {
 return Result.EMPTY;
 }
 try {
 String firstLine = firstNonEmptyLine(bytes);
 // Anthropic SSE starts with "event: message_start\ndata: ..." so we detect either
 // prefix. OpenAI SSE starts directly with "data:".
 boolean isSse =
 firstLine != null
 && (firstLine.startsWith("data:") || firstLine.startsWith("event:"));
 if (isSse) {
 return new Result(reassembleSse(bytes), timeToFirstTokenNanos);
 }
 // Non-streaming: plain Message JSON — pass it whole, no time_to_first_token
 return new Result(new String(bytes, StandardCharsets.UTF_8), null);
 } catch (Exception e) {
 log.error("Could not reassemble Anthropic response buffer", e);
 return Result.EMPTY;
 }
 }

 @Nullable
 private static String firstNonEmptyLine(byte[] bytes) {
 int start = 0;
 for (int i = 0; i <= bytes.length; i++) {
 if (i == bytes.length || bytes[i] == '\n') {
 String line = new String(bytes, start, i - start, StandardCharsets.UTF_8).strip();
 if (!line.isEmpty()) return line;
 start = i + 1;
 }
 }
 return null;
 }

 /**
 * Anthropic SSE wire format has named events:
 *
 * <pre>
 * event: message_start
 * data: {"type":"message_start","message":{...}}
 *
 * event: content_block_delta
 * data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hi"}}
 * </pre>
 *
 * We only need the {@code data:} lines — the event name is redundant with the {@code type}
 * field inside the JSON. Feed each data payload to {@link MessageAccumulator} and serialize the
 * assembled {@link com.anthropic.models.messages.Message}.
 */
 @Nullable
 private static String reassembleSse(byte[] sseBytes) {
 try {
 var mapper = BraintrustJsonMapper.get();
 var reader =
 new BufferedReader(
 new InputStreamReader(
 new ByteArrayInputStream(sseBytes), StandardCharsets.UTF_8));
 var accumulator = MessageAccumulator.create();
 String line;
 while ((line = reader.readLine()) != null) {
 if (!line.startsWith("data:")) continue;
 String data = line.substring("data:".length()).strip();
 if (data.isEmpty()) continue;
 try {
 accumulator.accumulate(mapper.readValue(data, RawMessageStreamEvent.class));
 } catch (Exception ignored) {
 // skip unrecognized event types (e.g. ping)
 }
 }
 return BraintrustJsonMapper.toJson(accumulator.message());
 } catch (Exception e) {
 log.error("Could not parse Anthropic SSE buffer to tag streaming span output", e);
 return null;
 }
 }
}

141 changes: 54 additions & 87 deletions
..._2_0/src/main/java/dev/braintrust/instrumentation/anthropic/v2_2_0/TracingHttpClient.java

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -5,25 +5,22 @@
import com.anthropic.core.http.HttpRequest;
import com.anthropic.core.http.HttpRequestBody;
import com.anthropic.core.http.HttpResponse;
import com.anthropic.helpers.MessageAccumulator;
import com.anthropic.models.messages.RawMessageStreamEvent;
import dev.braintrust.bootstrap.BraintrustBridge;
import dev.braintrust.instrumentation.InstrumentationSemConv;
import dev.braintrust.json.BraintrustJsonMapper;
import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.SpanContext;
import io.opentelemetry.api.trace.TraceFlags;
import io.opentelemetry.api.trace.TraceState;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.context.Context;
import java.io.BufferedReader;
import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;
import java.io.InputStream;
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;
Expand DownExpand Up@@ -125,7 +122,9 @@ public void close() {
 bufferedRequest.baseUrl() != null ? bufferedRequest.baseUrl() : "",
 bufferedRequest.pathSegments(),
 bufferedRequest.method().name(),
 inputJson);
 inputJson,
 null,
 headersAsMap(bufferedRequest.headers()));

 var response = underlying.execute(bufferedRequest, requestOptions);
 return new TeeingStreamHttpResponse(response, span, tracer);
Expand DownExpand Up@@ -153,7 +152,9 @@ public void close() {
 bufferedRequest.baseUrl() != null ? bufferedRequest.baseUrl() : "",
 bufferedRequest.pathSegments(),
 bufferedRequest.method().name(),
 inputJson);
 inputJson,
 null,
 headersAsMap(bufferedRequest.headers()));
 return underlying
 .executeAsync(bufferedRequest, requestOptions)
 .thenApply(
Expand DownExpand Up@@ -264,9 +265,39 @@ private void onStreamClosed() {
 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.
 // Anything outside 2xx, not just 4xx/5xx: both vendor SDKs treat success as
 // exactly 200..299, so a final 3xx that the http client did not follow (a 304, or
 // a redirect with no usable Location) is raised to the caller as an
 // UnexpectedStatusCodeException and must mark the span failed too.
 int statusCode = delegate.statusCode();
 if (statusCode < 200 || statusCode >= 300) {
 InstrumentationSemConv.tagLLMSpanHttpError(
 span, statusCode, new String(bytes, StandardCharsets.UTF_8));
 }

 // Wire-format bookkeeping lives in ResponseReassembler; this hands semconv
 // everything the response carried in one flat call. A null body (empty or
 // unparseable response) still tags the headers.
 // 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());
 try {
 var reassembled =
 ResponseReassembler.reassemble(bytes, timeToFirstTokenNanos.get());
 InstrumentationSemConv.tagLLMSpanResponse(
 tracer,
 span,
 InstrumentationSemConv.PROVIDER_NAME_ANTHROPIC,
 reassembled.body(),
 reassembled.timeToFirstTokenNanos(),
 headersAsMap(delegate.headers()));
 } catch (Exception e) {
 // Observability must never change the response behavior seen by the caller.
 log.error("Could not tag span from response buffer", e);
 }
 } finally {
 span.end();
 }
Expand DownExpand Up@@ -360,89 +391,25 @@ private void notifyClosed() {
 // Span tagging from buffered bytes
 // -------------------------------------------------------------------------

 private static void tagSpanFromBuffer(
 Tracer tracer, Span span, byte[] bytes, Long timeToFirstTokenNanos) {
 if (bytes.length == 0) return;
 try {
 String firstLine = firstNonEmptyLine(bytes);
 // Anthropic SSE starts with "event: message_start\ndata: ..." so we detect
 // either prefix. OpenAI SSE starts directly with "data:".
 boolean isSse =
 firstLine != null
 && (firstLine.startsWith("data:") || firstLine.startsWith("event:"));
 if (isSse) {
 tagSpanFromSseBytes(tracer, span, bytes, timeToFirstTokenNanos);
 } else {
 // Non-streaming: plain Message JSON — pass it whole, no time_to_first_token
 String responseJson = new String(bytes, StandardCharsets.UTF_8);
 InstrumentationSemConv.tagLLMSpanResponse(
 tracer,
 span,
 InstrumentationSemConv.PROVIDER_NAME_ANTHROPIC,
 responseJson,
 null);
 }
 } catch (Exception e) {
 log.error("Could not tag span from Anthropic response buffer", e);
 }
 }

 private static String firstNonEmptyLine(byte[] bytes) {
 int start = 0;
 for (int i = 0; i <= bytes.length; i++) {
 if (i == bytes.length || bytes[i] == '\n') {
 String line = new String(bytes, start, i - start, StandardCharsets.UTF_8).strip();
 if (!line.isEmpty()) return line;
 start = i + 1;
 }
 }
 return null;
 }

 /**
 * Anthropic SSE wire format has named events:
 *
 * <pre>
 * event: message_start
 * data: {"type":"message_start","message":{...}}
 *
 * event: content_block_delta
 * data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hi"}}
 * </pre>
 *
 * We only need the {@code data:} lines — the event name is redundant with the {@code type}
 * field inside the JSON. Feed each data payload to {@link MessageAccumulator} and serialize the
 * assembled {@link com.anthropic.models.messages.Message} for the span.
 * Adapts the anthropic sdk's {@code Headers} to the vendor-neutral shape {@link
 * InstrumentationSemConv} consumes. Returns an empty map on failure so a header-shape change
 * can never take down the tagging that follows it.
 */
 private static void tagSpanFromSseBytes(
 Tracer tracer, Span span, byte[] sseBytes, Long timeToFirstTokenNanos) {
 private static Map<String, List<String>> headersAsMap(
 @Nullable com.anthropic.core.http.Headers headers) {
 if (headers == null) {
 return Map.of();
 }
 try {
 var mapper = BraintrustJsonMapper.get();
 var reader =
 new BufferedReader(
 new InputStreamReader(
 new ByteArrayInputStream(sseBytes), StandardCharsets.UTF_8));
 var accumulator = MessageAccumulator.create();
 String line;
 while ((line = reader.readLine()) != null) {
 if (!line.startsWith("data:")) continue;
 String data = line.substring("data:".length()).strip();
 if (data.isEmpty()) continue;
 try {
 accumulator.accumulate(mapper.readValue(data, RawMessageStreamEvent.class));
 } catch (Exception ignored) {
 // skip unrecognized event types (e.g. ping)
 }
 var map = new HashMap<String, List<String>>();
 for (String name : headers.names()) {
 map.put(name, headers.values(name));
 }
 String assembledMessageJson = BraintrustJsonMapper.toJson(accumulator.message());
 InstrumentationSemConv.tagLLMSpanResponse(
 tracer,
 span,
 InstrumentationSemConv.PROVIDER_NAME_ANTHROPIC,
 assembledMessageJson,
 timeToFirstTokenNanos);
 return map;
 } catch (Exception e) {
 log.error("Could not parse Anthropic SSE buffer to tag streaming span output", e);
 log.debug("could not read headers", e);
 return Map.of();
 }
 }
}

2 changes: 2 additions & 0 deletions
.../dev/braintrust/instrumentation/anthropic/v2_2_0/auto/AnthropicInstrumentationModule.java

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -36,6 +36,8 @@ public List<String> getHelperClassNames() {
 MANUAL_INSTRUMENTATION_PACKAGE + "TracingHttpClient$ExtractedRequest",
 MANUAL_INSTRUMENTATION_PACKAGE + "BraintrustAnthropic",
 MANUAL_INSTRUMENTATION_PACKAGE + "ContextCapturingProxy",
 MANUAL_INSTRUMENTATION_PACKAGE + "ResponseReassembler",
 MANUAL_INSTRUMENTATION_PACKAGE + "ResponseReassembler$Result",
 "dev.braintrust.json.BraintrustJsonMapper",
 "dev.braintrust.instrumentation.InstrumentationSemConv");
 }
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Force GitHub README to respect dark mode\n(function() {\n var style = document.createElement('style');\n style.textContent = '\n .markdown-body {\n color-scheme: dark light;\n }\n .markdown-body pre { background: #161b22 !important; }\n .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }\n .markdown-body table th, .markdown-body table td { border-color: #30363d !important; }\n .markdown-body img { background: #0d1117; }\n .markdown-body blockquote { border-left-color: #8b949e; }\n .markdown-body hr { border-color: #30363d; }\n ';\n document.head.appendChild(style);\n})();", "GitHub Dark Mode README Fix");
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
 add request id to openai llm span attributes#172

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

Andrew Kent (realark)
merged 2 commits into

from

Aug 27, 2026
 Merged


add request id to openai llm span attributes
#172
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
e49d40a

VCR


realark Aug 26, 2026
4bbcc2e

tag vendor ids on openai and anthropic llm spans


realark Aug 26, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


3 changes: 2 additions & 1 deletion
AGENTS.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -160,11 +160,12 @@ VCR_MODE=record ./gradlew :braintrust-sdk:test --tests 'dev.braintrust.devserver
- when running btx, use the spec filter to target what is specifically under development: `VCR_MODE=off ./gradlew :btx:test -Pbtx.spec.filter=openai/prompt_cach --rerun`
- don't reformat the whole repo, but do run `./gradlew spotlessApply` on files you changed before committing. the pre-commit hook and `./gradlew check` both run `spotlessCheck`, which fails on unformatted code.

## Gotchas
## Misc Tips and Best Practices

- **don't hand-edit cassettes.** they're content-hashed and guarded against committed secrets. a failing VCR test means the recorded interaction changed — re-record it (see the VCR section), don't patch the json.
- **`braintrust-api` is generated code.** don't edit sources under it by hand; it's regenerated from the braintrust openapi spec pinned as `braintrustOpenApiRef` in gradle.properties.
- **there are no version constants to bump.** the sdk version is derived from git tags at build time (`generateVersion()` in build.gradle) and written into braintrust.properties. "bump the version" is not a source change.
- When adding test cases, favor adding to the test file of the module being changed rather than making a new file. For example, if you fix a bug in the `Foo` module, add the test case to `FooTest.java` instead of making a new file, `FooTestMyBuggyCase.java`

## Releasing

Expand Down

117 changes: 117 additions & 0 deletions
..._0/src/main/java/dev/braintrust/instrumentation/anthropic/v2_2_0/ResponseReassembler.java

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
package dev.braintrust.instrumentation.anthropic.v2_2_0;

import com.anthropic.helpers.MessageAccumulator;
import com.anthropic.models.messages.RawMessageStreamEvent;
import dev.braintrust.json.BraintrustJsonMapper;
import java.io.BufferedReader;
import java.io.ByteArrayInputStream;
import java.io.InputStreamReader;
import java.nio.charset.StandardCharsets;
import javax.annotation.Nullable;
import lombok.extern.slf4j.Slf4j;

/**
 * Turns the raw bytes of an Anthropic response into a single JSON document the semconv layer can
 * tag.
 *
 * <p>All of the wire-format bookkeeping lives here — SSE-vs-plain-JSON detection and chunk
 * reassembly — so that {@code TracingHttpClient} is left holding only the span lifecycle and one
 * flat call into {@code InstrumentationSemConv}.
 */
@Slf4j
class ResponseReassembler {

 private ResponseReassembler() {}

 /**
 * A reassembled response body plus the timing that belongs with it.
 *
 * <p>{@code body} is null when there was nothing usable to reassemble — an empty response, or
 * one we couldn't parse. Callers should still tag the response in that case; the headers remain
 * worth recording.
 *
 * <p>{@code timeToFirstTokenNanos} is only populated for a stream, since a non-streaming
 * response has no first token to time.
 */
 record Result(@Nullable String body, @Nullable Long timeToFirstTokenNanos) {
 static final Result EMPTY = new Result(null, null);
 }

 /** Detects the wire format and reassembles accordingly. Never throws. */
 static Result reassemble(byte[] bytes, long timeToFirstTokenNanos) {
 if (bytes.length == 0) {
 return Result.EMPTY;
 }
 try {
 String firstLine = firstNonEmptyLine(bytes);
 // Anthropic SSE starts with "event: message_start\ndata: ..." so we detect either
 // prefix. OpenAI SSE starts directly with "data:".
 boolean isSse =
 firstLine != null
 && (firstLine.startsWith("data:") || firstLine.startsWith("event:"));
 if (isSse) {
 return new Result(reassembleSse(bytes), timeToFirstTokenNanos);
 }
 // Non-streaming: plain Message JSON — pass it whole, no time_to_first_token
 return new Result(new String(bytes, StandardCharsets.UTF_8), null);
 } catch (Exception e) {
 log.error("Could not reassemble Anthropic response buffer", e);
 return Result.EMPTY;
 }
 }

 @Nullable
 private static String firstNonEmptyLine(byte[] bytes) {
 int start = 0;
 for (int i = 0; i <= bytes.length; i++) {
 if (i == bytes.length || bytes[i] == '\n') {
 String line = new String(bytes, start, i - start, StandardCharsets.UTF_8).strip();
 if (!line.isEmpty()) return line;
 start = i + 1;
 }
 }
 return null;
 }

 /**
 * Anthropic SSE wire format has named events:
 *
 * <pre>
 * event: message_start
 * data: {"type":"message_start","message":{...}}
 *
 * event: content_block_delta
 * data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hi"}}
 * </pre>
 *
 * We only need the {@code data:} lines — the event name is redundant with the {@code type}
 * field inside the JSON. Feed each data payload to {@link MessageAccumulator} and serialize the
 * assembled {@link com.anthropic.models.messages.Message}.
 */
 @Nullable
 private static String reassembleSse(byte[] sseBytes) {
 try {
 var mapper = BraintrustJsonMapper.get();
 var reader =
 new BufferedReader(
 new InputStreamReader(
 new ByteArrayInputStream(sseBytes), StandardCharsets.UTF_8));
 var accumulator = MessageAccumulator.create();
 String line;
 while ((line = reader.readLine()) != null) {
 if (!line.startsWith("data:")) continue;
 String data = line.substring("data:".length()).strip();
 if (data.isEmpty()) continue;
 try {
 accumulator.accumulate(mapper.readValue(data, RawMessageStreamEvent.class));
 } catch (Exception ignored) {
 // skip unrecognized event types (e.g. ping)
 }
 }
 return BraintrustJsonMapper.toJson(accumulator.message());
 } catch (Exception e) {
 log.error("Could not parse Anthropic SSE buffer to tag streaming span output", e);
 return null;
 }
 }
}

141 changes: 54 additions & 87 deletions
..._2_0/src/main/java/dev/braintrust/instrumentation/anthropic/v2_2_0/TracingHttpClient.java

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -5,25 +5,22 @@
import com.anthropic.core.http.HttpRequest;
import com.anthropic.core.http.HttpRequestBody;
import com.anthropic.core.http.HttpResponse;
import com.anthropic.helpers.MessageAccumulator;
import com.anthropic.models.messages.RawMessageStreamEvent;
import dev.braintrust.bootstrap.BraintrustBridge;
import dev.braintrust.instrumentation.InstrumentationSemConv;
import dev.braintrust.json.BraintrustJsonMapper;
import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.SpanContext;
import io.opentelemetry.api.trace.TraceFlags;
import io.opentelemetry.api.trace.TraceState;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.context.Context;
import java.io.BufferedReader;
import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;
import java.io.InputStream;
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;
Expand DownExpand Up@@ -125,7 +122,9 @@ public void close() {
 bufferedRequest.baseUrl() != null ? bufferedRequest.baseUrl() : "",
 bufferedRequest.pathSegments(),
 bufferedRequest.method().name(),
 inputJson);
 inputJson,
 null,
 headersAsMap(bufferedRequest.headers()));

 var response = underlying.execute(bufferedRequest, requestOptions);
 return new TeeingStreamHttpResponse(response, span, tracer);
Expand DownExpand Up@@ -153,7 +152,9 @@ public void close() {
 bufferedRequest.baseUrl() != null ? bufferedRequest.baseUrl() : "",
 bufferedRequest.pathSegments(),
 bufferedRequest.method().name(),
 inputJson);
 inputJson,
 null,
 headersAsMap(bufferedRequest.headers()));
 return underlying
 .executeAsync(bufferedRequest, requestOptions)
 .thenApply(
Expand DownExpand Up@@ -264,9 +265,39 @@ private void onStreamClosed() {
 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.
 // Anything outside 2xx, not just 4xx/5xx: both vendor SDKs treat success as
 // exactly 200..299, so a final 3xx that the http client did not follow (a 304, or
 // a redirect with no usable Location) is raised to the caller as an
 // UnexpectedStatusCodeException and must mark the span failed too.
 int statusCode = delegate.statusCode();
 if (statusCode < 200 || statusCode >= 300) {
 InstrumentationSemConv.tagLLMSpanHttpError(
 span, statusCode, new String(bytes, StandardCharsets.UTF_8));
 }

 // Wire-format bookkeeping lives in ResponseReassembler; this hands semconv
 // everything the response carried in one flat call. A null body (empty or
 // unparseable response) still tags the headers.
 // 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());
 try {
 var reassembled =
 ResponseReassembler.reassemble(bytes, timeToFirstTokenNanos.get());
 InstrumentationSemConv.tagLLMSpanResponse(
 tracer,
 span,
 InstrumentationSemConv.PROVIDER_NAME_ANTHROPIC,
 reassembled.body(),
 reassembled.timeToFirstTokenNanos(),
 headersAsMap(delegate.headers()));
 } catch (Exception e) {
 // Observability must never change the response behavior seen by the caller.
 log.error("Could not tag span from response buffer", e);
 }
 } finally {
 span.end();
 }
Expand DownExpand Up@@ -360,89 +391,25 @@ private void notifyClosed() {
 // Span tagging from buffered bytes
 // -------------------------------------------------------------------------

 private static void tagSpanFromBuffer(
 Tracer tracer, Span span, byte[] bytes, Long timeToFirstTokenNanos) {
 if (bytes.length == 0) return;
 try {
 String firstLine = firstNonEmptyLine(bytes);
 // Anthropic SSE starts with "event: message_start\ndata: ..." so we detect
 // either prefix. OpenAI SSE starts directly with "data:".
 boolean isSse =
 firstLine != null
 && (firstLine.startsWith("data:") || firstLine.startsWith("event:"));
 if (isSse) {
 tagSpanFromSseBytes(tracer, span, bytes, timeToFirstTokenNanos);
 } else {
 // Non-streaming: plain Message JSON — pass it whole, no time_to_first_token
 String responseJson = new String(bytes, StandardCharsets.UTF_8);
 InstrumentationSemConv.tagLLMSpanResponse(
 tracer,
 span,
 InstrumentationSemConv.PROVIDER_NAME_ANTHROPIC,
 responseJson,
 null);
 }
 } catch (Exception e) {
 log.error("Could not tag span from Anthropic response buffer", e);
 }
 }

 private static String firstNonEmptyLine(byte[] bytes) {
 int start = 0;
 for (int i = 0; i <= bytes.length; i++) {
 if (i == bytes.length || bytes[i] == '\n') {
 String line = new String(bytes, start, i - start, StandardCharsets.UTF_8).strip();
 if (!line.isEmpty()) return line;
 start = i + 1;
 }
 }
 return null;
 }

 /**
 * Anthropic SSE wire format has named events:
 *
 * <pre>
 * event: message_start
 * data: {"type":"message_start","message":{...}}
 *
 * event: content_block_delta
 * data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hi"}}
 * </pre>
 *
 * We only need the {@code data:} lines — the event name is redundant with the {@code type}
 * field inside the JSON. Feed each data payload to {@link MessageAccumulator} and serialize the
 * assembled {@link com.anthropic.models.messages.Message} for the span.
 * Adapts the anthropic sdk's {@code Headers} to the vendor-neutral shape {@link
 * InstrumentationSemConv} consumes. Returns an empty map on failure so a header-shape change
 * can never take down the tagging that follows it.
 */
 private static void tagSpanFromSseBytes(
 Tracer tracer, Span span, byte[] sseBytes, Long timeToFirstTokenNanos) {
 private static Map<String, List<String>> headersAsMap(
 @Nullable com.anthropic.core.http.Headers headers) {
 if (headers == null) {
 return Map.of();
 }
 try {
 var mapper = BraintrustJsonMapper.get();
 var reader =
 new BufferedReader(
 new InputStreamReader(
 new ByteArrayInputStream(sseBytes), StandardCharsets.UTF_8));
 var accumulator = MessageAccumulator.create();
 String line;
 while ((line = reader.readLine()) != null) {
 if (!line.startsWith("data:")) continue;
 String data = line.substring("data:".length()).strip();
 if (data.isEmpty()) continue;
 try {
 accumulator.accumulate(mapper.readValue(data, RawMessageStreamEvent.class));
 } catch (Exception ignored) {
 // skip unrecognized event types (e.g. ping)
 }
 var map = new HashMap<String, List<String>>();
 for (String name : headers.names()) {
 map.put(name, headers.values(name));
 }
 String assembledMessageJson = BraintrustJsonMapper.toJson(accumulator.message());
 InstrumentationSemConv.tagLLMSpanResponse(
 tracer,
 span,
 InstrumentationSemConv.PROVIDER_NAME_ANTHROPIC,
 assembledMessageJson,
 timeToFirstTokenNanos);
 return map;
 } catch (Exception e) {
 log.error("Could not parse Anthropic SSE buffer to tag streaming span output", e);
 log.debug("could not read headers", e);
 return Map.of();
 }
 }
}

2 changes: 2 additions & 0 deletions
.../dev/braintrust/instrumentation/anthropic/v2_2_0/auto/AnthropicInstrumentationModule.java

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -36,6 +36,8 @@ public List<String> getHelperClassNames() {
 MANUAL_INSTRUMENTATION_PACKAGE + "TracingHttpClient$ExtractedRequest",
 MANUAL_INSTRUMENTATION_PACKAGE + "BraintrustAnthropic",
 MANUAL_INSTRUMENTATION_PACKAGE + "ContextCapturingProxy",
 MANUAL_INSTRUMENTATION_PACKAGE + "ResponseReassembler",
 MANUAL_INSTRUMENTATION_PACKAGE + "ResponseReassembler$Result",
 "dev.braintrust.json.BraintrustJsonMapper",
 "dev.braintrust.instrumentation.InstrumentationSemConv");
 }
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Highlight search terms from Google/DuckDuckGo/Bing referrer\n(function() {\n var ref = document.referrer;\n var terms = [];\n \n if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {\n var url = new URL(ref);\n var q = url.searchParams.get('q') || url.searchParams.get('p');\n if (q) {\n terms = q.split(/\\s+/).filter(function(t) { return t.length > 2; });\n }\n }\n \n if (terms.length === 0) return;\n \n var style = document.createElement('style');\n style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';\n document.head.appendChild(style);\n \n function highlight(node) {\n if (node.nodeType === 3) { // text node\n var text = node.textContent;\n var found = false;\n terms.forEach(function(term) {\n var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\') + ')', 'gi');\n if (regex.test(text)) {\n found = true;\n var frag = document.createDocumentFragment();\n var parts = text.split(regex);\n parts.forEach(function(part, i) {\n if (i % 2 === 0) {\n frag.appendChild(document.createTextNode(part));\n } else {\n var span = document.createElement('span');\n span.className = 'userscript-highlight';\n span.textContent = part;\n frag.appendChild(span);\n }\n });\n node.parentNode.replaceChild(frag, node);\n }\n });\n } else if (node.nodeType === 1 && node.childNodes) { // element\n var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];\n if (!skipTags.includes(node.tagName)) {\n Array.from(node.childNodes).forEach(highlight);\n }\n }\n }\n \n highlight(document.body);\n \n // Re-highlight on dynamic content\n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1 || node.nodeType === 3) highlight(node);\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Highlight Search Terms");
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
 add request id to openai llm span attributes#172

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

Andrew Kent (realark)
merged 2 commits into

from

Aug 27, 2026
 Merged


add request id to openai llm span attributes
#172
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
e49d40a

VCR


realark Aug 26, 2026
4bbcc2e

tag vendor ids on openai and anthropic llm spans


realark Aug 26, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


3 changes: 2 additions & 1 deletion
AGENTS.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -160,11 +160,12 @@ VCR_MODE=record ./gradlew :braintrust-sdk:test --tests 'dev.braintrust.devserver
- when running btx, use the spec filter to target what is specifically under development: `VCR_MODE=off ./gradlew :btx:test -Pbtx.spec.filter=openai/prompt_cach --rerun`
- don't reformat the whole repo, but do run `./gradlew spotlessApply` on files you changed before committing. the pre-commit hook and `./gradlew check` both run `spotlessCheck`, which fails on unformatted code.

## Gotchas
## Misc Tips and Best Practices

- **don't hand-edit cassettes.** they're content-hashed and guarded against committed secrets. a failing VCR test means the recorded interaction changed — re-record it (see the VCR section), don't patch the json.
- **`braintrust-api` is generated code.** don't edit sources under it by hand; it's regenerated from the braintrust openapi spec pinned as `braintrustOpenApiRef` in gradle.properties.
- **there are no version constants to bump.** the sdk version is derived from git tags at build time (`generateVersion()` in build.gradle) and written into braintrust.properties. "bump the version" is not a source change.
- When adding test cases, favor adding to the test file of the module being changed rather than making a new file. For example, if you fix a bug in the `Foo` module, add the test case to `FooTest.java` instead of making a new file, `FooTestMyBuggyCase.java`

## Releasing

Expand Down

117 changes: 117 additions & 0 deletions
..._0/src/main/java/dev/braintrust/instrumentation/anthropic/v2_2_0/ResponseReassembler.java

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
package dev.braintrust.instrumentation.anthropic.v2_2_0;

import com.anthropic.helpers.MessageAccumulator;
import com.anthropic.models.messages.RawMessageStreamEvent;
import dev.braintrust.json.BraintrustJsonMapper;
import java.io.BufferedReader;
import java.io.ByteArrayInputStream;
import java.io.InputStreamReader;
import java.nio.charset.StandardCharsets;
import javax.annotation.Nullable;
import lombok.extern.slf4j.Slf4j;

/**
 * Turns the raw bytes of an Anthropic response into a single JSON document the semconv layer can
 * tag.
 *
 * <p>All of the wire-format bookkeeping lives here — SSE-vs-plain-JSON detection and chunk
 * reassembly — so that {@code TracingHttpClient} is left holding only the span lifecycle and one
 * flat call into {@code InstrumentationSemConv}.
 */
@Slf4j
class ResponseReassembler {

 private ResponseReassembler() {}

 /**
 * A reassembled response body plus the timing that belongs with it.
 *
 * <p>{@code body} is null when there was nothing usable to reassemble — an empty response, or
 * one we couldn't parse. Callers should still tag the response in that case; the headers remain
 * worth recording.
 *
 * <p>{@code timeToFirstTokenNanos} is only populated for a stream, since a non-streaming
 * response has no first token to time.
 */
 record Result(@Nullable String body, @Nullable Long timeToFirstTokenNanos) {
 static final Result EMPTY = new Result(null, null);
 }

 /** Detects the wire format and reassembles accordingly. Never throws. */
 static Result reassemble(byte[] bytes, long timeToFirstTokenNanos) {
 if (bytes.length == 0) {
 return Result.EMPTY;
 }
 try {
 String firstLine = firstNonEmptyLine(bytes);
 // Anthropic SSE starts with "event: message_start\ndata: ..." so we detect either
 // prefix. OpenAI SSE starts directly with "data:".
 boolean isSse =
 firstLine != null
 && (firstLine.startsWith("data:") || firstLine.startsWith("event:"));
 if (isSse) {
 return new Result(reassembleSse(bytes), timeToFirstTokenNanos);
 }
 // Non-streaming: plain Message JSON — pass it whole, no time_to_first_token
 return new Result(new String(bytes, StandardCharsets.UTF_8), null);
 } catch (Exception e) {
 log.error("Could not reassemble Anthropic response buffer", e);
 return Result.EMPTY;
 }
 }

 @Nullable
 private static String firstNonEmptyLine(byte[] bytes) {
 int start = 0;
 for (int i = 0; i <= bytes.length; i++) {
 if (i == bytes.length || bytes[i] == '\n') {
 String line = new String(bytes, start, i - start, StandardCharsets.UTF_8).strip();
 if (!line.isEmpty()) return line;
 start = i + 1;
 }
 }
 return null;
 }

 /**
 * Anthropic SSE wire format has named events:
 *
 * <pre>
 * event: message_start
 * data: {"type":"message_start","message":{...}}
 *
 * event: content_block_delta
 * data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hi"}}
 * </pre>
 *
 * We only need the {@code data:} lines — the event name is redundant with the {@code type}
 * field inside the JSON. Feed each data payload to {@link MessageAccumulator} and serialize the
 * assembled {@link com.anthropic.models.messages.Message}.
 */
 @Nullable
 private static String reassembleSse(byte[] sseBytes) {
 try {
 var mapper = BraintrustJsonMapper.get();
 var reader =
 new BufferedReader(
 new InputStreamReader(
 new ByteArrayInputStream(sseBytes), StandardCharsets.UTF_8));
 var accumulator = MessageAccumulator.create();
 String line;
 while ((line = reader.readLine()) != null) {
 if (!line.startsWith("data:")) continue;
 String data = line.substring("data:".length()).strip();
 if (data.isEmpty()) continue;
 try {
 accumulator.accumulate(mapper.readValue(data, RawMessageStreamEvent.class));
 } catch (Exception ignored) {
 // skip unrecognized event types (e.g. ping)
 }
 }
 return BraintrustJsonMapper.toJson(accumulator.message());
 } catch (Exception e) {
 log.error("Could not parse Anthropic SSE buffer to tag streaming span output", e);
 return null;
 }
 }
}

141 changes: 54 additions & 87 deletions
..._2_0/src/main/java/dev/braintrust/instrumentation/anthropic/v2_2_0/TracingHttpClient.java

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -5,25 +5,22 @@
import com.anthropic.core.http.HttpRequest;
import com.anthropic.core.http.HttpRequestBody;
import com.anthropic.core.http.HttpResponse;
import com.anthropic.helpers.MessageAccumulator;
import com.anthropic.models.messages.RawMessageStreamEvent;
import dev.braintrust.bootstrap.BraintrustBridge;
import dev.braintrust.instrumentation.InstrumentationSemConv;
import dev.braintrust.json.BraintrustJsonMapper;
import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.SpanContext;
import io.opentelemetry.api.trace.TraceFlags;
import io.opentelemetry.api.trace.TraceState;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.context.Context;
import java.io.BufferedReader;
import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;
import java.io.InputStream;
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;
Expand DownExpand Up@@ -125,7 +122,9 @@ public void close() {
 bufferedRequest.baseUrl() != null ? bufferedRequest.baseUrl() : "",
 bufferedRequest.pathSegments(),
 bufferedRequest.method().name(),
 inputJson);
 inputJson,
 null,
 headersAsMap(bufferedRequest.headers()));

 var response = underlying.execute(bufferedRequest, requestOptions);
 return new TeeingStreamHttpResponse(response, span, tracer);
Expand DownExpand Up@@ -153,7 +152,9 @@ public void close() {
 bufferedRequest.baseUrl() != null ? bufferedRequest.baseUrl() : "",
 bufferedRequest.pathSegments(),
 bufferedRequest.method().name(),
 inputJson);
 inputJson,
 null,
 headersAsMap(bufferedRequest.headers()));
 return underlying
 .executeAsync(bufferedRequest, requestOptions)
 .thenApply(
Expand DownExpand Up@@ -264,9 +265,39 @@ private void onStreamClosed() {
 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.
 // Anything outside 2xx, not just 4xx/5xx: both vendor SDKs treat success as
 // exactly 200..299, so a final 3xx that the http client did not follow (a 304, or
 // a redirect with no usable Location) is raised to the caller as an
 // UnexpectedStatusCodeException and must mark the span failed too.
 int statusCode = delegate.statusCode();
 if (statusCode < 200 || statusCode >= 300) {
 InstrumentationSemConv.tagLLMSpanHttpError(
 span, statusCode, new String(bytes, StandardCharsets.UTF_8));
 }

 // Wire-format bookkeeping lives in ResponseReassembler; this hands semconv
 // everything the response carried in one flat call. A null body (empty or
 // unparseable response) still tags the headers.
 // 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());
 try {
 var reassembled =
 ResponseReassembler.reassemble(bytes, timeToFirstTokenNanos.get());
 InstrumentationSemConv.tagLLMSpanResponse(
 tracer,
 span,
 InstrumentationSemConv.PROVIDER_NAME_ANTHROPIC,
 reassembled.body(),
 reassembled.timeToFirstTokenNanos(),
 headersAsMap(delegate.headers()));
 } catch (Exception e) {
 // Observability must never change the response behavior seen by the caller.
 log.error("Could not tag span from response buffer", e);
 }
 } finally {
 span.end();
 }
Expand DownExpand Up@@ -360,89 +391,25 @@ private void notifyClosed() {
 // Span tagging from buffered bytes
 // -------------------------------------------------------------------------

 private static void tagSpanFromBuffer(
 Tracer tracer, Span span, byte[] bytes, Long timeToFirstTokenNanos) {
 if (bytes.length == 0) return;
 try {
 String firstLine = firstNonEmptyLine(bytes);
 // Anthropic SSE starts with "event: message_start\ndata: ..." so we detect
 // either prefix. OpenAI SSE starts directly with "data:".
 boolean isSse =
 firstLine != null
 && (firstLine.startsWith("data:") || firstLine.startsWith("event:"));
 if (isSse) {
 tagSpanFromSseBytes(tracer, span, bytes, timeToFirstTokenNanos);
 } else {
 // Non-streaming: plain Message JSON — pass it whole, no time_to_first_token
 String responseJson = new String(bytes, StandardCharsets.UTF_8);
 InstrumentationSemConv.tagLLMSpanResponse(
 tracer,
 span,
 InstrumentationSemConv.PROVIDER_NAME_ANTHROPIC,
 responseJson,
 null);
 }
 } catch (Exception e) {
 log.error("Could not tag span from Anthropic response buffer", e);
 }
 }

 private static String firstNonEmptyLine(byte[] bytes) {
 int start = 0;
 for (int i = 0; i <= bytes.length; i++) {
 if (i == bytes.length || bytes[i] == '\n') {
 String line = new String(bytes, start, i - start, StandardCharsets.UTF_8).strip();
 if (!line.isEmpty()) return line;
 start = i + 1;
 }
 }
 return null;
 }

 /**
 * Anthropic SSE wire format has named events:
 *
 * <pre>
 * event: message_start
 * data: {"type":"message_start","message":{...}}
 *
 * event: content_block_delta
 * data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hi"}}
 * </pre>
 *
 * We only need the {@code data:} lines — the event name is redundant with the {@code type}
 * field inside the JSON. Feed each data payload to {@link MessageAccumulator} and serialize the
 * assembled {@link com.anthropic.models.messages.Message} for the span.
 * Adapts the anthropic sdk's {@code Headers} to the vendor-neutral shape {@link
 * InstrumentationSemConv} consumes. Returns an empty map on failure so a header-shape change
 * can never take down the tagging that follows it.
 */
 private static void tagSpanFromSseBytes(
 Tracer tracer, Span span, byte[] sseBytes, Long timeToFirstTokenNanos) {
 private static Map<String, List<String>> headersAsMap(
 @Nullable com.anthropic.core.http.Headers headers) {
 if (headers == null) {
 return Map.of();
 }
 try {
 var mapper = BraintrustJsonMapper.get();
 var reader =
 new BufferedReader(
 new InputStreamReader(
 new ByteArrayInputStream(sseBytes), StandardCharsets.UTF_8));
 var accumulator = MessageAccumulator.create();
 String line;
 while ((line = reader.readLine()) != null) {
 if (!line.startsWith("data:")) continue;
 String data = line.substring("data:".length()).strip();
 if (data.isEmpty()) continue;
 try {
 accumulator.accumulate(mapper.readValue(data, RawMessageStreamEvent.class));
 } catch (Exception ignored) {
 // skip unrecognized event types (e.g. ping)
 }
 var map = new HashMap<String, List<String>>();
 for (String name : headers.names()) {
 map.put(name, headers.values(name));
 }
 String assembledMessageJson = BraintrustJsonMapper.toJson(accumulator.message());
 InstrumentationSemConv.tagLLMSpanResponse(
 tracer,
 span,
 InstrumentationSemConv.PROVIDER_NAME_ANTHROPIC,
 assembledMessageJson,
 timeToFirstTokenNanos);
 return map;
 } catch (Exception e) {
 log.error("Could not parse Anthropic SSE buffer to tag streaming span output", e);
 log.debug("could not read headers", e);
 return Map.of();
 }
 }
}

2 changes: 2 additions & 0 deletions
.../dev/braintrust/instrumentation/anthropic/v2_2_0/auto/AnthropicInstrumentationModule.java

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -36,6 +36,8 @@ public List<String> getHelperClassNames() {
 MANUAL_INSTRUMENTATION_PACKAGE + "TracingHttpClient$ExtractedRequest",
 MANUAL_INSTRUMENTATION_PACKAGE + "BraintrustAnthropic",
 MANUAL_INSTRUMENTATION_PACKAGE + "ContextCapturingProxy",
 MANUAL_INSTRUMENTATION_PACKAGE + "ResponseReassembler",
 MANUAL_INSTRUMENTATION_PACKAGE + "ResponseReassembler$Result",
 "dev.braintrust.json.BraintrustJsonMapper",
 "dev.braintrust.instrumentation.InstrumentationSemConv");
 }
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Strip utm_, fbclid, gclid, etc. from all links on page\n(function() {\n var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',\n 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',\n 'ref', 'ref_src', 'source', 'medium', 'campaign'];\n \n function cleanUrl(url) {\n try {\n var u = new URL(url, window.location.origin);\n var changed = false;\n trackingParams.forEach(function(p) {\n if (u.searchParams.has(p)) {\n u.searchParams.delete(p);\n changed = true;\n }\n });\n return changed ? u.toString() : url;\n } catch (e) {\n return url;\n }\n }\n \n function cleanLinks() {\n document.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n \n cleanLinks();\n \n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1) {\n if (node.tagName === 'A') cleanLinks();\n node.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Remove Tracking Parameters from Links");
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '

Skip to content
 add request id to openai llm span attributes#172

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

Andrew Kent (realark)
merged 2 commits into

from

Aug 27, 2026
 Merged


add request id to openai llm span attributes
#172
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
e49d40a

VCR


realark Aug 26, 2026
4bbcc2e

tag vendor ids on openai and anthropic llm spans


realark Aug 26, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


3 changes: 2 additions & 1 deletion
AGENTS.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -160,11 +160,12 @@ VCR_MODE=record ./gradlew :braintrust-sdk:test --tests 'dev.braintrust.devserver
- when running btx, use the spec filter to target what is specifically under development: `VCR_MODE=off ./gradlew :btx:test -Pbtx.spec.filter=openai/prompt_cach --rerun`
- don't reformat the whole repo, but do run `./gradlew spotlessApply` on files you changed before committing. the pre-commit hook and `./gradlew check` both run `spotlessCheck`, which fails on unformatted code.

## Gotchas
## Misc Tips and Best Practices

- **don't hand-edit cassettes.** they're content-hashed and guarded against committed secrets. a failing VCR test means the recorded interaction changed — re-record it (see the VCR section), don't patch the json.
- **`braintrust-api` is generated code.** don't edit sources under it by hand; it's regenerated from the braintrust openapi spec pinned as `braintrustOpenApiRef` in gradle.properties.
- **there are no version constants to bump.** the sdk version is derived from git tags at build time (`generateVersion()` in build.gradle) and written into braintrust.properties. "bump the version" is not a source change.
- When adding test cases, favor adding to the test file of the module being changed rather than making a new file. For example, if you fix a bug in the `Foo` module, add the test case to `FooTest.java` instead of making a new file, `FooTestMyBuggyCase.java`

## Releasing

Expand Down

117 changes: 117 additions & 0 deletions
..._0/src/main/java/dev/braintrust/instrumentation/anthropic/v2_2_0/ResponseReassembler.java

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
package dev.braintrust.instrumentation.anthropic.v2_2_0;

import com.anthropic.helpers.MessageAccumulator;
import com.anthropic.models.messages.RawMessageStreamEvent;
import dev.braintrust.json.BraintrustJsonMapper;
import java.io.BufferedReader;
import java.io.ByteArrayInputStream;
import java.io.InputStreamReader;
import java.nio.charset.StandardCharsets;
import javax.annotation.Nullable;
import lombok.extern.slf4j.Slf4j;

/**
 * Turns the raw bytes of an Anthropic response into a single JSON document the semconv layer can
 * tag.
 *
 * <p>All of the wire-format bookkeeping lives here — SSE-vs-plain-JSON detection and chunk
 * reassembly — so that {@code TracingHttpClient} is left holding only the span lifecycle and one
 * flat call into {@code InstrumentationSemConv}.
 */
@Slf4j
class ResponseReassembler {

 private ResponseReassembler() {}

 /**
 * A reassembled response body plus the timing that belongs with it.
 *
 * <p>{@code body} is null when there was nothing usable to reassemble — an empty response, or
 * one we couldn't parse. Callers should still tag the response in that case; the headers remain
 * worth recording.
 *
 * <p>{@code timeToFirstTokenNanos} is only populated for a stream, since a non-streaming
 * response has no first token to time.
 */
 record Result(@Nullable String body, @Nullable Long timeToFirstTokenNanos) {
 static final Result EMPTY = new Result(null, null);
 }

 /** Detects the wire format and reassembles accordingly. Never throws. */
 static Result reassemble(byte[] bytes, long timeToFirstTokenNanos) {
 if (bytes.length == 0) {
 return Result.EMPTY;
 }
 try {
 String firstLine = firstNonEmptyLine(bytes);
 // Anthropic SSE starts with "event: message_start\ndata: ..." so we detect either
 // prefix. OpenAI SSE starts directly with "data:".
 boolean isSse =
 firstLine != null
 && (firstLine.startsWith("data:") || firstLine.startsWith("event:"));
 if (isSse) {
 return new Result(reassembleSse(bytes), timeToFirstTokenNanos);
 }
 // Non-streaming: plain Message JSON — pass it whole, no time_to_first_token
 return new Result(new String(bytes, StandardCharsets.UTF_8), null);
 } catch (Exception e) {
 log.error("Could not reassemble Anthropic response buffer", e);
 return Result.EMPTY;
 }
 }

 @Nullable
 private static String firstNonEmptyLine(byte[] bytes) {
 int start = 0;
 for (int i = 0; i <= bytes.length; i++) {
 if (i == bytes.length || bytes[i] == '\n') {
 String line = new String(bytes, start, i - start, StandardCharsets.UTF_8).strip();
 if (!line.isEmpty()) return line;
 start = i + 1;
 }
 }
 return null;
 }

 /**
 * Anthropic SSE wire format has named events:
 *
 * <pre>
 * event: message_start
 * data: {"type":"message_start","message":{...}}
 *
 * event: content_block_delta
 * data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hi"}}
 * </pre>
 *
 * We only need the {@code data:} lines — the event name is redundant with the {@code type}
 * field inside the JSON. Feed each data payload to {@link MessageAccumulator} and serialize the
 * assembled {@link com.anthropic.models.messages.Message}.
 */
 @Nullable
 private static String reassembleSse(byte[] sseBytes) {
 try {
 var mapper = BraintrustJsonMapper.get();
 var reader =
 new BufferedReader(
 new InputStreamReader(
 new ByteArrayInputStream(sseBytes), StandardCharsets.UTF_8));
 var accumulator = MessageAccumulator.create();
 String line;
 while ((line = reader.readLine()) != null) {
 if (!line.startsWith("data:")) continue;
 String data = line.substring("data:".length()).strip();
 if (data.isEmpty()) continue;
 try {
 accumulator.accumulate(mapper.readValue(data, RawMessageStreamEvent.class));
 } catch (Exception ignored) {
 // skip unrecognized event types (e.g. ping)
 }
 }
 return BraintrustJsonMapper.toJson(accumulator.message());
 } catch (Exception e) {
 log.error("Could not parse Anthropic SSE buffer to tag streaming span output", e);
 return null;
 }
 }
}

141 changes: 54 additions & 87 deletions
..._2_0/src/main/java/dev/braintrust/instrumentation/anthropic/v2_2_0/TracingHttpClient.java

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -5,25 +5,22 @@
import com.anthropic.core.http.HttpRequest;
import com.anthropic.core.http.HttpRequestBody;
import com.anthropic.core.http.HttpResponse;
import com.anthropic.helpers.MessageAccumulator;
import com.anthropic.models.messages.RawMessageStreamEvent;
import dev.braintrust.bootstrap.BraintrustBridge;
import dev.braintrust.instrumentation.InstrumentationSemConv;
import dev.braintrust.json.BraintrustJsonMapper;
import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.SpanContext;
import io.opentelemetry.api.trace.TraceFlags;
import io.opentelemetry.api.trace.TraceState;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.context.Context;
import java.io.BufferedReader;
import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;
import java.io.InputStream;
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;
Expand DownExpand Up@@ -125,7 +122,9 @@ public void close() {
 bufferedRequest.baseUrl() != null ? bufferedRequest.baseUrl() : "",
 bufferedRequest.pathSegments(),
 bufferedRequest.method().name(),
 inputJson);
 inputJson,
 null,
 headersAsMap(bufferedRequest.headers()));

 var response = underlying.execute(bufferedRequest, requestOptions);
 return new TeeingStreamHttpResponse(response, span, tracer);
Expand DownExpand Up@@ -153,7 +152,9 @@ public void close() {
 bufferedRequest.baseUrl() != null ? bufferedRequest.baseUrl() : "",
 bufferedRequest.pathSegments(),
 bufferedRequest.method().name(),
 inputJson);
 inputJson,
 null,
 headersAsMap(bufferedRequest.headers()));
 return underlying
 .executeAsync(bufferedRequest, requestOptions)
 .thenApply(
Expand DownExpand Up@@ -264,9 +265,39 @@ private void onStreamClosed() {
 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.
 // Anything outside 2xx, not just 4xx/5xx: both vendor SDKs treat success as
 // exactly 200..299, so a final 3xx that the http client did not follow (a 304, or
 // a redirect with no usable Location) is raised to the caller as an
 // UnexpectedStatusCodeException and must mark the span failed too.
 int statusCode = delegate.statusCode();
 if (statusCode < 200 || statusCode >= 300) {
 InstrumentationSemConv.tagLLMSpanHttpError(
 span, statusCode, new String(bytes, StandardCharsets.UTF_8));
 }

 // Wire-format bookkeeping lives in ResponseReassembler; this hands semconv
 // everything the response carried in one flat call. A null body (empty or
 // unparseable response) still tags the headers.
 // 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());
 try {
 var reassembled =
 ResponseReassembler.reassemble(bytes, timeToFirstTokenNanos.get());
 InstrumentationSemConv.tagLLMSpanResponse(
 tracer,
 span,
 InstrumentationSemConv.PROVIDER_NAME_ANTHROPIC,
 reassembled.body(),
 reassembled.timeToFirstTokenNanos(),
 headersAsMap(delegate.headers()));
 } catch (Exception e) {
 // Observability must never change the response behavior seen by the caller.
 log.error("Could not tag span from response buffer", e);
 }
 } finally {
 span.end();
 }
Expand DownExpand Up@@ -360,89 +391,25 @@ private void notifyClosed() {
 // Span tagging from buffered bytes
 // -------------------------------------------------------------------------

 private static void tagSpanFromBuffer(
 Tracer tracer, Span span, byte[] bytes, Long timeToFirstTokenNanos) {
 if (bytes.length == 0) return;
 try {
 String firstLine = firstNonEmptyLine(bytes);
 // Anthropic SSE starts with "event: message_start\ndata: ..." so we detect
 // either prefix. OpenAI SSE starts directly with "data:".
 boolean isSse =
 firstLine != null
 && (firstLine.startsWith("data:") || firstLine.startsWith("event:"));
 if (isSse) {
 tagSpanFromSseBytes(tracer, span, bytes, timeToFirstTokenNanos);
 } else {
 // Non-streaming: plain Message JSON — pass it whole, no time_to_first_token
 String responseJson = new String(bytes, StandardCharsets.UTF_8);
 InstrumentationSemConv.tagLLMSpanResponse(
 tracer,
 span,
 InstrumentationSemConv.PROVIDER_NAME_ANTHROPIC,
 responseJson,
 null);
 }
 } catch (Exception e) {
 log.error("Could not tag span from Anthropic response buffer", e);
 }
 }

 private static String firstNonEmptyLine(byte[] bytes) {
 int start = 0;
 for (int i = 0; i <= bytes.length; i++) {
 if (i == bytes.length || bytes[i] == '\n') {
 String line = new String(bytes, start, i - start, StandardCharsets.UTF_8).strip();
 if (!line.isEmpty()) return line;
 start = i + 1;
 }
 }
 return null;
 }

 /**
 * Anthropic SSE wire format has named events:
 *
 * <pre>
 * event: message_start
 * data: {"type":"message_start","message":{...}}
 *
 * event: content_block_delta
 * data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hi"}}
 * </pre>
 *
 * We only need the {@code data:} lines — the event name is redundant with the {@code type}
 * field inside the JSON. Feed each data payload to {@link MessageAccumulator} and serialize the
 * assembled {@link com.anthropic.models.messages.Message} for the span.
 * Adapts the anthropic sdk's {@code Headers} to the vendor-neutral shape {@link
 * InstrumentationSemConv} consumes. Returns an empty map on failure so a header-shape change
 * can never take down the tagging that follows it.
 */
 private static void tagSpanFromSseBytes(
 Tracer tracer, Span span, byte[] sseBytes, Long timeToFirstTokenNanos) {
 private static Map<String, List<String>> headersAsMap(
 @Nullable com.anthropic.core.http.Headers headers) {
 if (headers == null) {
 return Map.of();
 }
 try {
 var mapper = BraintrustJsonMapper.get();
 var reader =
 new BufferedReader(
 new InputStreamReader(
 new ByteArrayInputStream(sseBytes), StandardCharsets.UTF_8));
 var accumulator = MessageAccumulator.create();
 String line;
 while ((line = reader.readLine()) != null) {
 if (!line.startsWith("data:")) continue;
 String data = line.substring("data:".length()).strip();
 if (data.isEmpty()) continue;
 try {
 accumulator.accumulate(mapper.readValue(data, RawMessageStreamEvent.class));
 } catch (Exception ignored) {
 // skip unrecognized event types (e.g. ping)
 }
 var map = new HashMap<String, List<String>>();
 for (String name : headers.names()) {
 map.put(name, headers.values(name));
 }
 String assembledMessageJson = BraintrustJsonMapper.toJson(accumulator.message());
 InstrumentationSemConv.tagLLMSpanResponse(
 tracer,
 span,
 InstrumentationSemConv.PROVIDER_NAME_ANTHROPIC,
 assembledMessageJson,
 timeToFirstTokenNanos);
 return map;
 } catch (Exception e) {
 log.error("Could not parse Anthropic SSE buffer to tag streaming span output", e);
 log.debug("could not read headers", e);
 return Map.of();
 }
 }
}

2 changes: 2 additions & 0 deletions
.../dev/braintrust/instrumentation/anthropic/v2_2_0/auto/AnthropicInstrumentationModule.java

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -36,6 +36,8 @@ public List<String> getHelperClassNames() {
 MANUAL_INSTRUMENTATION_PACKAGE + "TracingHttpClient$ExtractedRequest",
 MANUAL_INSTRUMENTATION_PACKAGE + "BraintrustAnthropic",
 MANUAL_INSTRUMENTATION_PACKAGE + "ContextCapturingProxy",
 MANUAL_INSTRUMENTATION_PACKAGE + "ResponseReassembler",
 MANUAL_INSTRUMENTATION_PACKAGE + "ResponseReassembler$Result",
 "dev.braintrust.json.BraintrustJsonMapper",
 "dev.braintrust.instrumentation.InstrumentationSemConv");
 }
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Auto-enable theater mode on YouTube\n(function() {\n function tryTheater() {\n var btn = document.querySelector('button[aria-label=\"Theater mode\"], ytd-player #player button[title=\"Theater mode\"]');\n if (btn && !btn.classList.contains('activated')) {\n btn.click();\n }\n }\n \n // Try immediately\n tryTheater();\n \n // Try after navigation (SPA)\n var lastUrl = location.href;\n setInterval(function() {\n if (location.href !== lastUrl) {\n lastUrl = location.href;\n setTimeout(tryTheater, 500);\n }\n }, 1000);\n \n // Also try on player load\n var observer = new MutationObserver(tryTheater);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "YouTube Theater Mode Default");
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
 add request id to openai llm span attributes#172

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

Andrew Kent (realark)
merged 2 commits into

from

Aug 27, 2026
 Merged


add request id to openai llm span attributes
#172
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
e49d40a

VCR


realark Aug 26, 2026
4bbcc2e

tag vendor ids on openai and anthropic llm spans


realark Aug 26, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


3 changes: 2 additions & 1 deletion
AGENTS.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -160,11 +160,12 @@ VCR_MODE=record ./gradlew :braintrust-sdk:test --tests 'dev.braintrust.devserver
- when running btx, use the spec filter to target what is specifically under development: `VCR_MODE=off ./gradlew :btx:test -Pbtx.spec.filter=openai/prompt_cach --rerun`
- don't reformat the whole repo, but do run `./gradlew spotlessApply` on files you changed before committing. the pre-commit hook and `./gradlew check` both run `spotlessCheck`, which fails on unformatted code.

## Gotchas
## Misc Tips and Best Practices

- **don't hand-edit cassettes.** they're content-hashed and guarded against committed secrets. a failing VCR test means the recorded interaction changed — re-record it (see the VCR section), don't patch the json.
- **`braintrust-api` is generated code.** don't edit sources under it by hand; it's regenerated from the braintrust openapi spec pinned as `braintrustOpenApiRef` in gradle.properties.
- **there are no version constants to bump.** the sdk version is derived from git tags at build time (`generateVersion()` in build.gradle) and written into braintrust.properties. "bump the version" is not a source change.
- When adding test cases, favor adding to the test file of the module being changed rather than making a new file. For example, if you fix a bug in the `Foo` module, add the test case to `FooTest.java` instead of making a new file, `FooTestMyBuggyCase.java`

## Releasing

Expand Down

117 changes: 117 additions & 0 deletions
..._0/src/main/java/dev/braintrust/instrumentation/anthropic/v2_2_0/ResponseReassembler.java

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
package dev.braintrust.instrumentation.anthropic.v2_2_0;

import com.anthropic.helpers.MessageAccumulator;
import com.anthropic.models.messages.RawMessageStreamEvent;
import dev.braintrust.json.BraintrustJsonMapper;
import java.io.BufferedReader;
import java.io.ByteArrayInputStream;
import java.io.InputStreamReader;
import java.nio.charset.StandardCharsets;
import javax.annotation.Nullable;
import lombok.extern.slf4j.Slf4j;

/**
 * Turns the raw bytes of an Anthropic response into a single JSON document the semconv layer can
 * tag.
 *
 * <p>All of the wire-format bookkeeping lives here — SSE-vs-plain-JSON detection and chunk
 * reassembly — so that {@code TracingHttpClient} is left holding only the span lifecycle and one
 * flat call into {@code InstrumentationSemConv}.
 */
@Slf4j
class ResponseReassembler {

 private ResponseReassembler() {}

 /**
 * A reassembled response body plus the timing that belongs with it.
 *
 * <p>{@code body} is null when there was nothing usable to reassemble — an empty response, or
 * one we couldn't parse. Callers should still tag the response in that case; the headers remain
 * worth recording.
 *
 * <p>{@code timeToFirstTokenNanos} is only populated for a stream, since a non-streaming
 * response has no first token to time.
 */
 record Result(@Nullable String body, @Nullable Long timeToFirstTokenNanos) {
 static final Result EMPTY = new Result(null, null);
 }

 /** Detects the wire format and reassembles accordingly. Never throws. */
 static Result reassemble(byte[] bytes, long timeToFirstTokenNanos) {
 if (bytes.length == 0) {
 return Result.EMPTY;
 }
 try {
 String firstLine = firstNonEmptyLine(bytes);
 // Anthropic SSE starts with "event: message_start\ndata: ..." so we detect either
 // prefix. OpenAI SSE starts directly with "data:".
 boolean isSse =
 firstLine != null
 && (firstLine.startsWith("data:") || firstLine.startsWith("event:"));
 if (isSse) {
 return new Result(reassembleSse(bytes), timeToFirstTokenNanos);
 }
 // Non-streaming: plain Message JSON — pass it whole, no time_to_first_token
 return new Result(new String(bytes, StandardCharsets.UTF_8), null);
 } catch (Exception e) {
 log.error("Could not reassemble Anthropic response buffer", e);
 return Result.EMPTY;
 }
 }

 @Nullable
 private static String firstNonEmptyLine(byte[] bytes) {
 int start = 0;
 for (int i = 0; i <= bytes.length; i++) {
 if (i == bytes.length || bytes[i] == '\n') {
 String line = new String(bytes, start, i - start, StandardCharsets.UTF_8).strip();
 if (!line.isEmpty()) return line;
 start = i + 1;
 }
 }
 return null;
 }

 /**
 * Anthropic SSE wire format has named events:
 *
 * <pre>
 * event: message_start
 * data: {"type":"message_start","message":{...}}
 *
 * event: content_block_delta
 * data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hi"}}
 * </pre>
 *
 * We only need the {@code data:} lines — the event name is redundant with the {@code type}
 * field inside the JSON. Feed each data payload to {@link MessageAccumulator} and serialize the
 * assembled {@link com.anthropic.models.messages.Message}.
 */
 @Nullable
 private static String reassembleSse(byte[] sseBytes) {
 try {
 var mapper = BraintrustJsonMapper.get();
 var reader =
 new BufferedReader(
 new InputStreamReader(
 new ByteArrayInputStream(sseBytes), StandardCharsets.UTF_8));
 var accumulator = MessageAccumulator.create();
 String line;
 while ((line = reader.readLine()) != null) {
 if (!line.startsWith("data:")) continue;
 String data = line.substring("data:".length()).strip();
 if (data.isEmpty()) continue;
 try {
 accumulator.accumulate(mapper.readValue(data, RawMessageStreamEvent.class));
 } catch (Exception ignored) {
 // skip unrecognized event types (e.g. ping)
 }
 }
 return BraintrustJsonMapper.toJson(accumulator.message());
 } catch (Exception e) {
 log.error("Could not parse Anthropic SSE buffer to tag streaming span output", e);
 return null;
 }
 }
}

141 changes: 54 additions & 87 deletions
..._2_0/src/main/java/dev/braintrust/instrumentation/anthropic/v2_2_0/TracingHttpClient.java

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -5,25 +5,22 @@
import com.anthropic.core.http.HttpRequest;
import com.anthropic.core.http.HttpRequestBody;
import com.anthropic.core.http.HttpResponse;
import com.anthropic.helpers.MessageAccumulator;
import com.anthropic.models.messages.RawMessageStreamEvent;
import dev.braintrust.bootstrap.BraintrustBridge;
import dev.braintrust.instrumentation.InstrumentationSemConv;
import dev.braintrust.json.BraintrustJsonMapper;
import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.SpanContext;
import io.opentelemetry.api.trace.TraceFlags;
import io.opentelemetry.api.trace.TraceState;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.context.Context;
import java.io.BufferedReader;
import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;
import java.io.InputStream;
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;
Expand DownExpand Up@@ -125,7 +122,9 @@ public void close() {
 bufferedRequest.baseUrl() != null ? bufferedRequest.baseUrl() : "",
 bufferedRequest.pathSegments(),
 bufferedRequest.method().name(),
 inputJson);
 inputJson,
 null,
 headersAsMap(bufferedRequest.headers()));

 var response = underlying.execute(bufferedRequest, requestOptions);
 return new TeeingStreamHttpResponse(response, span, tracer);
Expand DownExpand Up@@ -153,7 +152,9 @@ public void close() {
 bufferedRequest.baseUrl() != null ? bufferedRequest.baseUrl() : "",
 bufferedRequest.pathSegments(),
 bufferedRequest.method().name(),
 inputJson);
 inputJson,
 null,
 headersAsMap(bufferedRequest.headers()));
 return underlying
 .executeAsync(bufferedRequest, requestOptions)
 .thenApply(
Expand DownExpand Up@@ -264,9 +265,39 @@ private void onStreamClosed() {
 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.
 // Anything outside 2xx, not just 4xx/5xx: both vendor SDKs treat success as
 // exactly 200..299, so a final 3xx that the http client did not follow (a 304, or
 // a redirect with no usable Location) is raised to the caller as an
 // UnexpectedStatusCodeException and must mark the span failed too.
 int statusCode = delegate.statusCode();
 if (statusCode < 200 || statusCode >= 300) {
 InstrumentationSemConv.tagLLMSpanHttpError(
 span, statusCode, new String(bytes, StandardCharsets.UTF_8));
 }

 // Wire-format bookkeeping lives in ResponseReassembler; this hands semconv
 // everything the response carried in one flat call. A null body (empty or
 // unparseable response) still tags the headers.
 // 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());
 try {
 var reassembled =
 ResponseReassembler.reassemble(bytes, timeToFirstTokenNanos.get());
 InstrumentationSemConv.tagLLMSpanResponse(
 tracer,
 span,
 InstrumentationSemConv.PROVIDER_NAME_ANTHROPIC,
 reassembled.body(),
 reassembled.timeToFirstTokenNanos(),
 headersAsMap(delegate.headers()));
 } catch (Exception e) {
 // Observability must never change the response behavior seen by the caller.
 log.error("Could not tag span from response buffer", e);
 }
 } finally {
 span.end();
 }
Expand DownExpand Up@@ -360,89 +391,25 @@ private void notifyClosed() {
 // Span tagging from buffered bytes
 // -------------------------------------------------------------------------

 private static void tagSpanFromBuffer(
 Tracer tracer, Span span, byte[] bytes, Long timeToFirstTokenNanos) {
 if (bytes.length == 0) return;
 try {
 String firstLine = firstNonEmptyLine(bytes);
 // Anthropic SSE starts with "event: message_start\ndata: ..." so we detect
 // either prefix. OpenAI SSE starts directly with "data:".
 boolean isSse =
 firstLine != null
 && (firstLine.startsWith("data:") || firstLine.startsWith("event:"));
 if (isSse) {
 tagSpanFromSseBytes(tracer, span, bytes, timeToFirstTokenNanos);
 } else {
 // Non-streaming: plain Message JSON — pass it whole, no time_to_first_token
 String responseJson = new String(bytes, StandardCharsets.UTF_8);
 InstrumentationSemConv.tagLLMSpanResponse(
 tracer,
 span,
 InstrumentationSemConv.PROVIDER_NAME_ANTHROPIC,
 responseJson,
 null);
 }
 } catch (Exception e) {
 log.error("Could not tag span from Anthropic response buffer", e);
 }
 }

 private static String firstNonEmptyLine(byte[] bytes) {
 int start = 0;
 for (int i = 0; i <= bytes.length; i++) {
 if (i == bytes.length || bytes[i] == '\n') {
 String line = new String(bytes, start, i - start, StandardCharsets.UTF_8).strip();
 if (!line.isEmpty()) return line;
 start = i + 1;
 }
 }
 return null;
 }

 /**
 * Anthropic SSE wire format has named events:
 *
 * <pre>
 * event: message_start
 * data: {"type":"message_start","message":{...}}
 *
 * event: content_block_delta
 * data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hi"}}
 * </pre>
 *
 * We only need the {@code data:} lines — the event name is redundant with the {@code type}
 * field inside the JSON. Feed each data payload to {@link MessageAccumulator} and serialize the
 * assembled {@link com.anthropic.models.messages.Message} for the span.
 * Adapts the anthropic sdk's {@code Headers} to the vendor-neutral shape {@link
 * InstrumentationSemConv} consumes. Returns an empty map on failure so a header-shape change
 * can never take down the tagging that follows it.
 */
 private static void tagSpanFromSseBytes(
 Tracer tracer, Span span, byte[] sseBytes, Long timeToFirstTokenNanos) {
 private static Map<String, List<String>> headersAsMap(
 @Nullable com.anthropic.core.http.Headers headers) {
 if (headers == null) {
 return Map.of();
 }
 try {
 var mapper = BraintrustJsonMapper.get();
 var reader =
 new BufferedReader(
 new InputStreamReader(
 new ByteArrayInputStream(sseBytes), StandardCharsets.UTF_8));
 var accumulator = MessageAccumulator.create();
 String line;
 while ((line = reader.readLine()) != null) {
 if (!line.startsWith("data:")) continue;
 String data = line.substring("data:".length()).strip();
 if (data.isEmpty()) continue;
 try {
 accumulator.accumulate(mapper.readValue(data, RawMessageStreamEvent.class));
 } catch (Exception ignored) {
 // skip unrecognized event types (e.g. ping)
 }
 var map = new HashMap<String, List<String>>();
 for (String name : headers.names()) {
 map.put(name, headers.values(name));
 }
 String assembledMessageJson = BraintrustJsonMapper.toJson(accumulator.message());
 InstrumentationSemConv.tagLLMSpanResponse(
 tracer,
 span,
 InstrumentationSemConv.PROVIDER_NAME_ANTHROPIC,
 assembledMessageJson,
 timeToFirstTokenNanos);
 return map;
 } catch (Exception e) {
 log.error("Could not parse Anthropic SSE buffer to tag streaming span output", e);
 log.debug("could not read headers", e);
 return Map.of();
 }
 }
}

2 changes: 2 additions & 0 deletions
.../dev/braintrust/instrumentation/anthropic/v2_2_0/auto/AnthropicInstrumentationModule.java

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -36,6 +36,8 @@ public List<String> getHelperClassNames() {
 MANUAL_INSTRUMENTATION_PACKAGE + "TracingHttpClient$ExtractedRequest",
 MANUAL_INSTRUMENTATION_PACKAGE + "BraintrustAnthropic",
 MANUAL_INSTRUMENTATION_PACKAGE + "ContextCapturingProxy",
 MANUAL_INSTRUMENTATION_PACKAGE + "ResponseReassembler",
 MANUAL_INSTRUMENTATION_PACKAGE + "ResponseReassembler$Result",
 "dev.braintrust.json.BraintrustJsonMapper",
 "dev.braintrust.instrumentation.InstrumentationSemConv");
 }
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Remove or un-stick sticky/fixed headers that block content\n(function() {\n function unstick() {\n document.querySelectorAll('header, nav, [role=\"banner\"], .header, .navbar, .sticky, .fixed-top, [style*=\"position: fixed\"], [style*=\"position:sticky\"]').forEach(function(el) {\n if (el.style.position === 'fixed' || el.style.position === 'sticky' || \n getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {\n el.style.position = 'static';\n el.style.top = 'auto';\n el.style.zIndex = 'auto';\n }\n });\n }\n \n unstick();\n \n var observer = new MutationObserver(unstick);\n observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });\n})();", "Kill Sticky Headers");
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
 add request id to openai llm span attributes#172

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

Andrew Kent (realark)
merged 2 commits into

from

Aug 27, 2026
 Merged


add request id to openai llm span attributes
#172
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
e49d40a

VCR


realark Aug 26, 2026
4bbcc2e

tag vendor ids on openai and anthropic llm spans


realark Aug 26, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


3 changes: 2 additions & 1 deletion
AGENTS.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -160,11 +160,12 @@ VCR_MODE=record ./gradlew :braintrust-sdk:test --tests 'dev.braintrust.devserver
- when running btx, use the spec filter to target what is specifically under development: `VCR_MODE=off ./gradlew :btx:test -Pbtx.spec.filter=openai/prompt_cach --rerun`
- don't reformat the whole repo, but do run `./gradlew spotlessApply` on files you changed before committing. the pre-commit hook and `./gradlew check` both run `spotlessCheck`, which fails on unformatted code.

## Gotchas
## Misc Tips and Best Practices

- **don't hand-edit cassettes.** they're content-hashed and guarded against committed secrets. a failing VCR test means the recorded interaction changed — re-record it (see the VCR section), don't patch the json.
- **`braintrust-api` is generated code.** don't edit sources under it by hand; it's regenerated from the braintrust openapi spec pinned as `braintrustOpenApiRef` in gradle.properties.
- **there are no version constants to bump.** the sdk version is derived from git tags at build time (`generateVersion()` in build.gradle) and written into braintrust.properties. "bump the version" is not a source change.
- When adding test cases, favor adding to the test file of the module being changed rather than making a new file. For example, if you fix a bug in the `Foo` module, add the test case to `FooTest.java` instead of making a new file, `FooTestMyBuggyCase.java`

## Releasing

Expand Down

117 changes: 117 additions & 0 deletions
..._0/src/main/java/dev/braintrust/instrumentation/anthropic/v2_2_0/ResponseReassembler.java

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
package dev.braintrust.instrumentation.anthropic.v2_2_0;

import com.anthropic.helpers.MessageAccumulator;
import com.anthropic.models.messages.RawMessageStreamEvent;
import dev.braintrust.json.BraintrustJsonMapper;
import java.io.BufferedReader;
import java.io.ByteArrayInputStream;
import java.io.InputStreamReader;
import java.nio.charset.StandardCharsets;
import javax.annotation.Nullable;
import lombok.extern.slf4j.Slf4j;

/**
 * Turns the raw bytes of an Anthropic response into a single JSON document the semconv layer can
 * tag.
 *
 * <p>All of the wire-format bookkeeping lives here — SSE-vs-plain-JSON detection and chunk
 * reassembly — so that {@code TracingHttpClient} is left holding only the span lifecycle and one
 * flat call into {@code InstrumentationSemConv}.
 */
@Slf4j
class ResponseReassembler {

 private ResponseReassembler() {}

 /**
 * A reassembled response body plus the timing that belongs with it.
 *
 * <p>{@code body} is null when there was nothing usable to reassemble — an empty response, or
 * one we couldn't parse. Callers should still tag the response in that case; the headers remain
 * worth recording.
 *
 * <p>{@code timeToFirstTokenNanos} is only populated for a stream, since a non-streaming
 * response has no first token to time.
 */
 record Result(@Nullable String body, @Nullable Long timeToFirstTokenNanos) {
 static final Result EMPTY = new Result(null, null);
 }

 /** Detects the wire format and reassembles accordingly. Never throws. */
 static Result reassemble(byte[] bytes, long timeToFirstTokenNanos) {
 if (bytes.length == 0) {
 return Result.EMPTY;
 }
 try {
 String firstLine = firstNonEmptyLine(bytes);
 // Anthropic SSE starts with "event: message_start\ndata: ..." so we detect either
 // prefix. OpenAI SSE starts directly with "data:".
 boolean isSse =
 firstLine != null
 && (firstLine.startsWith("data:") || firstLine.startsWith("event:"));
 if (isSse) {
 return new Result(reassembleSse(bytes), timeToFirstTokenNanos);
 }
 // Non-streaming: plain Message JSON — pass it whole, no time_to_first_token
 return new Result(new String(bytes, StandardCharsets.UTF_8), null);
 } catch (Exception e) {
 log.error("Could not reassemble Anthropic response buffer", e);
 return Result.EMPTY;
 }
 }

 @Nullable
 private static String firstNonEmptyLine(byte[] bytes) {
 int start = 0;
 for (int i = 0; i <= bytes.length; i++) {
 if (i == bytes.length || bytes[i] == '\n') {
 String line = new String(bytes, start, i - start, StandardCharsets.UTF_8).strip();
 if (!line.isEmpty()) return line;
 start = i + 1;
 }
 }
 return null;
 }

 /**
 * Anthropic SSE wire format has named events:
 *
 * <pre>
 * event: message_start
 * data: {"type":"message_start","message":{...}}
 *
 * event: content_block_delta
 * data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hi"}}
 * </pre>
 *
 * We only need the {@code data:} lines — the event name is redundant with the {@code type}
 * field inside the JSON. Feed each data payload to {@link MessageAccumulator} and serialize the
 * assembled {@link com.anthropic.models.messages.Message}.
 */
 @Nullable
 private static String reassembleSse(byte[] sseBytes) {
 try {
 var mapper = BraintrustJsonMapper.get();
 var reader =
 new BufferedReader(
 new InputStreamReader(
 new ByteArrayInputStream(sseBytes), StandardCharsets.UTF_8));
 var accumulator = MessageAccumulator.create();
 String line;
 while ((line = reader.readLine()) != null) {
 if (!line.startsWith("data:")) continue;
 String data = line.substring("data:".length()).strip();
 if (data.isEmpty()) continue;
 try {
 accumulator.accumulate(mapper.readValue(data, RawMessageStreamEvent.class));
 } catch (Exception ignored) {
 // skip unrecognized event types (e.g. ping)
 }
 }
 return BraintrustJsonMapper.toJson(accumulator.message());
 } catch (Exception e) {
 log.error("Could not parse Anthropic SSE buffer to tag streaming span output", e);
 return null;
 }
 }
}

141 changes: 54 additions & 87 deletions
..._2_0/src/main/java/dev/braintrust/instrumentation/anthropic/v2_2_0/TracingHttpClient.java

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -5,25 +5,22 @@
import com.anthropic.core.http.HttpRequest;
import com.anthropic.core.http.HttpRequestBody;
import com.anthropic.core.http.HttpResponse;
import com.anthropic.helpers.MessageAccumulator;
import com.anthropic.models.messages.RawMessageStreamEvent;
import dev.braintrust.bootstrap.BraintrustBridge;
import dev.braintrust.instrumentation.InstrumentationSemConv;
import dev.braintrust.json.BraintrustJsonMapper;
import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.SpanContext;
import io.opentelemetry.api.trace.TraceFlags;
import io.opentelemetry.api.trace.TraceState;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.context.Context;
import java.io.BufferedReader;
import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;
import java.io.InputStream;
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;
Expand DownExpand Up@@ -125,7 +122,9 @@ public void close() {
 bufferedRequest.baseUrl() != null ? bufferedRequest.baseUrl() : "",
 bufferedRequest.pathSegments(),
 bufferedRequest.method().name(),
 inputJson);
 inputJson,
 null,
 headersAsMap(bufferedRequest.headers()));

 var response = underlying.execute(bufferedRequest, requestOptions);
 return new TeeingStreamHttpResponse(response, span, tracer);
Expand DownExpand Up@@ -153,7 +152,9 @@ public void close() {
 bufferedRequest.baseUrl() != null ? bufferedRequest.baseUrl() : "",
 bufferedRequest.pathSegments(),
 bufferedRequest.method().name(),
 inputJson);
 inputJson,
 null,
 headersAsMap(bufferedRequest.headers()));
 return underlying
 .executeAsync(bufferedRequest, requestOptions)
 .thenApply(
Expand DownExpand Up@@ -264,9 +265,39 @@ private void onStreamClosed() {
 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.
 // Anything outside 2xx, not just 4xx/5xx: both vendor SDKs treat success as
 // exactly 200..299, so a final 3xx that the http client did not follow (a 304, or
 // a redirect with no usable Location) is raised to the caller as an
 // UnexpectedStatusCodeException and must mark the span failed too.
 int statusCode = delegate.statusCode();
 if (statusCode < 200 || statusCode >= 300) {
 InstrumentationSemConv.tagLLMSpanHttpError(
 span, statusCode, new String(bytes, StandardCharsets.UTF_8));
 }

 // Wire-format bookkeeping lives in ResponseReassembler; this hands semconv
 // everything the response carried in one flat call. A null body (empty or
 // unparseable response) still tags the headers.
 // 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());
 try {
 var reassembled =
 ResponseReassembler.reassemble(bytes, timeToFirstTokenNanos.get());
 InstrumentationSemConv.tagLLMSpanResponse(
 tracer,
 span,
 InstrumentationSemConv.PROVIDER_NAME_ANTHROPIC,
 reassembled.body(),
 reassembled.timeToFirstTokenNanos(),
 headersAsMap(delegate.headers()));
 } catch (Exception e) {
 // Observability must never change the response behavior seen by the caller.
 log.error("Could not tag span from response buffer", e);
 }
 } finally {
 span.end();
 }
Expand DownExpand Up@@ -360,89 +391,25 @@ private void notifyClosed() {
 // Span tagging from buffered bytes
 // -------------------------------------------------------------------------

 private static void tagSpanFromBuffer(
 Tracer tracer, Span span, byte[] bytes, Long timeToFirstTokenNanos) {
 if (bytes.length == 0) return;
 try {
 String firstLine = firstNonEmptyLine(bytes);
 // Anthropic SSE starts with "event: message_start\ndata: ..." so we detect
 // either prefix. OpenAI SSE starts directly with "data:".
 boolean isSse =
 firstLine != null
 && (firstLine.startsWith("data:") || firstLine.startsWith("event:"));
 if (isSse) {
 tagSpanFromSseBytes(tracer, span, bytes, timeToFirstTokenNanos);
 } else {
 // Non-streaming: plain Message JSON — pass it whole, no time_to_first_token
 String responseJson = new String(bytes, StandardCharsets.UTF_8);
 InstrumentationSemConv.tagLLMSpanResponse(
 tracer,
 span,
 InstrumentationSemConv.PROVIDER_NAME_ANTHROPIC,
 responseJson,
 null);
 }
 } catch (Exception e) {
 log.error("Could not tag span from Anthropic response buffer", e);
 }
 }

 private static String firstNonEmptyLine(byte[] bytes) {
 int start = 0;
 for (int i = 0; i <= bytes.length; i++) {
 if (i == bytes.length || bytes[i] == '\n') {
 String line = new String(bytes, start, i - start, StandardCharsets.UTF_8).strip();
 if (!line.isEmpty()) return line;
 start = i + 1;
 }
 }
 return null;
 }

 /**
 * Anthropic SSE wire format has named events:
 *
 * <pre>
 * event: message_start
 * data: {"type":"message_start","message":{...}}
 *
 * event: content_block_delta
 * data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hi"}}
 * </pre>
 *
 * We only need the {@code data:} lines — the event name is redundant with the {@code type}
 * field inside the JSON. Feed each data payload to {@link MessageAccumulator} and serialize the
 * assembled {@link com.anthropic.models.messages.Message} for the span.
 * Adapts the anthropic sdk's {@code Headers} to the vendor-neutral shape {@link
 * InstrumentationSemConv} consumes. Returns an empty map on failure so a header-shape change
 * can never take down the tagging that follows it.
 */
 private static void tagSpanFromSseBytes(
 Tracer tracer, Span span, byte[] sseBytes, Long timeToFirstTokenNanos) {
 private static Map<String, List<String>> headersAsMap(
 @Nullable com.anthropic.core.http.Headers headers) {
 if (headers == null) {
 return Map.of();
 }
 try {
 var mapper = BraintrustJsonMapper.get();
 var reader =
 new BufferedReader(
 new InputStreamReader(
 new ByteArrayInputStream(sseBytes), StandardCharsets.UTF_8));
 var accumulator = MessageAccumulator.create();
 String line;
 while ((line = reader.readLine()) != null) {
 if (!line.startsWith("data:")) continue;
 String data = line.substring("data:".length()).strip();
 if (data.isEmpty()) continue;
 try {
 accumulator.accumulate(mapper.readValue(data, RawMessageStreamEvent.class));
 } catch (Exception ignored) {
 // skip unrecognized event types (e.g. ping)
 }
 var map = new HashMap<String, List<String>>();
 for (String name : headers.names()) {
 map.put(name, headers.values(name));
 }
 String assembledMessageJson = BraintrustJsonMapper.toJson(accumulator.message());
 InstrumentationSemConv.tagLLMSpanResponse(
 tracer,
 span,
 InstrumentationSemConv.PROVIDER_NAME_ANTHROPIC,
 assembledMessageJson,
 timeToFirstTokenNanos);
 return map;
 } catch (Exception e) {
 log.error("Could not parse Anthropic SSE buffer to tag streaming span output", e);
 log.debug("could not read headers", e);
 return Map.of();
 }
 }
}

2 changes: 2 additions & 0 deletions
.../dev/braintrust/instrumentation/anthropic/v2_2_0/auto/AnthropicInstrumentationModule.java

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -36,6 +36,8 @@ public List<String> getHelperClassNames() {
 MANUAL_INSTRUMENTATION_PACKAGE + "TracingHttpClient$ExtractedRequest",
 MANUAL_INSTRUMENTATION_PACKAGE + "BraintrustAnthropic",
 MANUAL_INSTRUMENTATION_PACKAGE + "ContextCapturingProxy",
 MANUAL_INSTRUMENTATION_PACKAGE + "ResponseReassembler",
 MANUAL_INSTRUMENTATION_PACKAGE + "ResponseReassembler$Result",
 "dev.braintrust.json.BraintrustJsonMapper",
 "dev.braintrust.instrumentation.InstrumentationSemConv");
 }
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Universal Dark Mode - works on any site\n(function() {\n var enabled = true;\n \n function applyDarkMode() {\n if (!enabled) return;\n \n // Create style element if it doesn't exist\n var style = document.getElementById('universal-dark-mode-style');\n if (!style) {\n style = document.createElement('style');\n style.id = 'universal-dark-mode-style';\n document.head.appendChild(style);\n }\n \n // Dark mode CSS - inverts colors but preserves images/video\n style.textContent = '\n /* Invert everything except media */\n html {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #1a1a2e !important;\n }\n \n /* Restore images, videos, iframes, canvas */\n img, video, iframe, canvas, svg, picture, [style*=\"background-image\"] {\n filter: invert(1) hue-rotate(180deg) !important;\n }\n \n /* Preserve specific elements that should not be inverted */\n .no-dark-mode, .no-dark-mode *,\n [data-theme=\"light\"], [data-theme=\"light\"],\n .ace_editor, .ace_editor *,\n .CodeMirror, .CodeMirror *,\n .monaco-editor, .monaco-editor *,\n .markdown-body pre, .markdown-body pre *,\n .highlight, .highlight *,\n pre code, pre code * {\n filter: none !important;\n }\n \n /* Fix common UI elements */\n .modal, .popup, .dropdown-menu, .tooltip, .popover {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #2d2d44 !important;\n border-color: #444 !important;\n }\n \n /* Scrollbars */\n ::-webkit-scrollbar { background: #1a1a2e !important; }\n ::-webkit-scrollbar-thumb { background: #444 !important; }\n ::-webkit-scrollbar-thumb:hover { background: #555 !important; }\n \n /* Selection */\n ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ';\n }\n \n function removeDarkMode() {\n var style = document.getElementById('universal-dark-mode-style');\n if (style) style.remove();\n }\n \n // Toggle with Alt+Shift+D\n document.addEventListener('keydown', function(e) {\n if (e.altKey && e.shiftKey && e.key === 'D') {\n e.preventDefault();\n enabled = !enabled;\n if (enabled) {\n applyDarkMode();\n console.log('[Universal Dark Mode] Enabled');\n } else {\n removeDarkMode();\n console.log('[Universal Dark Mode] Disabled');\n }\n }\n });\n \n // Apply on load\n applyDarkMode();\n \n // Re-apply on dynamic content\n var observer = new MutationObserver(function(mutations) {\n if (enabled && !document.getElementById('universal-dark-mode-style')) {\n applyDarkMode();\n }\n });\n observer.observe(document.head, { childList: true });\n \n console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');\n})();", "Universal Dark Mode");
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();

Skip to content
 add request id to openai llm span attributes#172

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

Andrew Kent (realark)
merged 2 commits into

from

Aug 27, 2026
 Merged


add request id to openai llm span attributes
#172
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
e49d40a

VCR


realark Aug 26, 2026
4bbcc2e

tag vendor ids on openai and anthropic llm spans


realark Aug 26, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


3 changes: 2 additions & 1 deletion
AGENTS.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -160,11 +160,12 @@ VCR_MODE=record ./gradlew :braintrust-sdk:test --tests 'dev.braintrust.devserver
- when running btx, use the spec filter to target what is specifically under development: `VCR_MODE=off ./gradlew :btx:test -Pbtx.spec.filter=openai/prompt_cach --rerun`
- don't reformat the whole repo, but do run `./gradlew spotlessApply` on files you changed before committing. the pre-commit hook and `./gradlew check` both run `spotlessCheck`, which fails on unformatted code.

## Gotchas
## Misc Tips and Best Practices

- **don't hand-edit cassettes.** they're content-hashed and guarded against committed secrets. a failing VCR test means the recorded interaction changed — re-record it (see the VCR section), don't patch the json.
- **`braintrust-api` is generated code.** don't edit sources under it by hand; it's regenerated from the braintrust openapi spec pinned as `braintrustOpenApiRef` in gradle.properties.
- **there are no version constants to bump.** the sdk version is derived from git tags at build time (`generateVersion()` in build.gradle) and written into braintrust.properties. "bump the version" is not a source change.
- When adding test cases, favor adding to the test file of the module being changed rather than making a new file. For example, if you fix a bug in the `Foo` module, add the test case to `FooTest.java` instead of making a new file, `FooTestMyBuggyCase.java`

## Releasing

Expand Down

117 changes: 117 additions & 0 deletions
..._0/src/main/java/dev/braintrust/instrumentation/anthropic/v2_2_0/ResponseReassembler.java

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
package dev.braintrust.instrumentation.anthropic.v2_2_0;

import com.anthropic.helpers.MessageAccumulator;
import com.anthropic.models.messages.RawMessageStreamEvent;
import dev.braintrust.json.BraintrustJsonMapper;
import java.io.BufferedReader;
import java.io.ByteArrayInputStream;
import java.io.InputStreamReader;
import java.nio.charset.StandardCharsets;
import javax.annotation.Nullable;
import lombok.extern.slf4j.Slf4j;

/**
 * Turns the raw bytes of an Anthropic response into a single JSON document the semconv layer can
 * tag.
 *
 * <p>All of the wire-format bookkeeping lives here — SSE-vs-plain-JSON detection and chunk
 * reassembly — so that {@code TracingHttpClient} is left holding only the span lifecycle and one
 * flat call into {@code InstrumentationSemConv}.
 */
@Slf4j
class ResponseReassembler {

 private ResponseReassembler() {}

 /**
 * A reassembled response body plus the timing that belongs with it.
 *
 * <p>{@code body} is null when there was nothing usable to reassemble — an empty response, or
 * one we couldn't parse. Callers should still tag the response in that case; the headers remain
 * worth recording.
 *
 * <p>{@code timeToFirstTokenNanos} is only populated for a stream, since a non-streaming
 * response has no first token to time.
 */
 record Result(@Nullable String body, @Nullable Long timeToFirstTokenNanos) {
 static final Result EMPTY = new Result(null, null);
 }

 /** Detects the wire format and reassembles accordingly. Never throws. */
 static Result reassemble(byte[] bytes, long timeToFirstTokenNanos) {
 if (bytes.length == 0) {
 return Result.EMPTY;
 }
 try {
 String firstLine = firstNonEmptyLine(bytes);
 // Anthropic SSE starts with "event: message_start\ndata: ..." so we detect either
 // prefix. OpenAI SSE starts directly with "data:".
 boolean isSse =
 firstLine != null
 && (firstLine.startsWith("data:") || firstLine.startsWith("event:"));
 if (isSse) {
 return new Result(reassembleSse(bytes), timeToFirstTokenNanos);
 }
 // Non-streaming: plain Message JSON — pass it whole, no time_to_first_token
 return new Result(new String(bytes, StandardCharsets.UTF_8), null);
 } catch (Exception e) {
 log.error("Could not reassemble Anthropic response buffer", e);
 return Result.EMPTY;
 }
 }

 @Nullable
 private static String firstNonEmptyLine(byte[] bytes) {
 int start = 0;
 for (int i = 0; i <= bytes.length; i++) {
 if (i == bytes.length || bytes[i] == '\n') {
 String line = new String(bytes, start, i - start, StandardCharsets.UTF_8).strip();
 if (!line.isEmpty()) return line;
 start = i + 1;
 }
 }
 return null;
 }

 /**
 * Anthropic SSE wire format has named events:
 *
 * <pre>
 * event: message_start
 * data: {"type":"message_start","message":{...}}
 *
 * event: content_block_delta
 * data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hi"}}
 * </pre>
 *
 * We only need the {@code data:} lines — the event name is redundant with the {@code type}
 * field inside the JSON. Feed each data payload to {@link MessageAccumulator} and serialize the
 * assembled {@link com.anthropic.models.messages.Message}.
 */
 @Nullable
 private static String reassembleSse(byte[] sseBytes) {
 try {
 var mapper = BraintrustJsonMapper.get();
 var reader =
 new BufferedReader(
 new InputStreamReader(
 new ByteArrayInputStream(sseBytes), StandardCharsets.UTF_8));
 var accumulator = MessageAccumulator.create();
 String line;
 while ((line = reader.readLine()) != null) {
 if (!line.startsWith("data:")) continue;
 String data = line.substring("data:".length()).strip();
 if (data.isEmpty()) continue;
 try {
 accumulator.accumulate(mapper.readValue(data, RawMessageStreamEvent.class));
 } catch (Exception ignored) {
 // skip unrecognized event types (e.g. ping)
 }
 }
 return BraintrustJsonMapper.toJson(accumulator.message());
 } catch (Exception e) {
 log.error("Could not parse Anthropic SSE buffer to tag streaming span output", e);
 return null;
 }
 }
}

141 changes: 54 additions & 87 deletions
..._2_0/src/main/java/dev/braintrust/instrumentation/anthropic/v2_2_0/TracingHttpClient.java

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -5,25 +5,22 @@
import com.anthropic.core.http.HttpRequest;
import com.anthropic.core.http.HttpRequestBody;
import com.anthropic.core.http.HttpResponse;
import com.anthropic.helpers.MessageAccumulator;
import com.anthropic.models.messages.RawMessageStreamEvent;
import dev.braintrust.bootstrap.BraintrustBridge;
import dev.braintrust.instrumentation.InstrumentationSemConv;
import dev.braintrust.json.BraintrustJsonMapper;
import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.SpanContext;
import io.opentelemetry.api.trace.TraceFlags;
import io.opentelemetry.api.trace.TraceState;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.context.Context;
import java.io.BufferedReader;
import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;
import java.io.InputStream;
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;
Expand DownExpand Up@@ -125,7 +122,9 @@ public void close() {
 bufferedRequest.baseUrl() != null ? bufferedRequest.baseUrl() : "",
 bufferedRequest.pathSegments(),
 bufferedRequest.method().name(),
 inputJson);
 inputJson,
 null,
 headersAsMap(bufferedRequest.headers()));

 var response = underlying.execute(bufferedRequest, requestOptions);
 return new TeeingStreamHttpResponse(response, span, tracer);
Expand DownExpand Up@@ -153,7 +152,9 @@ public void close() {
 bufferedRequest.baseUrl() != null ? bufferedRequest.baseUrl() : "",
 bufferedRequest.pathSegments(),
 bufferedRequest.method().name(),
 inputJson);
 inputJson,
 null,
 headersAsMap(bufferedRequest.headers()));
 return underlying
 .executeAsync(bufferedRequest, requestOptions)
 .thenApply(
Expand DownExpand Up@@ -264,9 +265,39 @@ private void onStreamClosed() {
 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.
 // Anything outside 2xx, not just 4xx/5xx: both vendor SDKs treat success as
 // exactly 200..299, so a final 3xx that the http client did not follow (a 304, or
 // a redirect with no usable Location) is raised to the caller as an
 // UnexpectedStatusCodeException and must mark the span failed too.
 int statusCode = delegate.statusCode();
 if (statusCode < 200 || statusCode >= 300) {
 InstrumentationSemConv.tagLLMSpanHttpError(
 span, statusCode, new String(bytes, StandardCharsets.UTF_8));
 }

 // Wire-format bookkeeping lives in ResponseReassembler; this hands semconv
 // everything the response carried in one flat call. A null body (empty or
 // unparseable response) still tags the headers.
 // 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());
 try {
 var reassembled =
 ResponseReassembler.reassemble(bytes, timeToFirstTokenNanos.get());
 InstrumentationSemConv.tagLLMSpanResponse(
 tracer,
 span,
 InstrumentationSemConv.PROVIDER_NAME_ANTHROPIC,
 reassembled.body(),
 reassembled.timeToFirstTokenNanos(),
 headersAsMap(delegate.headers()));
 } catch (Exception e) {
 // Observability must never change the response behavior seen by the caller.
 log.error("Could not tag span from response buffer", e);
 }
 } finally {
 span.end();
 }
Expand DownExpand Up@@ -360,89 +391,25 @@ private void notifyClosed() {
 // Span tagging from buffered bytes
 // -------------------------------------------------------------------------

 private static void tagSpanFromBuffer(
 Tracer tracer, Span span, byte[] bytes, Long timeToFirstTokenNanos) {
 if (bytes.length == 0) return;
 try {
 String firstLine = firstNonEmptyLine(bytes);
 // Anthropic SSE starts with "event: message_start\ndata: ..." so we detect
 // either prefix. OpenAI SSE starts directly with "data:".
 boolean isSse =
 firstLine != null
 && (firstLine.startsWith("data:") || firstLine.startsWith("event:"));
 if (isSse) {
 tagSpanFromSseBytes(tracer, span, bytes, timeToFirstTokenNanos);
 } else {
 // Non-streaming: plain Message JSON — pass it whole, no time_to_first_token
 String responseJson = new String(bytes, StandardCharsets.UTF_8);
 InstrumentationSemConv.tagLLMSpanResponse(
 tracer,
 span,
 InstrumentationSemConv.PROVIDER_NAME_ANTHROPIC,
 responseJson,
 null);
 }
 } catch (Exception e) {
 log.error("Could not tag span from Anthropic response buffer", e);
 }
 }

 private static String firstNonEmptyLine(byte[] bytes) {
 int start = 0;
 for (int i = 0; i <= bytes.length; i++) {
 if (i == bytes.length || bytes[i] == '\n') {
 String line = new String(bytes, start, i - start, StandardCharsets.UTF_8).strip();
 if (!line.isEmpty()) return line;
 start = i + 1;
 }
 }
 return null;
 }

 /**
 * Anthropic SSE wire format has named events:
 *
 * <pre>
 * event: message_start
 * data: {"type":"message_start","message":{...}}
 *
 * event: content_block_delta
 * data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hi"}}
 * </pre>
 *
 * We only need the {@code data:} lines — the event name is redundant with the {@code type}
 * field inside the JSON. Feed each data payload to {@link MessageAccumulator} and serialize the
 * assembled {@link com.anthropic.models.messages.Message} for the span.
 * Adapts the anthropic sdk's {@code Headers} to the vendor-neutral shape {@link
 * InstrumentationSemConv} consumes. Returns an empty map on failure so a header-shape change
 * can never take down the tagging that follows it.
 */
 private static void tagSpanFromSseBytes(
 Tracer tracer, Span span, byte[] sseBytes, Long timeToFirstTokenNanos) {
 private static Map<String, List<String>> headersAsMap(
 @Nullable com.anthropic.core.http.Headers headers) {
 if (headers == null) {
 return Map.of();
 }
 try {
 var mapper = BraintrustJsonMapper.get();
 var reader =
 new BufferedReader(
 new InputStreamReader(
 new ByteArrayInputStream(sseBytes), StandardCharsets.UTF_8));
 var accumulator = MessageAccumulator.create();
 String line;
 while ((line = reader.readLine()) != null) {
 if (!line.startsWith("data:")) continue;
 String data = line.substring("data:".length()).strip();
 if (data.isEmpty()) continue;
 try {
 accumulator.accumulate(mapper.readValue(data, RawMessageStreamEvent.class));
 } catch (Exception ignored) {
 // skip unrecognized event types (e.g. ping)
 }
 var map = new HashMap<String, List<String>>();
 for (String name : headers.names()) {
 map.put(name, headers.values(name));
 }
 String assembledMessageJson = BraintrustJsonMapper.toJson(accumulator.message());
 InstrumentationSemConv.tagLLMSpanResponse(
 tracer,
 span,
 InstrumentationSemConv.PROVIDER_NAME_ANTHROPIC,
 assembledMessageJson,
 timeToFirstTokenNanos);
 return map;
 } catch (Exception e) {
 log.error("Could not parse Anthropic SSE buffer to tag streaming span output", e);
 log.debug("could not read headers", e);
 return Map.of();
 }
 }
}

2 changes: 2 additions & 0 deletions
.../dev/braintrust/instrumentation/anthropic/v2_2_0/auto/AnthropicInstrumentationModule.java

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -36,6 +36,8 @@ public List<String> getHelperClassNames() {
 MANUAL_INSTRUMENTATION_PACKAGE + "TracingHttpClient$ExtractedRequest",
 MANUAL_INSTRUMENTATION_PACKAGE + "BraintrustAnthropic",
 MANUAL_INSTRUMENTATION_PACKAGE + "ContextCapturingProxy",
 MANUAL_INSTRUMENTATION_PACKAGE + "ResponseReassembler",
 MANUAL_INSTRUMENTATION_PACKAGE + "ResponseReassembler$Result",
 "dev.braintrust.json.BraintrustJsonMapper",
 "dev.braintrust.instrumentation.InstrumentationSemConv");
 }
Expand Down
Loading
Loading