Skip to content

Commit 9bc2e79

Browse files
authored
refactor(otel)!: Decouple from OpenTelemetry SDK versions (#2765)
Closes [#2745](#2745) - Remove OpenTelemetry SDK and exporter peer dependencies from `@braintrust/otel`, so applications can select compatible OpenTelemetry 1, 2, or 3 packages. - **Breaking:** `BraintrustSpanProcessor` and `BraintrustExporter` now wrap instances supplied by the application. Previously, they created their own exporter and batch processor, which could batch spans twice and force a flush after each export. ```ts import { BraintrustExporter, BraintrustSpanProcessor, braintrustOtlpConfig, } from "@braintrust/otel"; import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http"; import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base"; const exporter = new BraintrustExporter({ // New helper supplies the Braintrust endpoint and headers. exporter: new OTLPTraceExporter( braintrustOtlpConfig({ parent: "project_name:my-project" }), ), }); const processor = new BraintrustSpanProcessor({ processor: new BatchSpanProcessor(exporter), // OpenTelemetry 1/2 }); ``` - Require an explicit project or experiment through `parent` or `BRAINTRUST_PARENT`, instead of silently using a default project. - Use public OpenTelemetry context APIs instead of private storage internals, and preserve sampling flags and trace state when mixing Braintrust and OpenTelemetry spans. - Flush all registered OpenTelemetry processors before scorer queries. Previously, each registration replaced the previous callback; registrations now also get removed on shutdown.
1 parent 6357372 commit 9bc2e79

66 files changed

Lines changed: 6578 additions & 2806 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
"@braintrust/otel": major
3+
"braintrust": patch
4+
---
5+
6+
refactor(otel)!: Decouple from OpenTelemetry SDK versions

‎.github/workflows/checks.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -472,7 +472,7 @@ jobs:
472472
fail-fast: false
473473
matrix:
474474
node-version: [22.18.0, 24, 26]
475-
test-dir: [otel-v1, otel-v2]
475+
test-dir: [otel-v1, otel-v2, otel-v3]
476476
steps:
477477
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
478478
- name: Set up Docker Buildx

‎e2e/config/pr-comment-scenarios.json‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1072,5 +1072,36 @@
10721072
"label": "v4 latest"
10731073
}
10741074
]
1075+
},
1076+
{
1077+
"scenarioDirName": "otel-sdk-compat",
1078+
"label": "OpenTelemetry SDK compatibility",
1079+
"metadataScenario": "otel-sdk-compat",
1080+
"variants": [
1081+
{
1082+
"variantKey": "otel-v1",
1083+
"label": "v1 pinned"
1084+
},
1085+
{
1086+
"variantKey": "otel-v1-latest",
1087+
"label": "v1 latest"
1088+
},
1089+
{
1090+
"variantKey": "otel-v2",
1091+
"label": "v2 pinned"
1092+
},
1093+
{
1094+
"variantKey": "otel-v2-latest",
1095+
"label": "v2 latest"
1096+
},
1097+
{
1098+
"variantKey": "otel-v3",
1099+
"label": "v3 pinned"
1100+
},
1101+
{
1102+
"variantKey": "otel-v3-latest",
1103+
"label": "v3 latest"
1104+
}
1105+
]
10751106
}
10761107
]

‎e2e/package.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@
2323
"typescript": "5.4.4",
2424
"vitest": "catalog:",
2525
"zod": "4.3.6",
26-
"vite-plus": "catalog:"
26+
"vite-plus": "catalog:",
27+
"@opentelemetry/exporter-trace-otlp-http": "0.217.0"
2728
}
2829
}

