Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
13 changes: 11 additions & 2 deletions braintrust-sdk/instrumentation/anthropic_2_2_0/build.gradle
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,17 @@ muzzle {
pass {
group = 'com.anthropic'
module = 'anthropic-java'
// 3.x is a breaking major (e.g. HttpRequest.body() now returns Optional); not yet supported
// Upper-bounded below 3.0.0: 3.x is a breaking major (HttpRequest.body() now returns
// Optional) and the anthropic_3_0_0 module takes over.
versions = '[2.2.0,3.0.0)'
}
// Assert the classLoaderMatcher rejects 3.0.0+ so the two anthropic modules never both
// instrument the same client builder.
fail {
group = 'com.anthropic'
module = 'anthropic-java'
pinVersions '3.0.0'
}
}

dependencies {
Expand All @@ -30,7 +38,8 @@ dependencies {
testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
testImplementation "net.bytebuddy:byte-buddy-agent:${byteBuddyVersion}"
testRuntimeOnly "org.slf4j:slf4j-simple:${slf4jVersion}"
testImplementation 'com.anthropic:anthropic-java:2.2.0'
// Exercise later 2.x convenience APIs while retaining the 2.2.0 compilation baseline.
testImplementation 'com.anthropic:anthropic-java:2.75.0'
}

test {
Expand Down
Original file line number Diff line number Diff line change
@@ -1,14 +1,155 @@
package dev.braintrust.instrumentation.anthropic;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.AnthropicClientAsync;
import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.api.trace.Tracer;
import java.lang.reflect.Method;
import javax.annotation.Nullable;
import lombok.extern.slf4j.Slf4j;

/** Braintrust Anthropic client instrumentation. */
/**
* Braintrust Anthropic client instrumentation.
*
* <p>Dispatches to the module matching the anthropic-java version of each client: {@code
* v3_0_0.BraintrustAnthropic} for 3.0.0 and up, {@code v2_2_0.BraintrustAnthropic} otherwise.
*/
@Slf4j
public final class BraintrustAnthropic {

/**
* Sentinel class that first appeared in anthropic-java 3.0.0. The {@code
* AnthropicInstrumentationModule.classLoaderMatcher()}s key on the same class, so the manual
* path picks the same module the agent would.
*/
private static final String V3_SENTINEL = "com.anthropic.models.messages.AssistantMessageParam";

private static final String V3_0_0_WRAPPER =
"dev.braintrust.instrumentation.anthropic.v3_0_0.BraintrustAnthropic";

/**
* Whether the anthropic-java that defined a client class is 3.0.0+. Probed on the client's own
* classloader (not this class's), so it is correct per client even when several anthropic-java
* versions are loaded side by side.
*/
private static final ClassValue<Boolean> IS_V3 =
new ClassValue<>() {
@Override
protected Boolean computeValue(Class<?> clientClass) {
try {
Class.forName(V3_SENTINEL, false, clientClass.getClassLoader());
return true;
} catch (ClassNotFoundException | LinkageError e) {
return false;
}
}
};

/** Instrument Anthropic client with Braintrust traces. */
public static AnthropicClient wrap(OpenTelemetry openTelemetry, AnthropicClient client) {
if (isV3(client)) {
return forwardToV3(V3.WRAP_OTEL_SYNC, openTelemetry, client);
}
return dev.braintrust.instrumentation.anthropic.v2_2_0.BraintrustAnthropic.wrap(
openTelemetry, client);
}

/** Instrument an async Anthropic client with Braintrust traces. */
public static AnthropicClientAsync wrap(
OpenTelemetry openTelemetry, AnthropicClientAsync client) {
if (isV3(client)) {
return forwardToV3(V3.WRAP_OTEL_ASYNC, openTelemetry, client);
}
return dev.braintrust.instrumentation.anthropic.v2_2_0.BraintrustAnthropic.wrap(
openTelemetry, client);
}

/**
* Instruments a client using the given tracer, replacing any tracer it was previously
* instrumented with.
*/
public static AnthropicClient wrap(Tracer tracer, AnthropicClient client) {
if (isV3(client)) {
return forwardToV3(V3.WRAP_TRACER_SYNC, tracer, client);
}
return dev.braintrust.instrumentation.anthropic.v2_2_0.BraintrustAnthropic.wrap(
tracer, client);
}

/** Async counterpart of {@link #wrap(Tracer, AnthropicClient)}. */
public static AnthropicClientAsync wrap(Tracer tracer, AnthropicClientAsync client) {
if (isV3(client)) {
return forwardToV3(V3.WRAP_TRACER_ASYNC, tracer, client);
}
return dev.braintrust.instrumentation.anthropic.v2_2_0.BraintrustAnthropic.wrap(
tracer, client);
}

private static boolean isV3(Object client) {
return IS_V3.get(client.getClass());
}

@SuppressWarnings("unchecked")
private static <C> C forwardToV3(@Nullable Method wrap, Object tracing, C client) {
if (wrap == null) {
return client; // already logged when V3 was initialized
}
try {
return (C) wrap.invoke(null, tracing, client);
} catch (ReflectiveOperationException | LinkageError e) {
log.error(
"failed to forward to {}.wrap; client will not be instrumented",
V3_0_0_WRAPPER,
e);
return client;
}
}

/**
* {@code v3_0_0.BraintrustAnthropic.wrap} overloads, resolved on first use by a 3.x client.
* Reflection keeps this module from depending on {@code anthropic_3_0_0}, which would put
* anthropic-java 3.x on its compile classpath. A {@code null} method means the v3 module is
* unexpectedly missing; v2_2_0 is binary-incompatible with 3.x, so there is no safe fallback.
*/
private static final class V3 {
private static final Class<?> WRAPPER = loadWrapper();
static final Method WRAP_OTEL_SYNC = method(OpenTelemetry.class, AnthropicClient.class);
static final Method WRAP_OTEL_ASYNC =
method(OpenTelemetry.class, AnthropicClientAsync.class);
static final Method WRAP_TRACER_SYNC = method(Tracer.class, AnthropicClient.class);
static final Method WRAP_TRACER_ASYNC = method(Tracer.class, AnthropicClientAsync.class);

@Nullable
private static Class<?> loadWrapper() {
try {
return Class.forName(
V3_0_0_WRAPPER, true, BraintrustAnthropic.class.getClassLoader());
} catch (ClassNotFoundException | LinkageError e) {
log.error(
"anthropic-java 3.0.0+ detected but {} is unavailable; clients will not be"
+ " instrumented",
V3_0_0_WRAPPER,
e);
return null;
}
}

@Nullable
private static Method method(Class<?> tracingType, Class<?> clientType) {
if (WRAPPER == null) {
return null;
}
try {
return WRAPPER.getMethod("wrap", tracingType, clientType);
} catch (NoSuchMethodException | LinkageError e) {
log.error(
"{}.wrap({}, {}) is unavailable; such clients will not be instrumented",
V3_0_0_WRAPPER,
tracingType.getSimpleName(),
clientType.getSimpleName(),
e);
return null;
}
}
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@
import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.api.trace.Tracer;
import java.lang.reflect.Field;
import java.lang.reflect.Method;
import java.lang.reflect.Modifier;
import java.util.function.Consumer;
import lombok.extern.slf4j.Slf4j;
Expand Down Expand Up @@ -87,6 +88,25 @@ private static boolean instrument(Tracer tracer, Object client, boolean replaceT
}
}

/** Preserves the source's current tracer when withOptions replaces a service's transport. */
static boolean instrumentDerivedService(Object source, Object service) {
try {
ClientOptions options = getField(source, "clientOptions");
// async() can rebuild the SDK retry layer around the traced original transport.
HttpClient transport = options.httpClient();
if (!(transport instanceof TracingHttpClient)) {
transport = getField(options, "originalHttpClient");
}
if (transport instanceof TracingHttpClient tracing) {
return instrument(tracing.tracer(), service, false);
}
} catch (ReflectiveOperationException | RuntimeException e) {
log.error("failed to instrument derived anthropic service", e);
}
// Without a tracing transport, adding the context proxy would leak its internal header.
return false;
}

private static void instrumentHttpClient(Tracer tracer, Object client, boolean replaceTracer) {
int[] instrumented = {0};
forAllFields(
Expand All @@ -111,13 +131,69 @@ private static void instrumentHttpClient(Tracer tracer, Object client, boolean r
}
}

/** Swaps both HTTP client fields on a {@link ClientOptions} for tracing wrappers. */
/**
* Swaps both HTTP client fields on a {@link ClientOptions} for tracing wrappers and turns off
* the SDK's built-in tracing.
*/
private static void instrumentClientOptions(
Tracer tracer, ClientOptions clientOptions, boolean replaceTracer) {
disableNativeTracing(clientOptions);
try {
HttpClient original = getField(clientOptions, "originalHttpClient");
if (original instanceof TracingHttpClient tracing
&& !(clientOptions.httpClient() instanceof TracingHttpClient)) {
// async()/withOptions() rebuild the SDK transport around the traced original.
// Rebuild around its untraced delegate to retain retries without nested LLM spans.
var builder = clientOptions.toBuilder();
// Avoid the public setter's extra GC-closing wrapper for this shared transport.
setPrivateField(builder, "httpClient", tracing.underlying());
HttpClient rebuilt = builder.build().httpClient();
setPrivateField(
clientOptions,
"httpClient",
new TracingHttpClient(replaceTracer ? tracer : tracing.tracer(), rebuilt));
}
} catch (ReflectiveOperationException e) {
throw new RuntimeException(e);
}
swapHttpClient(tracer, clientOptions, "originalHttpClient", replaceTracer);
swapHttpClient(tracer, clientOptions, "httpClient", replaceTracer);
}

/**
* anthropic-java 2.72.0+ has built-in OTel tracing, on by default via GlobalOpenTelemetry,
* which would emit a duplicate {@code com.anthropic.sdk.java} span around each of ours. The SDK
* re-reads {@code ClientOptions.openTelemetry().traces().enabled()} on every API call, so
* replacing the field disables it for this client. Reflective because this module compiles
* against 2.2.0, which predates that API; a no-op on older versions. Best-effort: on failure we
* keep our instrumentation and accept the duplicate spans.
*/
private static void disableNativeTracing(ClientOptions clientOptions) {
Method openTelemetryGetter;
try {
openTelemetryGetter = ClientOptions.class.getMethod("openTelemetry");
} catch (NoSuchMethodException e) {
return; // anthropic-java < 2.72.0: no built-in tracing
}
try {
Object otel = openTelemetryGetter.invoke(clientOptions);
Object traces = otel.getClass().getMethod("traces").invoke(otel);
if (!(Boolean) traces.getClass().getMethod("enabled").invoke(traces)) {
return;
}
Object builder = otel.getClass().getMethod("toBuilder").invoke(otel);
builder.getClass().getMethod("traces", boolean.class).invoke(builder, false);
setPrivateField(
clientOptions,
"openTelemetry",
builder.getClass().getMethod("build").invoke(builder));
} catch (ReflectiveOperationException | RuntimeException e) {
log.warn(
"failed to disable anthropic-java built-in tracing; spans may be duplicated",
e);
}
}

private static void swapHttpClient(
Tracer tracer, ClientOptions clientOptions, String fieldName, boolean replaceTracer) {
try {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,11 @@ public Object invoke(Object proxy, Method method, Object[] args) throws Throwabl
default -> "ContextCapturingProxy(" + delegate + ")"; // toString
};
}
// Convenience overloads must call back through the proxy once they create Params.
// Invoking them on the delegate would bypass context capture before async dispatch.
if (method.isDefault()) {
return InvocationHandler.invokeDefault(proxy, method, args);
}
Object[] invokeArgs = injectContextHeader(args);
Object result;
try {
Expand All @@ -96,6 +101,12 @@ public Object invoke(Object proxy, Method method, Object[] args) throws Throwabl
if (result != null
&& returnType.isInterface()
&& returnType.getName().startsWith("com.anthropic.")) {
// withOptions can replace the transport that strips our private context header.
// Only keep capturing context if the derived service is instrumented too.
if (method.getName().equals("withOptions")
&& !BraintrustAnthropic.instrumentDerivedService(delegate, result)) {
return result;
}
return Proxy.newProxyInstance(
returnType.getClassLoader(),
new Class<?>[] {returnType},
Expand Down
Loading
Loading