tracing.init() configuration

metrana.tracing.init(
    workspace_name=None, project_name=None, run_name=ACTIVE_RUN,
    *,
    organization=None, ingestion_url=None, api_key=None, log_level=None, disk=DEFAULT_DISK,
    backpressure_strategy=None, compression=None, delivery_policy=None, queue_max_bytes=DEFAULT,
    enqueue_timeout_secs=DEFAULT, disk_spool_retry_timeout_secs=DEFAULT, connect_timeout_secs=DEFAULT,
    max_pending_requests=DEFAULT, max_send_retries=DEFAULT, send_retry_initial_backoff_secs=DEFAULT,
    send_retry_max_backoff_secs=DEFAULT, ack_stall_timeout_secs=DEFAULT, close_spool_reserve_secs=DEFAULT,
    batch_max_age_secs=DEFAULT, max_msg_size=DEFAULT, sample_rate=None,
)

Called with no arguments after metrana.init, it anchors to that run and takes the run’s credentials and delivery settings: every delivery argument left at its default above is the run’s value, except compression. An explicit value is the caller’s, None included where it means something (disk=None for no spool, ack_stall_timeout_secs=None for no watchdog, max_send_retries=None for unbounded retries). Anchored elsewhere, an argument left at its default is the tracing default below. metrana.tracing.Tracer(workspace_name, project_name, run_name=None, *, ...) takes the same keyword arguments with those defaults spelled out, without the run-derived fallbacks.

Target

Argument	Meaning	Default
workspace_name	Workspace the traces belong to.	The active run’s. Required without one.
project_name	Project the traces belong to.	The active run’s. Required without one.
run_name	Run the traces are anchored to; its traces carry a policy step. None anchors them to the project alone, for inference, with no step.	ACTIVE_RUN: the run metrana.init opened, when the workspace and project are that run’s; otherwise None.
organization	Organization slug owning the workspace, when the workspace name is not unique on its own.	The active run’s, when the workspace is the run’s.

Credentials and endpoint

Argument	Default
api_key	The active run’s, then METRANA_API_KEY.
ingestion_url	The active run’s, then METRANA_INGESTION_URL, then the public endpoint.
log_level	The active run’s, then METRANA_LOG_LEVEL.

Delivery

These are the logger’s settings under the same names, apart from queue_max_bytes, the tracer’s own; see init() configuration for each one’s meaning. A tracer derived from the run inherits the run’s values for all of them except compression.

Argument	Tracing default	Note
compression	zstd	The logger defaults to off: float payloads do not compress, trace bodies are text and shrink several-fold.
disk	The default spool under METRANA_DISK_SPOOL_DIR, best-effort	Traces spool under a #traces subtree of it, apart from the run’s spool.
backpressure_strategy, delivery_policy	METRANA_BACKPRESSURE_STRATEGY, METRANA_DELIVERY_POLICY	As the logger.
queue_max_bytes	256 MiB	The send queue’s bound, in bytes rather than the logger’s queue_capacity count: one update can carry bodies of up to 16 MiB. Never inherited from the run.
batch_max_age_secs, max_msg_size, max_pending_requests	1.0 s, 1 MiB, 30	How updates pack into requests and how many requests are in flight.
max_send_retries, send_retry_*_backoff_secs, ack_stall_timeout_secs, close_spool_reserve_secs	15, 0.05 s to 15 s, 60 s, 5 s	Retry and failover policy.

Volume

Argument	Default	Meaning
sample_rate	None	The share of traces recorded, decided once per root: 1.0 every trace, 0.01 one in a hundred. A root left out is an inert NoopSpan, children included. None reads METRANA_TRACING_SAMPLE_RATE, which itself defaults to 1.0; an unusable value there falls back to 1.0, with a warning. Outside 0.0 to 1.0 raises ValueError.

Environment variable	Meaning
METRANA_TRACING_DISABLED	1 / true / yes / on switches tracing off for the process: init() builds nothing and every trace, span and decorated call is inert.
METRANA_TRACING_SAMPLE_RATE	The sample_rate when init() / Tracer are not given one.

See Switching off, and sampling.

Step context

with metrana.tracing.step(100):
    ...                              # every trace opened here without step= is at step 100
metrana.tracing.current_step()       # 100 inside, None outside

The step is tracked per thread and per asyncio task, like the enclosing span and the ambient attributes of tracing.attributes(...).

Errors at initialization

Exception	When
MetranaNotInitializedError	init() called without a target and without an active run to derive one from — or get_tracer() with no tracer, no run, after tracing.close(), or with tracing disabled. A trace opened in that state is inert instead.
NoMetranaApiKeyError	No API key from any source.
MetranaSpoolUnavailableError	An explicitly given spool directory cannot be used. The default spool is dropped with a warning instead.
MetranaLoggerInitError	The tracer cannot start for another reason, e.g. an endpoint that does not parse.

A second tracing.init() while a tracer exists — one built implicitly from the run included — closes that tracer, delivering what it holds, and replaces it with the new settings.