From 7dfdb65b44f48694b3556d272f6461a3ba1fba5a Mon Sep 17 00:00:00 2001 From: Andrew Kent Date: Thu, 2 Oct 2025 16:28:50 -0600 Subject: [PATCH 1/2] move developer docs to CONTRIBUTING.md --- CONTRIBUTING.md | 34 ++++++++++++++++++++++++++++++++++ README.md | 35 ----------------------------------- 2 files changed, 34 insertions(+), 35 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..e347c5b --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,34 @@ +# SDK Developer Documentation + +This file documents developing the SDK itself. If you simply wish to use the SDK or run examples, see [README.md](./README.md) + +## Setup + +- 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 + +OpenTelemetry provides a local collector with a debug exporter which logs all traces, logs, and metrics to stdout. + +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:0.136.0 # latest release will probably also work +``` + +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 +``` diff --git a/README.md b/README.md index cc6ba68..58c6bc7 100644 --- a/README.md +++ b/README.md @@ -51,38 +51,3 @@ The SDK uses a standard slf4j logger and will use the default log level (or not All Braintrust loggers will log into the `dev.braintrust` namespace. To adjust the log level, consult your logger documentation. For example, to enable debug logging for slf4j-simple you would set the system property `org.slf4j.simpleLogger.log.dev.braintrust=DEBUG` - -# SDK Developer Docs - -The remaining sections document developing the SDK itself. Nothing below is required if you simply wish to use the SDK or run examples. - -## Setup - -- 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 - -OpenTelemetry provides a local collector with a debug exporter which logs all traces, logs, and metrics to stdout. - -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:0.136.0 # latest release will probably also work -``` - -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 -``` From bd0c0717fd03a865288938f56077f1d89f4c44d4 Mon Sep 17 00:00:00 2001 From: Andrew Kent Date: Thu, 2 Oct 2025 16:32:43 -0600 Subject: [PATCH 2/2] remove SDKSpec stub file --- src/main/java/dev/braintrust/eval/Eval.java | 3 +-- src/main/java/dev/braintrust/spec/SdkSpec.java | 12 ------------ .../braintrust/trace/BraintrustSpanProcessor.java | 4 +--- .../java/dev/braintrust/trace/BraintrustTracing.java | 1 + src/test/java/dev/braintrust/eval/EvalTest.java | 3 +-- 5 files changed, 4 insertions(+), 19 deletions(-) delete mode 100644 src/main/java/dev/braintrust/spec/SdkSpec.java diff --git a/src/main/java/dev/braintrust/eval/Eval.java b/src/main/java/dev/braintrust/eval/Eval.java index 1332c40..a45baa2 100644 --- a/src/main/java/dev/braintrust/eval/Eval.java +++ b/src/main/java/dev/braintrust/eval/Eval.java @@ -4,7 +4,6 @@ import com.fasterxml.jackson.databind.ObjectMapper; import dev.braintrust.api.BraintrustApiClient; import dev.braintrust.config.BraintrustConfig; -import dev.braintrust.spec.SdkSpec; import dev.braintrust.trace.BraintrustContext; import dev.braintrust.trace.BraintrustTracing; import io.opentelemetry.api.common.AttributeKey; @@ -26,7 +25,7 @@ */ public final class Eval { private static final AttributeKey PARENT = - AttributeKey.stringKey(SdkSpec.Attributes.PARENT); + AttributeKey.stringKey(BraintrustTracing.PARENT_KEY); private static final ObjectMapper JSON_MAPPER = new com.fasterxml.jackson.databind.ObjectMapper(); private final @Nonnull String experimentName; diff --git a/src/main/java/dev/braintrust/spec/SdkSpec.java b/src/main/java/dev/braintrust/spec/SdkSpec.java deleted file mode 100644 index 811956b..0000000 --- a/src/main/java/dev/braintrust/spec/SdkSpec.java +++ /dev/null @@ -1,12 +0,0 @@ -package dev.braintrust.spec; - -public final class SdkSpec { - - public static final class Attributes { - public static final String PARENT = "braintrust.parent"; - } - - public static final class Context {} - - private SdkSpec() {} -} diff --git a/src/main/java/dev/braintrust/trace/BraintrustSpanProcessor.java b/src/main/java/dev/braintrust/trace/BraintrustSpanProcessor.java index fb78db0..dbc94da 100644 --- a/src/main/java/dev/braintrust/trace/BraintrustSpanProcessor.java +++ b/src/main/java/dev/braintrust/trace/BraintrustSpanProcessor.java @@ -1,7 +1,6 @@ package dev.braintrust.trace; import dev.braintrust.config.BraintrustConfig; -import dev.braintrust.spec.SdkSpec; import io.opentelemetry.api.common.AttributeKey; import io.opentelemetry.context.Context; import io.opentelemetry.sdk.common.CompletableResultCode; @@ -21,10 +20,9 @@ */ @Slf4j class BraintrustSpanProcessor implements SpanProcessor { - // Braintrust-specific attributes public static final AttributeKey PARENT = - AttributeKey.stringKey(SdkSpec.Attributes.PARENT); + AttributeKey.stringKey(BraintrustTracing.PARENT_KEY); private final BraintrustConfig config; private final SpanProcessor delegate; diff --git a/src/main/java/dev/braintrust/trace/BraintrustTracing.java b/src/main/java/dev/braintrust/trace/BraintrustTracing.java index 9f636a6..778c3a8 100644 --- a/src/main/java/dev/braintrust/trace/BraintrustTracing.java +++ b/src/main/java/dev/braintrust/trace/BraintrustTracing.java @@ -29,6 +29,7 @@ */ @Slf4j public final class BraintrustTracing { + public static final String PARENT_KEY = "braintrust.parent"; static final String OTEL_SERVICE_NAME = "braintrust-app"; static final String INSTRUMENTATION_NAME = "braintrust-java"; static final String INSTRUMENTATION_VERSION = loadVersionFromProperties(); diff --git a/src/test/java/dev/braintrust/eval/EvalTest.java b/src/test/java/dev/braintrust/eval/EvalTest.java index b7b76bc..027989f 100644 --- a/src/test/java/dev/braintrust/eval/EvalTest.java +++ b/src/test/java/dev/braintrust/eval/EvalTest.java @@ -4,7 +4,6 @@ import dev.braintrust.api.BraintrustApiClient; import dev.braintrust.config.BraintrustConfig; -import dev.braintrust.spec.SdkSpec; import dev.braintrust.trace.BraintrustTracing; import dev.braintrust.trace.BraintrustTracingTest; import io.opentelemetry.api.GlobalOpenTelemetry; @@ -74,7 +73,7 @@ public void evalOtelTraceWithProperAttributes() { span -> { var parent = span.getAttributes() - .get(AttributeKey.stringKey(SdkSpec.Attributes.PARENT)); + .get(AttributeKey.stringKey(BraintrustTracing.PARENT_KEY)); assertEquals( "experiment_id:" + experiment.id(), parent,