initial java autoinstrumentation

Author: realark

.github/workflows/publish-release-from-tag.yml

@@ -100,19 +100,24 @@ jobs:
           # Strip 'v' prefix to get the actual version used by Gradle
           VERSION="${TAG#v}"
 
-          # Find the built JAR files (version does NOT include 'v' prefix)
-          MAIN_JAR=$(find build/libs -name "*-${VERSION}.jar" ! -name "*-sources.jar" ! -name "*-javadoc.jar" | head -1)
-          SOURCES_JAR=$(find build/libs -name "*-${VERSION}-sources.jar" | head -1)
-          JAVADOC_JAR=$(find build/libs -name "*-${VERSION}-javadoc.jar" | head -1)
+          # braintrust-sdk artifacts
+          SDK_MAIN_JAR=$(find braintrust-sdk/build/libs -name "*-${VERSION}.jar" ! -name "*-sources.jar" ! -name "*-javadoc.jar" | head -1)
+          SDK_SOURCES_JAR=$(find braintrust-sdk/build/libs -name "*-${VERSION}-sources.jar" | head -1)
+          SDK_JAVADOC_JAR=$(find braintrust-sdk/build/libs -name "*-${VERSION}-javadoc.jar" | head -1)
 
-          echo "main-jar=$MAIN_JAR" >> $GITHUB_OUTPUT
-          echo "sources-jar=$SOURCES_JAR" >> $GITHUB_OUTPUT
-          echo "javadoc-jar=$JAVADOC_JAR" >> $GITHUB_OUTPUT
+          # braintrust-java-agent artifact (single fat jar, no sources/javadoc)
+          AGENT_JAR=$(find braintrust-java-agent/build/libs -name "braintrust-java-agent-${VERSION}.jar" | head -1)
+
+          echo "sdk-main-jar=$SDK_MAIN_JAR" >> $GITHUB_OUTPUT
+          echo "sdk-sources-jar=$SDK_SOURCES_JAR" >> $GITHUB_OUTPUT
+          echo "sdk-javadoc-jar=$SDK_JAVADOC_JAR" >> $GITHUB_OUTPUT
+          echo "agent-jar=$AGENT_JAR" >> $GITHUB_OUTPUT
 
           echo "Found artifacts:"
-          echo "  Main JAR: $MAIN_JAR"
-          echo "  Sources JAR: $SOURCES_JAR"
-          echo "  Javadoc JAR: $JAVADOC_JAR"
+          echo "  SDK Main JAR: $SDK_MAIN_JAR"
+          echo "  SDK Sources JAR: $SDK_SOURCES_JAR"
+          echo "  SDK Javadoc JAR: $SDK_JAVADOC_JAR"
+          echo "  Agent JAR: $AGENT_JAR"
 
       - name: Create GitHub Release
         run: |
@@ -123,18 +128,16 @@ jobs:
             --generate-notes \
             --title "Release $TAG"
 
-          # Upload artifacts if they exist
-          if [[ -n "${{ steps.find-artifacts.outputs.main-jar }}" && -f "${{ steps.find-artifacts.outputs.main-jar }}" ]]; then
-            gh release upload "$TAG" "${{ steps.find-artifacts.outputs.main-jar }}"
-          fi
-
-          if [[ -n "${{ steps.find-artifacts.outputs.sources-jar }}" && -f "${{ steps.find-artifacts.outputs.sources-jar }}" ]]; then
-            gh release upload "$TAG" "${{ steps.find-artifacts.outputs.sources-jar }}"
-          fi
-
-          if [[ -n "${{ steps.find-artifacts.outputs.javadoc-jar }}" && -f "${{ steps.find-artifacts.outputs.javadoc-jar }}" ]]; then
-            gh release upload "$TAG" "${{ steps.find-artifacts.outputs.javadoc-jar }}"
-          fi
+          # Upload SDK artifacts
+          for jar in \
+            "${{ steps.find-artifacts.outputs.sdk-main-jar }}" \
+            "${{ steps.find-artifacts.outputs.sdk-sources-jar }}" \
+            "${{ steps.find-artifacts.outputs.sdk-javadoc-jar }}" \
+            "${{ steps.find-artifacts.outputs.agent-jar }}"; do
+            if [[ -n "$jar" && -f "$jar" ]]; then
+              gh release upload "$TAG" "$jar"
+            fi
+          done
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       - name: Publish to Sonatype

.pre-commit-config.yaml

@@ -0,0 +1,12 @@
+// Java plugin, toolchain (Java 17 / Adoptium), options.release, and repositories
+// are inherited from the parent's subprojects {} block.
+
+// These are compile-time dependencies so bootstrap classes can reference OTel types.
+// At runtime, the actual OTel JARs are bundled as normal .class files in the agent JAR
+// and placed on the bootstrap classpath via Instrumentation.appendToBootstrapClassLoaderSearch().
+dependencies {
+  compileOnly "io.opentelemetry:opentelemetry-api:${otelVersion}"
+  compileOnly "io.opentelemetry:opentelemetry-sdk:${otelVersion}"
+  compileOnly "io.opentelemetry:opentelemetry-sdk-extension-autoconfigure:${otelVersion}"
+  compileOnly "io.opentelemetry:opentelemetry-sdk-extension-autoconfigure-spi:${otelVersion}"
+}

Makefile

