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 -``` 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,