feat: add span customizers (SDK-316)

[Andrew Kent (realark)]

AI Generated Description

Summary

Implements SDK-316 using the span customizer specification and the JavaScript reference.

• Add SpanCustomizer.on_span_export, SpanExportData, set_span_customizers, and auto_instrument(span_customizers=...).
• Customize native instrumentation records after lazy resolution, before merging, masking, attachments, and serialization. Manual spans, datasets, feedback, and separate OTel exporters remain outside the scope.
• Preserve identity/routing/merge fields, ordered replacements, immutable registration snapshots, fail-open continuation, and transformed-record reuse on retries.
• Mark previously unmarked Pipecat and legacy LangChain instrumentation spans; document lifecycle and fail-open redaction risks.

Verification

• Dedicated customizer suite: 10 passed.
• Isolated core suite: 863 passed, 64 skipped, 12 xfailed.
• test_types: pyright/mypy clean, 35 runtime tests passed.
• Pipecat customizer regression passed on 1.3.0 and latest (1.10.0).
• Standalone SDK smoke: incremental input/output redaction, stable span identity, manual-span exclusion.
• Changed-file pre-commit checks passed.

The core suite required clearing local Braintrust endpoint environment overrides to match recorded cassettes. It exits successfully but prints an atexit closed-output-stream warning. No cassettes were changed.

Contract note

Like JavaScript, failures are fail open. Throwing is not a safe way to block export; the API docs state this explicitly.

[Andrew Kent (realark)]

Fixed the CI regression in 5111069. The Discovery Engine subprocess test treated every auto_instrument parameter as a boolean flag, passing span_customizers=False. It now disables only parameters whose defaults are boolean, leaving the new list-valued option at its default.

Verification:

• Full test_google_discoveryengine(latest) session: 30 tests passed, including both subprocess import orders.
• Changed-file pre-commit checks passed.
• Full GitHub CI rerun passed, including the Python 3.10–3.14 Linux/Windows matrix: https://github.com/braintrustdata/braintrust-sdk-python/actions/runs/35578157031 .