Instrumentation Rules

Read first based on the task:

• js/src/instrumentation/README.md for wrapping and tracing architecture
• Closest file in js/src/instrumentation/core/ when changing shared invocation semantics
• Closest file in js/src/instrumentation/plugins/ when changing provider-specific extraction or span mapping
• Closest file in js/src/wrappers/ when manual wrappers and auto-instrumentation need to stay aligned
• Closest test in js/tests/auto-instrumentations/ when changing hook, loader, bundler, or transform behavior
• Closest e2e scenario in e2e/scenarios/*instrumentation* or e2e/scenarios/*node-hook* when the user-visible trace contract changes

Map the change before editing:

• js/src/instrumentation/core/ - invocation definitions, independent tracing helpers, stream patching, shared types
• js/src/instrumentation/plugins/ - explicit interceptor registration and provider-specific tracing functions
• js/src/wrappers/ - manual instrumentation entrypoints that should mirror the same logical contracts
• js/src/auto-instrumentations/ - loader and bundler instrumentation config
• js/tests/auto-instrumentations/ - functional coverage for transformed code
• e2e/scenarios/ - subprocess-level contract coverage against the mock Braintrust server
• Non-invasive: instrumentation must not change user-visible behavior. Errors must still propagate, streams and promise subclasses must keep their original semantics, and any patch must be behavior-preserving and idempotent.
• Inputs are untrusted: treat args, results, events, headers, and metadata as hostile. Prototype pollution is a concrete risk here. Avoid unsafe property access patterns, prototype-sensitive operations, and unnecessary mutation of third-party objects.
• Support both auto-instrumentation and manual instrumentation. Auto-instrumentation does not cover every environment, loader, or framework.
• For orchestrion auto-instrumentation, prefer targeting public API functions. Instrumenting internal helpers is more likely to break across library versions.
• Braintrust's vendored Orchestrion implementation is purely internal to the SDK. Downstream packages must not depend on its APIs, config schema, generated helpers, or compatibility with upstream Orchestrion. Do not expose these internals through SDK entrypoints or public configuration options. Update the transformer and its SDK callers together; remove unused upstream features and compatibility scaffolding. Preserve instrumented application behavior, coordination between SDK copies, and upstream license notices.
• Keep wrapping and tracing separate, including internal APIs. Define typed invocation hooks with defineInterceptor; intercept and invoke only compose and execute wrappers. Definitions describe call arguments, return values, and opaque additional data, without span provenance or tracing methods. The wrapping runtime must work without SDK initialization and have no dependency on spans, logging, or tracing lifecycle events. Put span creation, context propagation, and finalization in separate tracing functions. Plugins explicitly register those functions through intercept; shared tracing helpers accept callables and tracing configuration, never hooks or registration responsibilities. Do not add combined helpers such as traceInvocation or interceptAndTrace, or retain a tracing-event compatibility path. Manual wrappers and generated wrappers use the same hook through invoke and do not directly emit observability data.
• Reuse shared repo utilities before introducing local helpers. Check js/util/index.ts, neighboring instrumentation files, and existing plugins/wrappers for utilities like isObject, merge helpers, and sanitizers before adding ad hoc replacements.
• If a public instrumentation surface changes, check whether the export surface also needs updates in js/src/instrumentation/index.ts or js/src/exports.ts.
• Preserve async context propagation. Changes around invocation hooks, stream patching, or loader hooks must keep the current span context across awaits and stream consumption.
• Maintain isomorphic behavior. Node and browser/bundled paths must use compatible channel implementations and avoid channel-registry mismatches.
• Setup, teardown, and patching must be idempotent. Enabling twice, disabling twice, or applying a patch twice should remain safe.
• Promise/stream behavior must be preserved. Patches need to keep subclass/helper semantics intact.
• Treat Braintrust logging and span-finalization methods, including span.log() and span.end(), as non-throwing. Do not wrap these methods in defensive try/catch blocks or add fallback logic for hypothetical logging exceptions.
• Use the SDK debugLogger for SDK instrumentation diagnostics. Do not call console.* directly from instrumentation code; direct console use should stay inside the debug logger implementation or another explicitly justified exception.
• Pass Error objects directly as span.log({ error }) values. The SDK serializes errors correctly, so do not add local helpers that manually turn errors into message/stack strings unless an external API requires a non-Error representation.
• Log only the useful surface. Prefer narrow, stable payloads over dumping full request/response objects; exclude redundant or overly large data when possible.
• Automatic capture of inline multimodal bytes as Braintrust attachments must be opt-in. Guard attachment creation and binary observation with BRAINTRUST_CAPTURE_ATTACHMENTS, and enable them only when its value is 1 or true. Audio/video recordings may contain personal data and are separately controlled with their own explicit flags (BRAINTRUST_CAPTURE_USER_AUDIO_ATTACHMENTS, BRAINTRUST_CAPTURE_AGENT_AUDIO_ATTACHMENTS): enabling the shared flag for other media never records audio/video without these being enabled. Preserve useful text, metadata, metrics, and remote references when attachment capture is disabled, and omit inline bytes from logged payloads.
• Segmentable streaming media must use the shared configureInstrumentation({ streamingAttachmentBufferBytes }) setting instead of provider-specific chunk-size or time-based controls. It defaults to 4 MiB per logical media stream and counts binary attachment payload bytes after decoding and format conversion, including any required padding or silence. Flush near the threshold at valid media boundaries and flush remaining valid content when the recording ends. Preserve ordering, format metadata, and timestamps needed to interpret the attachments. Keep whole-file responses intact, even if they exceed the threshold; never arbitrarily split encoded images, audio, or video. This is a flush threshold, not a total memory limit or attachment-capture opt-in. Preserve application stream behavior and existing capture consent; keep any capture safety ceiling internal and distinct from the threshold.
• Do not modify package READMEs during instrumentation work unless the user specifically requests it or the change corrects outdated information.
• We want to limit our instrumentation to operations that are relevant for AI generations and operations (LLMs, embeddings, media generation, ...). Things like creating entities on platforms (CRUD for Workflows of Agent entities) is irrelevant to us.
• When building instrumentation, we should always have a vendored type/interface for what we are wrapping. The type or interface should not be larger than what is relevant to the instrumentation. The type or interface should be used for typing invocation hooks and also should be used to assert the type on whatever is passed into wrappers as soon as the wrapper has verified that the passed in value is plausibly what should be wrapped.

Process

Before implementing or changing instrumentation it is advisable to add or adjust the e2e tests for the desired change, make it fail, then implement the new instrumentation until the test passes.

When validating instrumentation with real provider APIs or recording e2e cassettes, default to cheap models that support the behavior under test, unless the user explicitly requests otherwise. Keep prompts, output limits, and media duration small while preserving meaningful coverage.