Link Braintrust and OpenTelemetry spans

To combine OpenTelemetry spans with Braintrust spans, share context within a process or propagate context across services, depending on where the spans are created. You can use both approaches in the same application. Configure trace export before following these examples. Compatibility mode stores the active span in OpenTelemetry’s context, so Braintrust and OpenTelemetry instrumentation contribute to the same trace within a process. For example, use it to nest OpenTelemetry spans under a Braintrust evaluation span.

Call setupOtelCompat() before creating any loggers or spans, and use AsyncLocalStorageContextManager to nest spans under their parent evaluation spans:

Compatibility mode requires the @braintrust/otel package, v0.1.0 or later.

TypeScript

import { BasicTracerProvider } from "@opentelemetry/sdk-trace-base";
import { trace, context } from "@opentelemetry/api";
import { AsyncLocalStorageContextManager } from "@opentelemetry/context-async-hooks";
import { setupOtelCompat, BraintrustSpanProcessor } from "@braintrust/otel";

// Setup context manager to group span
// Set up context manager to group spans
contextManager.enable();
context.setGlobalContextManager(contextManager);

const braintrustProcessor = new BraintrustSpanProcessor({
  parent: "project_name:my-braintrust-project",
  filterAISpans: true,
});

const provider = new BasicTracerProvider({
  spanProcessors: [braintrustProcessor]
});
trace.setGlobalTracerProvider(provider);

// Call this first, before any logger or span creation
setupOtelCompat();

async function task(input: string): Promise<string> {
  const tracer = trace.getTracer("my-service");

  return await tracer.startActiveSpan("otel.task", async (span) => {
    span.setAttribute("input", input);
    const result = `Processed: ${input}`;
    span.setAttribute("output", result);
    span.end();
    return result;
  });
}

await Eval("OTEL Integration Example", {
  data: [
    { input: "test1", expected: "Processed: test1" },
    { input: "test2", expected: "Processed: test2" },
  ],
  task,
});

Propagate context across services

Pass the parent span’s context to the receiving service so its spans join the same trace. Choose the example that matches which SDK creates the parent span.

These examples require @braintrust/otel v0.1.0 or later and use fetch to pass context in HTTP headers.

When linking Python and TypeScript services, align their ID formats.

Braintrust parent to OpenTelemetry child

Export the Braintrust span context and use it to create an OpenTelemetry context.

import { initLogger } from "braintrust";
import { contextFromSpanExport } from "@braintrust/otel";
import * as api from "@opentelemetry/api";

// Service A: Create Braintrust span and export context
const logger = initLogger({ projectName: "my-project" });
await logger.traced(async (span) => {
  const exported = await span.export();
  // Send to Service B via HTTP
  await fetch("https://service-b/api", {
    headers: { "x-braintrust-context": exported },
  });
});

// Service B: Receive request and create OTel span as child
const exported = req.headers.get("x-braintrust-context");
const ctx = contextFromSpanExport(exported);
await api.context.with(ctx, async () => {
  const tracer = api.trace.getTracer("service-b");
  await tracer.startActiveSpan("service_b", async (span) => {
    // This span is now a child of the Braintrust span
    span.end();
  });
});

OpenTelemetry parent to Braintrust child

Propagate the OpenTelemetry context using W3C Trace Context headers.

import { addSpanParentToBaggage, parentFromHeaders } from "@braintrust/otel";
import * as api from "@opentelemetry/api";

// Service A: Create OTel span and export headers
const tracer = api.trace.getTracer("service-a");
await tracer.startActiveSpan("service_a", async (span) => {
  // Add Braintrust parent to baggage for propagation
  const ctx = addSpanParentToBaggage(span);

  // Export W3C trace context headers and send to Service B
  const headers: Record<string, string> = {};
  api.propagation.inject(ctx, headers);
  await fetch("https://service-b/api", { headers });

  span.end();
});

// Service B: Receive request and create Braintrust span as child
const parent = parentFromHeaders(req.headers);
await logger.traced(
  async (span) => {
    // This span is now a child of the OTel span
  },
  { name: "service_b", parent },
);

The examples use HTTP, but you can also transmit trace context through message queue metadata, gRPC metadata, or another inter-service transport that supports context propagation.

ID format compatibility

Braintrust can represent span and trace IDs as OTel-compatible hexadecimal values and serialize them in a shared export format, so exported spans interoperate with OpenTelemetry.

For distributed tracing between Python and TypeScript services, make sure both services use the same format. Either set BRAINTRUST_LEGACY_IDS=true on the Python service, or enable compatibility mode on the TypeScript service.

The TypeScript SDK reads and exports only the legacy ID and export format by default. Enable compatibility mode with setupOtelCompat() to read either format (auto-detecting) and export the OTel-compatible format, including when propagating spans through x-bt-parent or other distributed-tracing channels.

The TypeScript examples use the @braintrust/otel package to link OpenTelemetry and Braintrust spans. If you only need to propagate Braintrust trace context between TypeScript services over HTTP, the core braintrust package has native W3C helpers, injectTraceContext and extractTraceContextFromHeaders, that emit and read standard traceparent headers without the extra package.

AI providers

SDKs

Developer tools

Runtime environments

Link Braintrust and OpenTelemetry spans

Propagate context across services

Braintrust parent to OpenTelemetry child

OpenTelemetry parent to Braintrust child

Resources

​Share context within a process

​Propagate context across services

​Braintrust parent to OpenTelemetry child

​OpenTelemetry parent to Braintrust child

​Resources

Share context within a process

Propagate context across services

Braintrust parent to OpenTelemetry child

OpenTelemetry parent to Braintrust child

Resources