Rollout documentation

Constructor options

All constructor parameters mirror the environment variables below, plus a set of advanced delivery and privacy options. The same arguments are accepted by rollout.init(...).

config.py

client = Rollout(    api_key="...",    agent_name="support_agent",    environment="production",    sample_rate=0.5,              # keep 50% of traces    sync_mode=True,               # send immediately (tests/debugging only)    debug=True,                   # verbose logging    disabled=False,    before_send=lambda e: e,      # mutate or drop events before enqueue    capture_stream_chunks=False,  # persist every token (off by default))

Identity & routing

These describe where events go and how runs are labeled. Each has a matching environment variable (see below).

Option	Type	Default	Description
api_key	str \| None	—	Workspace API key.
base_url	str	hosted endpoint	Override the ingest endpoint.
environment	str \| None	None	Deployment environment, e.g. production.
release	str \| None	None	App version or git SHA.
service_name	str \| None	None	Service identifier.
agent_name	str \| None	None	Default agent name for traces.
agent_id	str \| None	None	Agent ID.
agent_version	str \| None	None	Agent version.
deployment	str \| None	None	Deployment slot or region.

Delivery & behavior

These control batching, sampling, privacy, and streaming. They are constructor-only — there are no environment variables for the queue and batch tuning options.

Option	Type	Default	Description
sample_rate	float	1.0	Fraction of traces to keep (0.0–1.0).
sync_mode	bool	False	Send events inline in the calling thread (tests only).
debug	bool	False	Verbose logging.
disabled	bool	False	Turn the SDK into a no-op.
before_send	callable \| None	None	Mutate an event, or return None to drop it.
scrubber	callable \| None	None	Redact or strip fields on every event.
send_default_pii	bool	False	Whether to send default PII. Never required.
capture_stream_chunks	bool	False	Persist every streamed token.
stream_preview_chars	int	4096	Size of the rolling stream preview.
auto_instrument	tuple[str, ...]	()	Provider names to instrument automatically.
max_queue_events	int	1000	Max events buffered in memory.
max_queue_bytes	int	4 MB	Max bytes buffered in memory.
max_batch_events	int	100	Max events per outgoing batch.
max_batch_bytes	int	512 KB	Max bytes per outgoing batch.
flush_interval	float	2.0	Seconds between automatic flushes.
shutdown_timeout	float	5.0	Seconds to wait for the queue to drain on shutdown.

Note

before_send and scrubber are covered in detail on Privacy & redaction.

Environment variables

Set these instead of passing arguments — handy for keeping configuration out of code and switching behavior per deployment.

Variable	Description
ROLLOUT_API_KEY	API key.
ROLLOUT_BASE_URL	Override ingest endpoint.
ROLLOUT_ENVIRONMENT	Deployment environment, e.g. production.
ROLLOUT_RELEASE	App version or git SHA.
ROLLOUT_SERVICE_NAME	Service identifier.
ROLLOUT_AGENT_NAME	Agent name.
ROLLOUT_AGENT_ID	Agent ID.
ROLLOUT_AGENT_VERSION	Agent version.
ROLLOUT_DEPLOYMENT	Deployment slot or region.
ROLLOUT_SAMPLE_RATE	Trace sample rate (0.0–1.0).
ROLLOUT_DEBUG	Enable verbose logging (true/false).
ROLLOUT_DISABLED	Disable the SDK entirely (true/false).

Tip

Boolean variables accept 1/true/yes/on and 0/false/no/off (case-insensitive). Empty string values are treated as unset.

Sampling

sample_rate keeps a fraction of traces. Sampling is decided per trace: once a trace is sampled in, all of its spans and events are kept, so you never get partially-sampled traces. A rate of 1.0 (the default) keeps everything; 0.0 keeps nothing.

Disabling the SDK

Set disabled=True or ROLLOUT_DISABLED=trueto turn the SDK into a no-op without changing application code — useful for tests, CI, local scripts, and as an emergency kill-switch. Traces, spans, and decorators still run your code; they just don't emit events.