‎e2e/scenarios/ai-sdk-otel-export/scenario.impl.ts‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
1+
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
12
import { SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base";
2-
import { BraintrustExporter } from "@braintrust/otel";
3+
import { BraintrustExporter, braintrustOtlpConfig } from "@braintrust/otel";
34
import {
45
createTracerProvider,
56
getTestRunId,
@@ -32,9 +33,13 @@ export async function runAISDKOtelExport(options: AISDKOtelScenarioOptions) {
3233
const projectName = scopedName("e2e-ai-sdk-otel-export", testRunId);
3334

3435
const exporter = new BraintrustExporter({
35-
apiKey: process.env.BRAINTRUST_API_KEY!,
36-
apiUrl: process.env.BRAINTRUST_API_URL!,
37-
parent: `project_name:${projectName}`,
36+
exporter: new OTLPTraceExporter(
37+
braintrustOtlpConfig({
38+
apiKey: process.env.BRAINTRUST_API_KEY!,
39+
apiUrl: process.env.BRAINTRUST_API_URL!,
40+
parent: `project_name:${projectName}`,
41+
}),
42+
),
3843
filterAISpans: true,
3944
});
4045

‎e2e/scenarios/nextjs-instrumentation/src/instrumentation.ts‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
1-
import { BraintrustExporter } from "@braintrust/otel";
1+
import { OTLPHttpJsonTraceExporter } from "@vercel/otel";
2+
import { BraintrustExporter, braintrustOtlpConfig } from "@braintrust/otel";
23
import { registerOTel } from "@vercel/otel";
34
import { initLogger } from "braintrust";
45
import { scopedName } from "./lib/runtime-check";
@@ -12,10 +13,14 @@ export async function register() {
1213
registerOTel({
1314
serviceName: "nextjs-instrumentation-e2e",
1415
traceExporter: new BraintrustExporter({
15-
apiKey: process.env.BRAINTRUST_API_KEY!,
16-
apiUrl: process.env.BRAINTRUST_API_URL!,
17-
parent: `project_name:${scopedName("e2e-nextjs-instrumentation")}`,
16+
exporter: new OTLPHttpJsonTraceExporter(
17+
braintrustOtlpConfig({
18+
apiKey: process.env.BRAINTRUST_API_KEY!,
19+
apiUrl: process.env.BRAINTRUST_API_URL!,
20+
parent: `project_name:${scopedName("e2e-nextjs-instrumentation")}`,
21+
}),
22+
),
1823
filterAISpans: false,
19-
}) as any,
24+
}),
2025
});
2126
}

‎e2e/scenarios/nextjs-instrumentation/src/lib/runtime-check.ts‎

Lines changed: 13 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
import { BraintrustExporter } from "@braintrust/otel";
2-
import { trace } from "@opentelemetry/api";
1+
import { OTLPHttpJsonTraceExporter } from "@vercel/otel";
2+
import { BraintrustExporter, braintrustOtlpConfig } from "@braintrust/otel";
33
import {
44
BasicTracerProvider,
55
SimpleSpanProcessor,
@@ -33,54 +33,20 @@ export function scopedName(base: string): string {
3333
return `${base}-${suffix}`;
3434
}
3535

36-
function createTracerProvider(processors: unknown[]) {
37-
if (
38-
typeof (new BasicTracerProvider() as { addSpanProcessor?: unknown })
39-
.addSpanProcessor === "function"
40-
) {
41-
const provider = new BasicTracerProvider() as {
42-
addSpanProcessor: (processor: unknown) => void;
43-
getTracer: (name: string) => {
44-
startActiveSpan: (
45-
name: string,
46-
callback: (span: {
47-
end: () => void;
48-
setAttribute: (key: string, value: string) => void;
49-
}) => Promise<void> | void,
50-
) => Promise<void>;
51-
};
52-
shutdown?: () => Promise<void>;
53-
};
54-
processors.forEach((processor) => provider.addSpanProcessor(processor));
55-
return provider;
56-
}
57-
58-
return new BasicTracerProvider({
59-
spanProcessors: processors as never,
60-
}) as {
61-
getTracer: (name: string) => {
62-
startActiveSpan: (
63-
name: string,
64-
callback: (span: {
65-
end: () => void;
66-
setAttribute: (key: string, value: string) => void;
67-
}) => Promise<void> | void,
68-
) => Promise<void>;
69-
};
70-
shutdown?: () => Promise<void>;
71-
};
72-
}
73-
7436
async function emitOtelSpan(runtime: Runtime, testRunId: string) {
7537
const exporter = new BraintrustExporter({
76-
apiKey: requiredEnv("BRAINTRUST_API_KEY"),
77-
apiUrl: requiredEnv("BRAINTRUST_API_URL"),
78-
parent: `project_name:${scopedName("e2e-nextjs-instrumentation")}`,
38+
exporter: new OTLPHttpJsonTraceExporter(
39+
braintrustOtlpConfig({
40+
apiKey: requiredEnv("BRAINTRUST_API_KEY"),
41+
apiUrl: requiredEnv("BRAINTRUST_API_URL"),
42+
parent: `project_name:${scopedName("e2e-nextjs-instrumentation")}`,
43+
}),
44+
),
7945
filterAISpans: false,
8046
});
8147

82-
const provider = createTracerProvider([new SimpleSpanProcessor(exporter)]);
83-
trace.setGlobalTracerProvider(provider as never);
48+
const processor = new SimpleSpanProcessor(exporter);
49+
const provider = new BasicTracerProvider({ spanProcessors: [processor] });
8450

8551
await provider
8652
.getTracer("nextjs-instrumentation-e2e")
@@ -91,9 +57,8 @@ async function emitOtelSpan(runtime: Runtime, testRunId: string) {
9157
span.end();
9258
});
9359

94-
await exporter.forceFlush();
95-
await provider.shutdown?.();
96-
await new Promise((resolve) => setTimeout(resolve, 250));
60+
await processor.forceFlush();
61+
await provider.shutdown();
9762
}
9863

9964
export async function runRuntimeCheck(runtime: Runtime) {

‎e2e/scenarios/otel-compat-mixed-tracing/scenario.ts‎

Lines changed: 19 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,13 @@
1+
import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
2+
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
13
import { context as otelContext, trace } from "@opentelemetry/api";
24
import { AsyncHooksContextManager } from "@opentelemetry/context-async-hooks";
3-
import { BraintrustSpanProcessor, setupOtelCompat } from "@braintrust/otel";
5+
import {
6+
BraintrustSpanProcessor,
7+
setupOtelCompat,
8+
BraintrustExporter,
9+
braintrustOtlpConfig,
10+
} from "@braintrust/otel";
411
import { initLogger, withCurrent } from "braintrust";
512
import {
613
createTracerProvider,
@@ -19,9 +26,17 @@ async function main() {
1926

2027
try {
2128
const processor = new BraintrustSpanProcessor({
22-
apiKey: process.env.BRAINTRUST_API_KEY!,
23-
apiUrl: process.env.BRAINTRUST_API_URL!,
24-
parent: `project_name:${scopedName("e2e-otel-compat-mixed-tracing", testRunId)}`,
29+
processor: new BatchSpanProcessor(
30+
new BraintrustExporter({
31+
exporter: new OTLPTraceExporter(
32+
braintrustOtlpConfig({
33+
apiKey: process.env.BRAINTRUST_API_KEY!,
34+
apiUrl: process.env.BRAINTRUST_API_URL!,
35+
parent: `project_name:${scopedName("e2e-otel-compat-mixed-tracing", testRunId)}`,
36+
}),
37+
),
38+
}),
39+
),
2540
});
2641
const provider = createTracerProvider([processor]);
2742
trace.setGlobalTracerProvider(provider);
Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
{
2+
"name": "@braintrust/e2e-otel-sdk-compat",
3+
"private": true,
4+
"braintrustScenario": {
5+
"bump": {
6+
"dependencies": {
7+
"otel-v1-latest-api": {
8+
"package": "@opentelemetry/api",
9+
"range": "~1.9.0",
10+
"targetDependency": "@opentelemetry/api",
11+
"targetManifest": "versions/otel-v1-latest/package.json"
12+
},
13+
"otel-v1-latest-sdk-trace-base": {
14+
"package": "@opentelemetry/sdk-trace-base",
15+
"range": "^1.30.1",
16+
"targetDependency": "@opentelemetry/sdk-trace-base",
17+
"targetManifest": "versions/otel-v1-latest/package.json"
18+
},
19+
"otel-v1-latest-context-async-hooks": {
20+
"package": "@opentelemetry/context-async-hooks",
21+
"range": "^1.30.1",
22+
"targetDependency": "@opentelemetry/context-async-hooks",
23+
"targetManifest": "versions/otel-v1-latest/package.json"
24+
},
25+
"otel-v1-latest-exporter-trace-otlp-http": {
26+
"package": "@opentelemetry/exporter-trace-otlp-http",
27+
"range": "^0.57.2",
28+
"targetDependency": "@opentelemetry/exporter-trace-otlp-http",
29+
"targetManifest": "versions/otel-v1-latest/package.json"
30+
},
31+
"otel-v2-latest-api": {
32+
"package": "@opentelemetry/api",
33+
"range": "~1.9.0",
34+
"targetDependency": "@opentelemetry/api",
35+
"targetManifest": "versions/otel-v2-latest/package.json"
36+
},
37+
"otel-v2-latest-sdk-trace-base": {
38+
"package": "@opentelemetry/sdk-trace-base",
39+
"range": "^2.12.0",
40+
"targetDependency": "@opentelemetry/sdk-trace-base",
41+
"targetManifest": "versions/otel-v2-latest/package.json"
42+
},
43+
"otel-v2-latest-context-async-hooks": {
44+
"package": "@opentelemetry/context-async-hooks",
45+
"range": "^2.12.0",
46+
"targetDependency": "@opentelemetry/context-async-hooks",
47+
"targetManifest": "versions/otel-v2-latest/package.json"
48+
},
49+
"otel-v2-latest-exporter-trace-otlp-http": {
50+
"package": "@opentelemetry/exporter-trace-otlp-http",
51+
"range": "^0.218.0",
52+
"targetDependency": "@opentelemetry/exporter-trace-otlp-http",
53+
"targetManifest": "versions/otel-v2-latest/package.json"
54+
},
55+
"otel-v3-latest-api": {
56+
"package": "@opentelemetry/api",
57+
"range": "~1.10.0",
58+
"targetDependency": "@opentelemetry/api",
59+
"targetManifest": "versions/otel-v3-latest/package.json"
60+
},
61+
"otel-v3-latest-sdk-trace": {
62+
"package": "@opentelemetry/sdk-trace",
63+
"range": "^3.1.0",
64+
"targetDependency": "@opentelemetry/sdk-trace",
65+
"targetManifest": "versions/otel-v3-latest/package.json"
66+
},
67+
"otel-v3-latest-context-async-hooks": {
68+
"package": "@opentelemetry/context-async-hooks",
69+
"range": "^3.1.0",
70+
"targetDependency": "@opentelemetry/context-async-hooks",
71+
"targetManifest": "versions/otel-v3-latest/package.json"
72+
},
73+
"otel-v3-latest-exporter-trace-otlp-http": {
74+
"package": "@opentelemetry/exporter-trace-otlp-http",
75+
"range": "^0.301.0",
76+
"targetDependency": "@opentelemetry/exporter-trace-otlp-http",
77+
"targetManifest": "versions/otel-v3-latest/package.json"
78+
}
79+
}
80+
}
81+
}
82+
}
Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
import { promises as fs } from "node:fs";
2+
import path from "node:path";
3+
import { expect, test } from "vite-plus/test";
4+
import {
5+
prepareScenarioDir,
6+
resolveScenarioDir,
7+
withScenarioHarness,
8+
} from "../../helpers/scenario-harness";
9+
import { extractOtelSpans } from "../../helpers/trace-summary";
10+
11+
const originalScenarioDir = resolveScenarioDir(import.meta.url);
12+
const variants = [
13+
"otel-v1",
14+
"otel-v1-latest",
15+
"otel-v2",
16+
"otel-v2-latest",
17+
"otel-v3",
18+
"otel-v3-latest",
19+
];
20+
const prepared = await Promise.all(
21+
variants.map(async (variant) => {
22+
// Separate install roots prevent different OTel API peer ranges from sharing a copy.
23+
const sourceDir = path.resolve(
24+
originalScenarioDir,
25+
`../../.bt-tmp/generated-scenarios/otel-sdk-compat-${variant}`,
26+
);
27+
await fs.rm(sourceDir, { recursive: true, force: true });
28+
await fs.cp(path.join(originalScenarioDir, "template"), sourceDir, {
29+
recursive: true,
30+
});
31+
await fs.cp(
32+
path.join(originalScenarioDir, "versions", variant),
33+
sourceDir,
34+
{ recursive: true },
35+
);
36+
return {
37+
variant,
38+
scenarioDir: await prepareScenarioDir({ scenarioDir: sourceDir }),
39+
};
40+
}),
41+
);
42+
43+
for (const { variant, scenarioDir } of prepared) {
44+
test(`otel-sdk-compat ${variant}: native context, filtering, customization and OTLP export`, async () => {
45+
await withScenarioHarness(
46+
async ({ runNodeScenarioDir, requestsAfter, testRunId }) => {
47+
await runNodeScenarioDir({
48+
scenarioDir,
49+
entry: "scenario.mjs",
50+
env: { OTEL_MAJOR: variant.slice(6, 7) },
51+
runContext: {
52+
variantKey: variant,
53+
originalScenarioDir,
54+
cassette: false,
55+
},
56+
});
57+
const requests = requestsAfter(
58+
0,
59+
(request) => request.path === "/otel/v1/traces",
60+
);
61+
expect(requests).toHaveLength(1);
62+
const spans = extractOtelSpans(requests[0].jsonBody);
63+
expect(spans.map((span) => span.name).sort()).toEqual([
64+
"gen_ai.child",
65+
"gen_ai.remote",
66+
]);
67+
for (const span of spans) {
68+
expect(span.attributes.testRunId).toBe(testRunId);
69+
expect(span.attributes.reviewed).toBe(true);
70+
expect(span.attributes.secret).toBeUndefined();
71+
expect(span.attributes["braintrust.parent"]).toBeDefined();
72+
expect(span.parentSpanId).toBeDefined();
73+
}
74+
expect(spans[0].traceId).toBe(spans[1].traceId);
75+
expect(spans[0].parentSpanId).toBe(spans[1].parentSpanId);
76+
expect(JSON.stringify(requests[0].jsonBody)).not.toContain(
77+
"private-payload",
78+
);
79+
},
80+
);
81+
});
82+
}

0 commit comments

Comments
 (0)