feat: Add otel compatible distributed tracing

[Andrew Kent (realark)]

implements: https://github.com/braintrustdata/braintrust-spec/blob/main/docs/features/distributed-tracing.md

• use otel-friendly IDs by default in the SDK
• add inject/extract methods for distributed tracing instead of parent slug methods
  • implements: https://www.w3.org/TR/trace-context/

OLD WAY: https://www.braintrust.dev/docs/instrument/advanced-tracing#trace-distributed-systems

import { currentSpan, initLogger, startSpan, traced } from "braintrust";

const logger = initLogger({ projectName: "my-project" });

// Client: Export the span
const processRequest = (request: Request) =>
  traced(
    async (span) =>
      fetch("/api/process", {
        method: "POST",
        body: JSON.stringify(request),
        headers: { "X-Trace-ID": await currentSpan().export() },
      }),
  );

// Server: Resume the trace
async function handleRequest(req: Request) {
  const traceId = req.headers.get("X-Trace-ID") ?? undefined;

  return traced(
    async (span) => {
      const result = await processData(req.body);
      span.log({ input: req.body, output: result });
      return result;
    },
    { parent: traceId },
  );
}

NOTE: the "old way" is still supported and backwards-compatible. Native SDKs can continue to link to each other in the manner, even if one is upgraded and the other is not. However if users with to link to otel sdks, they will have to change their code to use the new apis.

NEW WAY:

import {
  currentSpan,
  extractTraceContext,
  initLogger,
  startSpan,
  traced,
} from "braintrust";

const logger = initLogger({ projectName: "my-project" });

// Client: Export the span
const processRequest = (request: Request) =>
  traced(
    async (span) =>
      fetch("/api/process", {
        method: "POST",
        body: JSON.stringify(request),
        headers: currentSpan().inject({}), // <--- new inject api
      }),
  );

// Server: Resume the trace
async function handleRequest(req: Request) {
  return traced(
    async (span) => {
      const result = await processData(req.body);
      span.log({ input: req.body, output: result });
      return result;
    },
    { parent: extractTraceContext(req.headers) }, // <--- new extract api
  );
}

Other notes

• confusing naming: this has the unfortunate effect of the root_span_id field essentially becoming the trace id rather than the id of the root span (i.e. root_span_id != rootSpan.id). This sucks, but it's already the case for otel sdks and py otel compat mode. So at least we're consistent.
• legacy id flag: the sdk currently maintains two paths for id generation. it defaults to UUIDs and does hex IDs when we're in in otel compat mode. This changes the default to use hex IDs and has a flag to revert to the old behavior (BRAINTRUST_LEGACY_IDS). We could just rip out the old uuid logic entirely, but this approach seems like the least risky
• to support passing through tracestate and flags, an additional field was added to SpanImpl (propagatedState)

examples

• https://www.braintrust.dev/app/Braintrust%20SDKs/p/distributed-tracing-test/trace?object_type=project_logs&object_id=d010dc4b-b4f2-421e-a165-232a8e6f062f&r=c7681ae1d7754e3fd27a06fb53c6fc29&s=decc9abf92ddeae5
• https://www.braintrust.dev/app/Braintrust%20SDKs/p/distributed-tracing-test/logs?r=6449255f3c9a8f7121cf9ce04c6d73f6&s=4180f4889809461e

[Abhijeet Prasad (AbhiPrasad)]

we should also try to parse https://developer.mozilla.org/en-US/docs/Web/API/Headers here (we can duck type it).

[Andrew Kent (realark)]

Luca Forstner (@lforst) took care of this (thanks Luca!)

[Abhijeet Prasad (AbhiPrasad)]

looks like btMember is always added. Shouldn't we check to make sure it is not too large?

[Andrew Kent (realark)]

Luca Forstner (@lforst) took care of this (thanks Luca!)