feat: add span customizers (SDK-316)

[Andrew Kent (realark)]

AI Generated Description

Summary

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

• Add extensible config.SpanCustomizer{OnSpanExport: ...} and braintrust.WithSpanCustomizers(...), plus direct trace configuration support.
• Run ordered hooks over isolated completed sdktrace.ReadOnlySpan export snapshots for immediate-key, lazy-auth, and injected exporters.
• Permit field/attribute replacement, removal, and routing changes while preserving trace/span/parent identity.
• Fail the entire batch before transport on callback errors/panics, nil/typed-nil results, or changed IDs; preserve the caller’s batch and spans seen by other processors.
• Snapshot registrations, preserve the empty-hook fast path, and document retries/concurrency and attachment/console boundaries.
• Add a compiling README example and runnable examples/internal/span-customizers example.

Verification

• Race-enabled customizer tests in root and trace packages passed.
• Legacy GODEBUG=panicnil=1 failure handling passed.
• Actual gzip/protobuf OTLP transport tests passed for immediate and lazy authentication, including zero requests on failed customization.
• Standalone public client smoke with a real local HTTP receiver passed redaction and identity preservation.
• README snippets compile.
• Root and btx golangci-lint: zero issues; formatting checks passed.
• Module verification and nested-module/release-coverage checks passed.
• Full make test build passed, including root, all releasable nested modules, btx, and Orchestrion injection tests (with the pinned Orchestrion v1.12.1 binary).

The new wire-level tests directly import existing OTLP/protobuf dependencies; go mod tidy promotes those two dependencies from indirect to direct without version changes.

Contract boundaries

Hooks run after existing attachment processing; already uploaded attachments cannot be retracted. Separately enabled trace-console logging is not customized. Transport retries reuse transformed spans; an explicit exporter resubmission reruns hooks. Callback closure state must be concurrency-safe.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-24T14:38:13.572308Z	d572871	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "Codex (@codex) review" or "Codex (@codex) security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d572871187

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "Codex (@codex) review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "Codex (@codex) address that feedback".