API Reference

Decorate a sync or async function and record one trace event for each call.

Generator and async-generator functions are also supported and are traced for their full iteration lifetime rather than only their creation: the wrapper stays lazy (no body runs and nothing is written until the first iteration), the trace stays open across every next/send/throw (or asend/athrow) so child spans and generations created in the body attach to it, and it is finalized when the generator is exhausted (recorded as a successful trace), raises (recorded as a redacted error and re-raised), or is closed/cancelled early (recorded as a successful trace whose metadata.generator.outcome is "closed"). Yielded values are never buffered; with output capture enabled only a bounded yielded-item count is recorded under metadata.generator.items.

metadata is an optional static mapping recorded on the produced trace ROOT event, redacted with the same rules as captured input/output. It is the decorator-side counterpart to trace(metadata=...) for tagging an entry point (route, tenant, feature flag) without rewriting it as a manual with trace(...) block. It is attached only when the decorated call opens a new trace root; a nested @observe() call records a span and never carries this trace-level metadata. For observed generators it composes with the recorded metadata.generator.* outcome (the generator keys win on conflict).

Create a trace root with a context manager.

Create a nested span inside the current trace.

Create a generation event for an LLM call inside the current trace.

Create a tool call event inside the current trace.

Create a retrieval tool call using Bir's documented RAG event shape.

Attach a score event to the current trace.