@@ -0,0 +1,31 @@
+package dev.braintrust.bootstrap;
+
+import java.util.concurrent.atomic.AtomicInteger;
+import java.util.concurrent.atomic.AtomicReference;
+
+/** Globally available bootstrap classpath resource class */
+public class BraintrustBridge {
+    public static final String INSTRUMENTATION_NAME = "braintrust-java";
+
+    /**
+     * Diagnostic utility tracking the number of times braintrust otel has been installed.
+     *
+     * <p>In a production app, this should be zero until global otel get() is invoked, then it
+     * should remain at 1 for the rest of app's lifetime.
+     */
+    public static final AtomicInteger otelInstallCount = new AtomicInteger(0);
+
+    private static final AtomicReference<BraintrustClassLoader> agentClassLoaderRef =
+            new AtomicReference<>();
+
+    public static BraintrustClassLoader getAgentClassLoader() {
+        return agentClassLoaderRef.get();
+    }
+
+    public static void setAgentClassLoaderIfAbsent(BraintrustClassLoader classLoader) {
+        var witness = agentClassLoaderRef.compareAndExchange(null, classLoader);
+        if (null != witness) {
+            throw new IllegalStateException("agent classloader must only be set once");
+        }
+    }
+}

braintrust-java-agent/bootstrap/build.gradle

@@ -0,0 +1,130 @@
+package dev.braintrust.bootstrap;
+
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.net.URL;
+import java.security.CodeSource;
+import java.security.SecureClassLoader;
+import java.security.cert.Certificate;
+import java.util.Collections;
+import java.util.Enumeration;
+import java.util.jar.JarEntry;
+import java.util.jar.JarFile;
+
+/**
+ * A classloader that loads agent-internal classes from {@code .classdata} entries inside the agent
+ * JAR.
+ *
+ * <p>Classes stored under the {@code internal/} prefix with a {@code .classdata} extension are
+ * invisible to the JVM's default classloading mechanism. This classloader knows how to find them,
+ * providing full classloader isolation between the agent's internals and the application's
+ * classpath.
+ */
+public class BraintrustClassLoader extends SecureClassLoader {
+    private static final String ENTRY_PREFIX = "internal/";
+    private static final String CLASS_DATA_SUFFIX = ".classdata";
+
+    private final JarFile agentJarFile;
+    private final CodeSource agentCodeSource;
+    private final String agentResourcePrefix;
+
+    static {
+        registerAsParallelCapable();
+    }
+
+    /**
+     * Creates a new BraintrustClassLoader.
+     *
+     * @param agentJarURL the URL of the agent JAR file (from the -javaagent path)
+     * @param parent the parent classloader (typically the system/platform classloader)
+     */
+    public BraintrustClassLoader(URL agentJarURL, ClassLoader parent) throws Exception {
+        super(parent);
+        this.agentJarFile = new JarFile(new java.io.File(agentJarURL.toURI()), false);
+        this.agentCodeSource = new CodeSource(agentJarURL, (Certificate[]) null);
+        this.agentResourcePrefix = "jar:file:" + agentJarFile.getName() + "!/";
+    }
+
+    @Override
+    protected Class<?> findClass(String name) throws ClassNotFoundException {
+        // Convert "dev.braintrust.agent.internal.BraintrustAgent"
+        //      -> "internal/dev/braintrust/agent/internal/BraintrustAgent.classdata"
+        String entryName = ENTRY_PREFIX + name.replace('.', '/') + CLASS_DATA_SUFFIX;
+        JarEntry entry = agentJarFile.getJarEntry(entryName);
+        if (entry == null) {
+            throw new ClassNotFoundException(name);
+        }
+
+        byte[] classBytes = readEntry(entry, name);
+        return defineClass(name, classBytes, 0, classBytes.length, agentCodeSource);
+    }
+
+    @Override
+    protected URL findResource(String name) {
+        // For .class resource lookups, map to .classdata
+        String entryName;
+        if (name.endsWith(".class")) {
+            entryName =
+                    ENTRY_PREFIX
+                            + name.substring(0, name.length() - ".class".length())
+                            + CLASS_DATA_SUFFIX;
+        } else {
+            entryName = ENTRY_PREFIX + name;
+        }
+
+        JarEntry entry = agentJarFile.getJarEntry(entryName);
+        if (entry != null) {
+            try {
+                return new URL(agentResourcePrefix + entryName);
+            } catch (java.net.MalformedURLException e) {
+                // fall through
+            }
+        }
+        return null;
+    }
+
+    @Override
+    protected Enumeration<URL> findResources(String name) {
+        URL resource = findResource(name);
+        if (resource != null) {
+            return Collections.enumeration(Collections.singletonList(resource));
+        }
+        return Collections.emptyEnumeration();
+    }
+
+    private byte[] readEntry(JarEntry entry, String className) throws ClassNotFoundException {
+        int size = (int) entry.getSize();
+        if (size < 0) {
+            try (InputStream in = agentJarFile.getInputStream(entry);
+                    ByteArrayOutputStream out = new ByteArrayOutputStream()) {
+                byte[] buf = new byte[8192];
+                int bytesRead;
+                while ((bytesRead = in.read(buf)) >= 0) {
+                    out.write(buf, 0, bytesRead);
+                }
+                return out.toByteArray();
+            } catch (IOException e) {
+                throw new ClassNotFoundException(className, e);
+            }
+        }
+        byte[] buf = new byte[size];
+        try (InputStream in = agentJarFile.getInputStream(entry)) {
+            int offset = 0;
+            while (offset < size) {
+                int bytesRead = in.read(buf, offset, size - offset);
+                if (bytesRead < 0) {
+                    break;
+                }
+                offset += bytesRead;
+            }
+            if (offset != size) {
+                throw new ClassNotFoundException(
+                        className + " (incomplete read: " + offset + "/" + size + " bytes)");
+            }
+            return buf;
+        } catch (IOException e) {
+            throw new ClassNotFoundException(className, e);
+        }
+    }
+}