Rollout documentation

Rollout client

Construct a client with Rollout(...). Constructor options are documented on Configuration; its public methods are below. The resolved configuration is available read-only as client.config.

Method	Returns	Description
`trace(name, *, user_id=…, conversation_id=…, …)`	Trace	Open a trace context manager.
`span(span_type, *, name=…, model=…, …)`	Span	Open a span on the active trace.
`wrap(obj, , provider=None, *options)`	client	Instrument a provider client in place.
`wrap_tools(tools, **options)`	mapping/list	Instrument a tool registry.
`identify_user(user_id, *, traits=…, …)`	—	Send a user identity event.
`feedback(name, value, *, trace_id=…)`	—	Record explicit feedback on a trace.
`signal(name, value, *, trace_id=…)`	—	Record a behavioral signal on a trace.
`user(*, user_id=…, traits=…, …)`	UserContext	Scope user identity to a block.
`capture_event(event_type, , …, *fields)`	—	Enqueue a raw observability event.
`check(*, verbose=True)`	CheckResult	Send a diagnostic trace and verify ingestion.
`acheck(*, verbose=True)`	CheckResult	Async check().
`flush() / shutdown()`	—	Drain the queue / drain and stop the worker.
`aflush() / ashutdown()`	—	Async flush / shutdown.

Trace

Returned by client.trace(...). Use it as a (sync or async) context manager.

Method	Returns	Description
`span(span_type, *, name=…, …)`	Span	Open a span within this trace.
`llm(name, *, model=…, provider=…, stream=False)`	Span	Shorthand for an llm span.
`tool(name, *, tool_call_id=…, arguments=…)`	ToolCall	Open a tool.call / tool.result pair.
`message(*, role, content, tool_call_id=…, is_internal=False)`	—	Record a conversation message.
`feedback(name, value)`	—	Record explicit feedback on this trace.
`signal(name, value)`	—	Record a behavioral signal.
`identify_user(user_id, *, traits=…)`	—	Associate a user with this trace.

Span

Returned by trace.span(...) / trace.llm(...). Latency, parent span, and error status are captured automatically.

Method	Description
`record_input(value)`	Record the input to the span (pydantic models serialize automatically).
`record_output(value)`	Record the output from the span.
`set_usage(*, input_tokens=…, output_tokens=…, cost_usd=…, …)`	Record token and cost usage.
`record_chunk(text)`	Append a streamed chunk to the rolling preview.
`end(output=None, *, usage=None, status="ok", error=None)`	Finalize the span. Safe to call once; idempotent.

ToolCall

Returned by trace.tool(...). Entering records the tool.call; exiting records the tool.result (an error if an exception propagates).

Method	Description
`record_output(value)`	Record the tool's result for the terminal tool.result event.

Module-level API

After rollout.init(...), these route through the global client. Import the package as import mv37.rollout as rollout.

Function	Description
`init(**options)`	Create and store the global client (returns it).
`get_client()`	Return the global client.
`current_trace() / current_span()`	Return the active Trace / Span, or None.
`wrap(obj, …) / wrap_tools(tools, …)`	Instrument a provider client / tool registry.
`identify_user(…) / feedback(…) / signal(…)`	Identity and outcome events on the active trace.
`user(…)`	User-scoping context manager.
`capture_event(event_type, …)`	Enqueue a raw observability event.
`check() / acheck()`	Diagnostic connectivity check.
`flush() / shutdown() / aflush() / ashutdown()`	Lifecycle, against the global client.

The decorators (all accept an optional name; sync and async):

Decorator	Description
`@agent`	Agent entry point — a fresh, flushed trace per call.
`@trace`	A trace per call (also a context manager).
`@span`	A typed span (also a context manager).
`@tool`	A tool.call / tool.result pair.
`@task`	A task span — a multi-step unit of work.

Helpers

Both return a dict ready to splat into span.set_usage(...), and an empty dict if the response carries no usage.

helpers.py

from mv37.rollout import usage_from_openai, usage_from_anthropicspan.set_usage(**usage_from_openai(response))     # input/output/total/cached/reasoning tokensspan.set_usage(**usage_from_anthropic(response))  # input/output tokens + cache tokens

Result types

Type	Fields
`CheckResult`	ok, accepted, rejected, errors, message — returned by check().
`EventBatchResponse`	Raw response from the ingest batch endpoint.
`EventBatchError`	Details for one rejected event.
`RolloutConfig`	The resolved, validated configuration (client.config).

Type aliases for attributes and usage are exported too: EventAttributes, UserTraits, and UsageDict (all dict[str, Any]).

Exceptions

Exception	Raised when
`UnsupportedIntegrationError`	wrap() is given an object or provider it cannot instrument.
`MissingDependencyError`	An integration is used without its optional dependency installed.

Both subclass IntegrationError. Provider exceptions from the wrapped client are never swallowed — they propagate untouched.

Event types

Most users never construct events directly — the trace, span, and tool APIs build them for you — but every method maps to a typed event on the ingest API. The set includes:

events.txt

trace.start   trace.endspan.start    span.update    span.endmessagellm.request   llm.response   llm.stream_start   llm.stream_chunk   llm.stream_endtool.call     tool.resultretrieval     eval.result    error    metricfeedback      user.signal    identity.update

Note

Use client.capture_event(event_type, ...)only when you need to emit an event the high-level API doesn't cover. For everything else, prefer the trace, span, and tool methods.