Add auto-instrumentation via BraintrustTracingLayer

[Stephen Belanger (Qard)]

Summary

This PR implements true auto-instrumentation for the Braintrust Rust SDK using the tracing crate and OpenTelemetry GenAI semantic conventions.

With this change, users can install a tracing subscriber once and have all AI SDK calls automatically logged to Braintrust - zero manual code needed.

What's New

BraintrustTracingLayer

A new tracing_subscriber::Layer that:

• Captures OpenTelemetry GenAI semantic convention events
• Automatically converts them to Braintrust SpanLog entries
• Sends logs to Braintrust in the background
• Supports streaming responses
• Works with any instrumented AI SDK

Usage

use braintrust_sdk_rust::{BraintrustClient, BraintrustTracingLayer};
use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let braintrust = BraintrustClient::builder()
        .api_url("https://api.braintrust.dev")
        .build().await?;

    let span = braintrust.span_builder().await?
        .project_name("my-project")
        .build();

    // Install once - this is all you need!
    tracing_subscriber::registry()
        .with(BraintrustTracingLayer::new(span.clone()))
        .init();

    // All instrumented AI SDK calls are now automatically logged!
    Ok(())
}

Implementation Details

Core Components

1. src/tracing_layer/mod.rs: Main layer implementation

   • Implements Layer<S> trait
   • Lifecycle hooks: on_new_span, on_record, on_event, on_close
   • Filters events by gen_ai.* target prefix

2. src/tracing_layer/data.rs: GenAISpanData storage struct

   • Accumulates request/response data
   • Stores prompts, completions, usage metrics
   • Supports streaming chunks

3. src/tracing_layer/visitor.rs: FieldVisitor for field extraction

   • Implements tracing::field::Visit
   • Extracts typed fields into serde_json::Value

Supported SDKs

This works with any SDK that emits OpenTelemetry GenAI events:

• async-openai (with instrumentation feature)
• rust-genai / genai (with instrumentation feature) - covers 11+ providers

Testing

• ✅ 5 comprehensive integration tests
• ✅ Tests layer installation, event capture, filtering, streaming
• ✅ All existing tests still pass
• ✅ Clippy and fmt checks pass
• ✅ Working integration example included

Dependencies

Added tracing-subscriber with registry feature:

tracing-subscriber = { version = "0.3", features = ["registry"] }

Documentation

• Updated README with auto-instrumentation section
• Added examples/auto_instrumentation.rs
• Updated design doc at docs/auto-instrumentation.md

Benefits

• Zero manual logging code - install layer once, automatic logging forever
• Consistent format across all AI providers
• Standard conventions - follows OpenTelemetry GenAI specs
• Low overhead - async logging doesn't block application
• Streaming support - automatically captures streaming responses

Breaking Changes

None. This is a purely additive feature.

Related Work

This PR is part of a broader effort to bring auto-instrumentation to Rust AI applications. Future work includes:

• Contributing instrumentation upstream to async-openai and rust-genai
• Instrumenting additional SDKs (rig-core, candle-core, etc.)
• Adding AWS Bedrock interceptor support

Checklist

• Tests added and passing
• Documentation updated
• Example code provided
• Clippy checks passing
• Formatting checks passing
• No breaking changes

---

🤖 Co-Authored-By: Claude Sonnet 4.5 noreply@anthropic.com

[Abhijeet Prasad (AbhiPrasad)]

I guess the tracing layer runs on every tracing event, like every call to tracing::info!. Can we avoid that given we only care about genai spans? It would help with overhead a lot in high throughput apps.

[Abhijeet Prasad (AbhiPrasad)]

I think we still need to take care of the fact that the tracing layer runs on every tracing event.

[Stephen Belanger (Qard)]

Ankur Goyal (@ankrgyl) Manu Goyal (@manugoyal) Any idea what AI SDKs should be prioritized for Rust auto-instrumentation? The idea here is to build on the excellent tracing framework and open PRs to add tracing crate support to any AI SDKs which do not already have proper support for emitting spans using OpenTelemetry Gen-AI Semantic Conventions.

[Abhijeet Prasad (AbhiPrasad)]

I think we can clean this up a bit, we probably only need to document Approach 1 and 2. Might also make sense to move this into a docs folder.

[Abhijeet Prasad (AbhiPrasad)]

should we bound the number of tasks we spawn?

[Abhijeet Prasad (AbhiPrasad)]

This is quite a lot of boilerplate. Can we avoid doing this if we are just going to pass it into log_builder.metadata anyway? We can just make the builder take these different attributes, not caring if they are Option<>

[Abhijeet Prasad (AbhiPrasad)]

Doesn't block, but maybe makes sense to use a macro for these calls.