feat: support Python OpenTelemetry span customizers

[Andrew Kent (realark)]

Summary

Implements SDK-473. Stacked on and dependent on SDK-472 (ark/SDK-472-customizer-error-handling); merge the error-handling base first.

• Reuse set_span_customizers / synchronous on_span_export for direct OtelExporter, BraintrustSpanProcessor, and OTel compatibility mode, with no second configuration API and no double invocation.
• OTel hooks receive detached plain dictionaries exposing attributes, name, events, links, status, resource/scope metadata, context/parent, kind, and nanosecond timestamps. Native hooks retain their existing incremental-record shape. The README documents every field and includes a redaction example.
• Customize after filtering/origin enrichment and before OTLP serialization. Protect original IDs, parent, timing, and Braintrust routing. Replacement dictionaries do not implicitly merge removed content; other exporters never see mutations.
• Share SDK-472 synchronous return validation, BaseException handling (except KeyboardInterrupt/SystemExit), chain stopping, and once-only safe diagnostics across native and OTel pipelines. Failures preserve identity/timing/routing only plus the exact braintrust.context_json customizer_error marker; no resource/scope/context/payload leakage. Validate serialization shapes before the upstream encoder can discard attributes or reject the batch.
• Retain optional OTel imports and support both legacy 1.16 and modern encoders. No-customizer export behavior stays unchanged.

Verification

All executed on Python 3.12.12:

• mise exec -- nox -s "test_otel(1.16.0)" "test_otel(1.44.0)" "test_otel(latest)" test_otel_not_installed test_core -- -q: all five sessions passed. OTel: 64 tests per version (latest = 1.45.0). No-OTel: 8 passed / 56 skipped. Core: 987 passed / 95 skipped / 12 xfailed / 21 subtests passed.
• .nox/test_otel-latest/bin/python -m pytest -p no:braintrust src/braintrust/otel src/braintrust/test_span_customizer.py -q: 59 passed.
• Changed-file pre-commit hooks passed (Ruff formatting/checks, whitespace, codespell).
• Permanent regression tests use real OTLP protobuf serialization and HTTP export to a local collector: successful mutations/replacements, mixed healthy/stripped batches, repeated exports, shared native/OTel diagnostics, invalid wire shapes, preserved ID/time/routing, deep no-mutation isolation, filter ordering, logger/experiment compatibility roots and children.

Limitations

Local version matrix uses Python 3.12; CI covers the remaining supported Python versions. OTel 1.16 emits two upstream protobuf deprecation warnings. Scope attributes require a supporting OTel version; the old SDK exposes none and does not serialize them. Explicit repeated export calls rerun hooks; internal transport retries reuse serialized data.

[Andrew Kent (realark)]

Amended the single SDK-473 commit to 7b2a438. The protobuf HTTP test receiver resolves its generated request class through the public protobuf symbol database, avoiding unsupported static imports of runtime-generated symbols. No lint suppressions added. Full pylint and all three OTel version suites passed locally (64 tests each, including real protobuf/HTTP exports). All hosted CI checks now pass across Python 3.10–3.14 on Linux/Windows, including static checks, nox suites, smoke tests, and checks-passed: https://github.com/braintrustdata/braintrust-sdk-python/actions/runs/38298845721