From 81966970eb36368b6129335b4a92772590c6aa0a Mon Sep 17 00:00:00 2001 From: Andrew Kent Date: Wed, 1 Oct 2025 13:41:53 -0600 Subject: [PATCH] update docs --- README.md | 55 ++++++++++++++----- build.gradle | 8 --- .../braintrust/api/BraintrustApiClient.java | 4 ++ .../braintrust/config/BraintrustConfig.java | 8 ++- .../openai/BraintrustOpenAI.java | 1 + 5 files changed, 52 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index 9e729ac..cc6ba68 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,31 @@ # Braintrust Java SDK -An OpenTelemetry-based Braintrust SDK for Java 17 and up. Contains instrumentation for major AI vendors (OpenAI, Anthropic, etc) +An OpenTelemetry-based Braintrust SDK for Java 17 and up. Contains: + +- Instrumentation for major AI vendors (OpenAI, Anthropic, etc) +- LLM Eval framework for sending Experiments to Braintrust +- Utils for sending Open Telemetry data to Braintrust If you're simply looking to call the Braintrust API with Java code, see [https://github.com/braintrustdata/braintrust-java](https://github.com/braintrustdata/braintrust-java) This SDK is currently is in BETA status and APIs may change -# Quickstart (Running examples and reporting data to Braintrust) + + + + + + + + + + + +# Examples + +All examples can be found here: [./examples/src/main/java/dev/braintrust/examples](./examples/src/main/java/dev/braintrust/examples) -Prerequisites: +To run the examples from the command line you need: - A Braintrust account and a valid BRAINTRUST_API_KEY - Java 17 (or greater): - macOS: `brew install openjdk@17` @@ -25,21 +42,32 @@ If you wish to see all examples run: ./gradlew :examples:tasks --group="Braintrust SDK Examples" ``` -Source code for all examples can be found here: [./examples/src/main/java/dev/braintrust/examples](./examples/src/main/java/dev/braintrust/examples) - If you wish to hack around with the examples you can modify source then re-run the gradle task. -# Using the SDK in your code +## Logging + +The SDK uses a standard slf4j logger and will use the default log level (or not log at all if slf4j is not installed). + +All Braintrust loggers will log into the `dev.braintrust` namespace. To adjust the log level, consult your logger documentation. -TODO: update this section when we have published our first release +For example, to enable debug logging for slf4j-simple you would set the system property `org.slf4j.simpleLogger.log.dev.braintrust=DEBUG` -# Developer Setup +# SDK Developer Docs -This section documents how to set up your machine to develop the SDK. This is not required if you simply wish to use the SDK or run examples. +The remaining sections document developing the SDK itself. Nothing below is required if you simply wish to use the SDK or run examples. ## Setup -TODO -- document sdkman, gradle, etc +- Install JDK 17 + - Recommended to use SDK Man: https://sdkman.io/ and `sdk use java 17.0.16-tem` +- Ensure you can run all tests and checks: `./gradlew check build` +- IDE Setup + - Intellij Community + - Ubuntu: `sudo snap install intellij-idea-community` + - Other: https://www.jetbrains.com/idea/download/ +- (Optional) Install pre-commit hooks: `./gradlew installGitHooks` + - These hooks automatically run common checks for you but CI also runs the same checks before merging to the main branch is allowed + - NOTE: this will overwrite existing hooks. Take backups before running ## Running a local OpenTelemetry collector @@ -49,15 +77,12 @@ To run a local collector: ``` # Assumes you're in the repo root -docker run --rm -p 4318:4318 -v "$PWD/localcollector/collector.yaml:/etc/otelcol/config.yaml" otel/opentelemetry-collector:latest +docker run --rm -p 4318:4318 -v "$PWD/localcollector/collector.yaml:/etc/otelcol/config.yaml" otel/opentelemetry-collector:0.136.0 # latest release will probably also work ``` -To send otel data to the local collector: +To send Braintrust otel data to the local collector: ``` # assumes you have BRAINTRUST_API_KEY and OPENAI_API_KEY exported export BRAINTRUST_API_URL="http://localhost:4318" ; export BRAINTRUST_TRACES_PATH="/v1/traces"; export BRAINTRUST_LOGS_PATH="/v1/logs" ; ./gradlew :examples:runOpenAIInstrumentation ``` - - -## TODO: finish these docs diff --git a/build.gradle b/build.gradle index ba7ccda..4f2c907 100644 --- a/build.gradle +++ b/build.gradle @@ -149,11 +149,3 @@ task installGitHooks(type: Exec) { group = 'Build Setup' commandLine 'bash', 'scripts/install-hooks.sh' } - -// Run installGitHooks after project evaluation -afterEvaluate { - // Install hooks when building for the first time - tasks.named('build').configure { - dependsOn installGitHooks - } -} diff --git a/src/main/java/dev/braintrust/api/BraintrustApiClient.java b/src/main/java/dev/braintrust/api/BraintrustApiClient.java index 50e5f10..1650373 100644 --- a/src/main/java/dev/braintrust/api/BraintrustApiClient.java +++ b/src/main/java/dev/braintrust/api/BraintrustApiClient.java @@ -19,6 +19,10 @@ import java.util.concurrent.ExecutionException; import lombok.extern.slf4j.Slf4j; +/** + * Provides the necessary API calls for the Braintrust SDK. Users of the SDK should favor using + * {@link dev.braintrust.eval.Eval} or {@link dev.braintrust.trace.BraintrustTracing} + */ public interface BraintrustApiClient { /** Creates or gets a project by name. */ Project getOrCreateProject(String projectName); diff --git a/src/main/java/dev/braintrust/config/BraintrustConfig.java b/src/main/java/dev/braintrust/config/BraintrustConfig.java index e18a5d1..5c0a97e 100644 --- a/src/main/java/dev/braintrust/config/BraintrustConfig.java +++ b/src/main/java/dev/braintrust/config/BraintrustConfig.java @@ -10,7 +10,13 @@ import lombok.Getter; import lombok.experimental.Accessors; -/** Configuration for Braintrust SDK */ +/** + * Configuration for Braintrust SDK with sane defaults. + * + *

Most SDK users will want to use envars to configure all Braintrust settings. + * + *

However, it's also possible to override any envar during config construction. + */ @Getter @Accessors(fluent = true) public final class BraintrustConfig extends BaseConfig { diff --git a/src/main/java/dev/braintrust/instrumentation/openai/BraintrustOpenAI.java b/src/main/java/dev/braintrust/instrumentation/openai/BraintrustOpenAI.java index 0a36965..39c01a6 100644 --- a/src/main/java/dev/braintrust/instrumentation/openai/BraintrustOpenAI.java +++ b/src/main/java/dev/braintrust/instrumentation/openai/BraintrustOpenAI.java @@ -4,6 +4,7 @@ import dev.braintrust.instrumentation.openai.otel.OpenAITelemetry; import io.opentelemetry.api.OpenTelemetry; +/** Braintrust OpenAI client instrumentation. */ public class BraintrustOpenAI { /** Instrument openai client with braintrust traces */ public static OpenAIClient wrapOpenAI(OpenTelemetry openTelemetry, OpenAIClient openAIClient) {