Optional metadata (for example an evaluator's reasoning or threshold) is redacted with the same rules as captured input/output and stored on the score event so it can be inspected in the dashboard later.

Describe the prompt version used by a generation.

Configure local SDK behavior.

service_name and environment are recorded on trace root events under metadata.service so traces can be filtered by deployment later.

source tags every trace root with metadata.source so traces can be filtered by where they originated. It is the SDK-side counterpart to the source the Bir server/dashboard already filter on (the product's Playground records "playground"); the server matches it by exact, trimmed value, so pick a stable label such as "checkout-api". Like the trace metadata argument, an explicit source in a trace(metadata=...) block still wins over this configured default. Defaults to None (no source recorded).

enabled is the master on/off switch for all recording. The default True keeps every primitive recording as configured. Set it to False for an explicit, intent-revealing kill switch (a feature flag, an incident toggle, a test): @observe, trace/span/generation/ tool_call/retrieval, and score all still run the wrapped code and still propagate exceptions, but nothing is ever written, making Bir a true no-op without touching call sites. It is enforced through the same path as sampling, so a trace already in flight when recording is disabled stops writing immediately, and configure(enabled=True) restores full recording for traces started afterward. get_current_trace_id() / get_current_span_id() still return the live in-process ids inside a trace while disabled (matching a sampled-out trace), so log correlation keeps working even though nothing is persisted.

sample_rate is the probability (0.0 to 1.0) that a trace is recorded. It is decided once per trace root; when a trace is sampled out the function still runs and still raises, but the trace and every event under it write nothing. The default 1.0 records every trace. sample_rate only applies while enabled is True; enabled=False turns everything off regardless of the rate.

sample_rules is an opt-in mapping of exact trace root name to a sampling rate for that root. A matching rule overrides the global sample_rate; an unmatched root uses the global rate. Rules are validated once here and stored immutably, and the decision is still made once per trace root and inherited by every descendant event. Passing sample_rules replaces the prior rule table (an empty mapping clears it); omitting it leaves the current rules unchanged.

max_bytes enables opt-in size-based rotation of the local trace file. It defaults to None (unlimited), which keeps the historical single-file behavior. When set to a non-negative integer, the active file is rotated before any write that would push it past the cap: traces.jsonl becomes traces.jsonl.1, the previous .1 becomes .2, and so on, keeping at most backup_count rotated files and dropping the oldest. Rotation always happens on whole-line boundaries, so every file stays valid JSONL and a JSON object is never split across files (a single line larger than max_bytes is still written whole). backup_count defaults to 3; 0 keeps no rotated files and simply drops the active file when it fills.

Note that a single logical trace may be split across rotated files when rotation happens mid-trace, so reading with include_rotated=True can surface incomplete traces near a rotation boundary.

additional_secret_keys and additional_redaction_patterns add to the built-in redaction rules; they can only ever widen what is redacted and can never disable, replace, reorder, or change the [redacted] marker of the built-in rules. additional_secret_keys is an iterable of extra mapping-key names: a captured mapping key is redacted when it matches one of them exactly and case-insensitively, treating - and _ as equivalent (this is whole-name exact matching, unlike the built-in substring rules). additional_redaction_patterns is an iterable of regex strings and/or already-compiled re.Pattern objects; every match of each pattern in any captured string, repr fallback, prompt text, eval metadata, or error message is replaced with [redacted], running after all built-in text patterns. Both are validated and compiled once here, so an empty key, empty pattern, invalid regex, non-string entry, bytes pattern, or an over-large list raises ValueError/TypeError immediately. Passing either argument replaces the previously configured additional rules of that kind (passing an empty iterable clears them); omitting it leaves the current additional rules unchanged. The built-in rules always remain in force either way.

model_prices is an opt-in, local-only price table that auto-fills a generation's cost from its token usage. It is a mapping of model name to a rates mapping holding a non-negative, finite input and/or output per-token rate plus an optional currency (default "USD"). Bir bundles no prices, so the rates — and keeping them current — are yours to supply. When a generation has usage and a model matching a configured entry but no explicitly set cost, its input_cost/output_cost/total_cost are derived from the matching rates at the configured currency exactly as a manual set_cost(...) would record them (input rate times input tokens, output rate times output tokens, total summed when both sides are priced). An explicit set_cost(...) always wins and is never overwritten, and a generation whose usage lacks the needed token split is left without a derived cost. The table is validated once here, so a non-mapping table, a non-string or empty model name, a non-mapping or empty rate entry, an unknown rate key, a boolean, negative, or non-finite rate, an invalid currency, or an over-large table raises ValueError/TypeError immediately. Passing model_prices replaces the previously configured table (an empty mapping clears it); omitting it leaves the current table unchanged. With no table configured, generation cost behavior is unchanged.

max_value_length and max_collection_items are opt-in capture-size limits that bound a single captured value so one huge payload (a base64 image, a megabyte of model output) cannot bloat the local store. Both default to None (unlimited), which keeps captured output byte-for-byte unchanged. When max_value_length is a non-negative integer, a captured string longer than it is truncated to that many characters with a visible …[truncated] marker appended; truncation always runs after redaction, so a secret is replaced before any cut and can never be split in a way that defeats the redactor. When max_collection_items is a non-negative integer, a captured list, tuple, set, or mapping larger than it keeps only the first that-many items and records a single …[truncated] marker for the remainder, leaving the output valid JSON. Both apply uniformly to every capture path (inputs, outputs, metadata, repr fallbacks, and dataset and experiment capture) and compose with the existing capture-depth cap. They only bound captured values, never event names, models, ids, or the schema. A non-integer, boolean, or negative limit raises TypeError/ValueError here.

Any field left unset falls back to the value supplied by the matching environment variable (BIR_TRACE_PATH, BIR_CAPTURE_INPUTS, BIR_CAPTURE_OUTPUTS, BIR_DISABLED, BIR_SAMPLE_RATE, BIR_SERVICE_NAME, BIR_ENVIRONMENT, BIR_SOURCE, BIR_MAX_VALUE_LENGTH, BIR_MAX_COLLECTION_ITEMS), which is read once at import time, and otherwise to the hardcoded default. A truthy BIR_DISABLED sets enabled=False (it is the inverse of the enabled field, so the common "turn it off in production" case is a single boolean variable). Explicit arguments to this function take precedence over the environment, so configure(enabled=True) re-enables recording even when BIR_DISABLED is set.

Load local JSONL trace events.

By default only the active trace file is read. Pass include_rotated=True to also read size-rotated siblings (traces.jsonl.1 ..) created by configure(max_bytes=...). Rotated files are read oldest-first so the returned events stay in the same chronological order they were written, matching how a single never-rotated file would read. Because rotation can occur mid-trace, a single logical trace may be split across files.

Load local traces grouped by trace_id.

include_rotated is forwarded to :func:load_events; see its note about traces possibly being split across rotated files.

Send local JSONL trace events to a Bir ingestion server.

Transient failures are retried with exponential backoff: a network error, timeout, or HTTP 5xx is retried up to retries times (default 2), sleeping backoff * 2**attempt seconds between tries (backoff defaults to 0.5). A 4xx response is a permanent rejection and is raised immediately without retry, matching the un-retried behavior. A healthy send still makes a single attempt, so the default behavior is unchanged.

mark_sent is opt-in bookkeeping for cheap re-sends. When True, the IDs the server accepts are recorded in a sidecar file next to the trace file (<trace_path>.sent) and skipped on later sends, so attempted reflects only events not yet recorded as sent. The sidecar is SDK-local: it never modifies the trace JSONL or the event schema, and a missing or corrupt sidecar is treated as empty so it can never block a send. With the default mark_sent=False nothing is recorded and re-sending the whole file stays safe because the server is idempotent on event IDs.

include_rotated is opt-in upload of size-rotated trace files. The default False uploads only the active trace file, matching the historical behavior. When True, retained rotated siblings (traces.jsonl.1 ..) created by configure(max_bytes=...) are uploaded oldest-first followed by the active file, so rotation can no longer strand unsent events. Events are deduplicated by ID when a rotated file overlaps the active file, and the mark_sent sidecar still anchors to the active trace path so recorded IDs are skipped across the whole selected file set.

Return the active trace's id, or None outside any trace.

The value is the same id written to the trace_id field of every event recorded while this trace is active, so an application log stamped with it can later be correlated with the trace. Read from a task-local context, so each asyncio task and thread observes its own active trace and never another's. While recording is disabled (configure(enabled=False)) or the trace was sampled out, this still returns the live id inside the trace so log correlation keeps working even though nothing is persisted.

Return the innermost active span's id, or None outside any trace.

Inside a nested span()/generation()/tool_call() this is the innermost open node's id; directly inside a trace with no open child it is the trace root's id. The value is the same id written to the parent_id field of any child event created at this point, so it names what an event recorded now would attach to. Read from a task-local context, so each asyncio task and thread observes its own ids and never another's. Like :func:get_current_trace_id, this still returns the live id while recording is disabled or the trace was sampled out, so log correlation is unaffected.