Map OpenAI cached tokens in Java SDK

braintrust-sdk/src/main/java/dev/braintrust/instrumentation/InstrumentationSemConv.java

@@ -165,6 +165,12 @@ private static void tagOpenAIResponse(
             if (usage.has("completion_tokens"))
                 metrics.put("completion_tokens", usage.get("completion_tokens"));
             if (usage.has("total_tokens")) metrics.put("tokens", usage.get("total_tokens"));
+            if (usage.has("prompt_tokens_details")) {
+                JsonNode details = usage.get("prompt_tokens_details");
+                if (details.has("cached_tokens")) {
+                    metrics.put("prompt_cached_tokens", details.get("cached_tokens"));
+                }
+            }
             // Responses API field names
             if (usage.has("input_tokens")) metrics.put("prompt_tokens", usage.get("input_tokens"));
             if (usage.has("output_tokens"))
@@ -174,6 +180,12 @@ private static void tagOpenAIResponse(
                         "tokens",
                         usage.get("input_tokens").asLong() + usage.get("output_tokens").asLong());
             }
+            if (usage.has("input_tokens_details")) {
+                JsonNode details = usage.get("input_tokens_details");
+                if (details.has("cached_tokens")) {
+                    metrics.put("prompt_cached_tokens", details.get("cached_tokens"));
+                }
+            }
             // Reasoning tokens (Responses API)
             if (usage.has("output_tokens_details")) {
                 JsonNode details = usage.get("output_tokens_details");

braintrust-sdk/src/test/java/dev/braintrust/instrumentation/InstrumentationSemConvTest.java

@@ -0,0 +1,99 @@
+package dev.braintrust.instrumentation;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import io.opentelemetry.api.common.AttributeKey;
+import io.opentelemetry.sdk.OpenTelemetrySdk;
+import io.opentelemetry.sdk.testing.exporter.InMemorySpanExporter;
+import io.opentelemetry.sdk.trace.SdkTracerProvider;
+import io.opentelemetry.sdk.trace.export.SimpleSpanProcessor;
+import lombok.SneakyThrows;
+import org.junit.jupiter.api.Test;
+
+class InstrumentationSemConvTest {
+    private static final ObjectMapper JSON_MAPPER = new ObjectMapper();
+    private static final AttributeKey<String> BRAINTRUST_METRICS =
+            AttributeKey.stringKey("braintrust.metrics");
+
+    @Test
+    @SneakyThrows
+    void mapsOpenAIChatCompletionsCachedTokens() {
+        JsonNode metrics =
+                metricsForOpenAIResponse(
+                        """
+                        {
+                          "choices": [],
+                          "usage": {
+                            "prompt_tokens": 100,
+                            "completion_tokens": 10,
+                            "total_tokens": 110,
+                            "prompt_tokens_details": {
+                              "cached_tokens": 80
+                            }
+                          }
+                        }
+                        """);
+
+        assertEquals(100, metrics.get("prompt_tokens").asInt());
+        assertEquals(10, metrics.get("completion_tokens").asInt());
+        assertEquals(110, metrics.get("tokens").asInt());
+        assertEquals(80, metrics.get("prompt_cached_tokens").asInt());
+    }
+
+    @Test
+    @SneakyThrows
+    void mapsOpenAIResponsesCachedTokens() {
+        JsonNode metrics =
+                metricsForOpenAIResponse(
+                        """
+                        {
+                          "output": [],
+                          "usage": {
+                            "input_tokens": 100,
+                            "input_tokens_details": {
+                              "cached_tokens": 80
+                            },
+                            "output_tokens": 10,
+                            "output_tokens_details": {
+                              "reasoning_tokens": 3
+                            },
+                            "total_tokens": 110
+                          }
+                        }
+                        """);
+
+        assertEquals(100, metrics.get("prompt_tokens").asInt());
+        assertEquals(10, metrics.get("completion_tokens").asInt());
+        assertEquals(110, metrics.get("tokens").asInt());
+        assertEquals(80, metrics.get("prompt_cached_tokens").asInt());
+        assertEquals(3, metrics.get("completion_reasoning_tokens").asInt());
+    }
+
+    @SneakyThrows
+    private static JsonNode metricsForOpenAIResponse(String responseJson) {
+        InMemorySpanExporter exporter = InMemorySpanExporter.create();
+        SdkTracerProvider tracerProvider =
+                SdkTracerProvider.builder()
+                        .addSpanProcessor(SimpleSpanProcessor.create(exporter))
+                        .build();
+        try {
+            OpenTelemetrySdk openTelemetry =
+                    OpenTelemetrySdk.builder().setTracerProvider(tracerProvider).build();
+            var span = openTelemetry.getTracer("test").spanBuilder("llm").startSpan();
+            try {
+                InstrumentationSemConv.tagLLMSpanResponse(
+                        span, InstrumentationSemConv.PROVIDER_NAME_OPENAI, responseJson);
+            } finally {
+                span.end();
+            }
+
+            String metricsJson =
+                    exporter.getFinishedSpanItems().get(0).getAttributes().get(BRAINTRUST_METRICS);
+            return JSON_MAPPER.readTree(metricsJson);
+        } finally {
+            tracerProvider.close();
+        }
+    }
+}