init() configuration

metrana.init(...) must be called once before any log call or close(). It creates or resumes the run and builds the background engine. This page is the full argument reference, grouped by purpose.

metrana.init(
    workspace_name="ws",
    project_name="proj",
    run_name="run-001",
    api_key="...",          # or METRANA_API_KEY
)

Run identity

Argument	Default	Purpose
`workspace_name`	(required)	Workspace the run belongs to.
`project_name`	(required)	Project (within the workspace) the run belongs to.
`run_name`	(required)	Name identifying the run to create or resume.
`experiment_name`	`None`	Optional experiment name grouping the run.
`api_key`	`None`	API key; falls back to `METRANA_API_KEY`.
`ingestion_url`	`None`	Ingestion endpoint; `None` uses `https://ingestion.metrana.ai`.
`create_project_if_missing`	`True`	Create the project if it does not exist.

Run metadata (create-only)

Applied only by the process that creates the run — see Config & attributes.

Argument	Default	Purpose
`config`	`None`	Dict logged as queryable run attributes under `config/`.
`tags`	`None`	Tags attached to the run at creation.
`description`	`None`	Description attached at creation.

Resume & fork

See Resuming & forking.

Argument	Default	Purpose
`resume_strategy`	`"never"`	How to handle an existing run: `"never"` or `"allow"`.
`orchestration_id`	`None`	Token shared by every process logging into the same run; auto-resolved if `None`.
`logger_id`	`None`	Stable per-writer id (e.g. one per rank) so a restart isn’t mistaken for a new concurrent writer.
`fork_from_run`	`None`	Name of an existing run to fork from. Requires `fork_at_step`.
`fork_at_step`	`None`	Inclusive step to fork at (major step for RL). Requires `fork_from_run`.

Delivery & reliability

See Guarantees & retries.

Argument	Default	Purpose
`backpressure_strategy`	`"block"`	When the queue is full: `"block"`, `"drop_new"`, or `"raise"`.
`delivery_policy`	`"all_or_crash"`	When every channel gives up: `"all_or_crash"` or `"tolerate_loss"`.
`max_send_retries`	`15`	gRPC send retries before failover to spool / delivery policy. `None` retries forever.
`send_retry_initial_backoff_secs`	`0.05`	Initial delay before the first send retry.
`send_retry_max_backoff_secs`	`15.0`	Cap on the exponential retry backoff.
`enqueue_timeout_secs`	`0.1`	Grace period a non-blocking backpressure policy waits before dropping/raising.
`init_timeout_secs`	`120.0`	Timeout for the run init handshake.
`connect_timeout_secs`	`5.0`	TCP/gRPC connect timeout.

Disk spool

See Disk spool.

Argument	Default	Purpose
`disk`	`None`	Directory path or `DiskConfig` enabling the on-disk failover spool. `None` disables it.

disk="/path" uses all DiskConfig defaults. To tune, pass a DiskConfig:

`DiskConfig` field	Default	Purpose
`dir` (positional)	(required)	Base spool directory.
`max_size_bytes`	`8 << 30` (8 GiB)	Spool size cap (no “unlimited” sentinel — set large to uncap).
`segment_size_bytes`	`100 << 20` (100 MiB)	On-disk segment file size.
`compression`	`DiskCompression.Zstd`	On-disk compression.
`zstd_level`	`3`	zstd level.
`io_max_retries`	`60`	Disk I/O retries; `None` = forever.

See Disk spool → Capacity.

Values

Argument	Default	Purpose
`default_dtype`	`"float32"`	Storage precision for float-typed metric values when a log call passes no `dtype`: `"float64"`, `"float32"` or `"float16"` (integer-typed values ship as `float64` to stay exact). The per-call-oriented `"int64"`/`"int32"` are accepted too, but as a run-wide default they would truncate every float metric.

Throughput

See Tuning & observability.

Argument	Default	Purpose
`queue_capacity`	`10_000`	In-process send-queue depth. `None` reads `METRANA_EVENT_QUEUE_MAX_SIZE`.
`max_pending_requests`	`30`	Max in-flight streaming requests.
`batch_max_age_secs`	`1.0`	How long points coalesce into a batch before sending.
`max_msg_size`	`1 << 20`	Max serialized request size in bytes.
`compression`	`"none"`	Outbound gRPC compression: `"none"` or `"zstd"` (server must accept zstd).

Logging (diagnostics)

Argument	Default	Purpose
`log_level`	`None`	Diagnostic level; configures loguru when `autoconfigure_loguru` is `True`.
`autoconfigure_loguru`	`True`	If `True`, configure loguru at `log_level`.

Rendering

See Renderings. Requires the rendering extra.

Argument	Default	Purpose
`rendering_error_strategy`	`"warn"`	Frame-encoding error handling: `"silent"`, `"warn"`, `"raise_on_log"`, `"raise_on_close"`.
`rendering_output_dir`	`None`	Where encoded MP4s are written.
`rendering_fps`	`30`	Output frame rate.
`rendering_max_concurrent_encoders`	`1`	Parallel encoders across `(env_id, episode)` pairs.
`rendering_queue_max_size`	`None`	Bound on the frame queue.
`skip_drain_render_on_close`	`None`	If `True`, `close()` drops queued frames. `None` reads `METRANA_SKIP_DRAIN_RENDER_ON_CLOSE`.
`rendering_close_timeout`	`None`	How long `close()` waits to drain queued frames.

Raises

init() can raise:

NoMetranaApiKeyError — no api_key and METRANA_API_KEY unset.
MetranaRunAlreadyExistsError — under resume_strategy="never", the run exists and can’t be confirmed as this job’s.
MetranaOrchestrationIdMismatchError — the existing run carries a different orchestration id (a subclass of the above).
MetranaLoggerInitError — the run otherwise failed to initialize (connection failure, init timeout).

See Errors.