feat: otel compatible distributed tracing

[Andrew Kent (realark)]

• 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

from braintrust import current_span, init_logger, start_span, traced

logger = init_logger(project="my-project")

# Client: Export the span
@traced
def process_request(request):
    return requests.post(
        "/api/process",
        json=request,
        headers={"X-Trace-ID": current_span().export()},
    )

# Server: Resume the trace
def handle_request(req):
    trace_id = req.headers.get("X-Trace-ID")

    with start_span(parent=trace_id) as span:
        result = process_data(req.body)
        span.log(input=req.body, output=result)
        return result

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:

from braintrust import current_span, init_logger, start_span, traced

logger = init_logger(project="my-project")

# Client: Export the span
@traced
def process_request(request):
    return requests.post(
        "/api/process",
        json=request,
        headers=current_span().inject({}), # <--- new inject api
    )

# Server: Resume the trace
def handle_request(req):
    with start_span(parent=extract_trace_context(req.headers) as span: # <--- new extract api
        result = process_data(req.body)
        span.log(input=req.body, output=result)
        return result

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. 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 (propagated_state)

Examples

• https://www.braintrust.dev/app/Braintrust%20SDKs/p/distributed-tracing-test/logs?range=%221h%22&r=021fb6471e30c686a667ffdfbba15ee6&s=67123a9c35899f93
• https://www.braintrust.dev/app/Braintrust%20SDKs/p/distributed-tracing-test/logs?range=%221h%22&r=5be69e7ec10f257b8671417162bcf075&s=050480159793924b

[Abhijeet Prasad (AbhiPrasad)]

I'm happy with this public API. Mind writing a spec doc for this so we can also be clear about the behavior difference between py/js and the otel powered sdks?

[Andrew Kent (realark)]

Abhijeet Prasad (@AbhiPrasad) sweet! I've been working on this spec in tandem with this PR: braintrustdata/braintrust-spec#27

I just updated it to add test cases for encoding and size limits