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
)

Strings or enums

This reference writes the option arguments as strings ("block", "warn", "zstd"), which is the shortest form and the one most code uses. Every one of them also accepts a typed enum exported from the metrana package root:

Enum	Argument	Members
BackpressureStrategy	backpressure_strategy	Block, DropNew, Raise, SpoolThenRaise
DeliveryPolicy	delivery_policy	AllOrCrash, TolerateLoss
ResumeStrategy	resume_strategy	Never, Allow
InitMode	init_mode	OnlineOnly, Offline
ErrorStrategy	rendering_error_strategy	Silent, Warn, RaiseOnLog, RaiseOnClose
RenderingUploadMode	upload_renderings	All, Triggered, Off
Compression	compression	Off, Zstd
LogLevel	log_level	Trace, Debug, Info, Success, Warn, Error, Critical, Off
DiskCompression	disk’s compression	Off, Lz4, Zstd

import metrana

metrana.init(
    workspace_name="ws", project_name="proj", run_name="run-001",
    backpressure_strategy=metrana.BackpressureStrategy.SpoolThenRaise,
    delivery_policy=metrana.DeliveryPolicy.AllOrCrash,
)

The enums are worth reaching for when you want your editor and type-checker to catch a typo — a misspelled string is only rejected at init(), at runtime. String values are case-insensitive, so "BLOCK" and "block" are equivalent.

DiskCompression is the exception: it’s a numeric enum with no string equivalent, so pass the member itself (metrana.DiskCompression.Zstd) when configuring a disk spool.

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; falls back to METRANA_INGESTION_URL, then https://ingestion.metrana.ai.
artifact_api_url	None	Artifact / video endpoint used by rendering uploads and by the artifact and video helpers; falls back to METRANA_ARTIFACT_API_URL, then https://artifacts.metrana.ai.
query_api_url	None	Endpoint every QueryClient built in this process defaults to; falls back to METRANA_QUERY_API_URL, then https://query.metrana.ai.

The three endpoint arguments configure the three services the SDK talks to — see Service endpoints for the full resolution order and self-hosting notes. | 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".
init_mode	"online_only"	Online vs. offline start: "online_only" (the handshake must succeed) or "offline" (never contact the backend; requires a spool, cannot fork).
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", "raise", or "spool_then_raise" (fail over to the disk spool, then raise only if even that can’t absorb it; requires disk).
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	1.0	Grace period a non-blocking backpressure policy waits before dropping/raising/spooling.
disk_spool_retry_timeout_secs	5.0	"spool_then_raise" only: extra wait after the triggered failover for the spool to unblock the call, on top of enqueue_timeout_secs / the flush timeout.
ack_stall_timeout_secs	60.0	Max zero-ack-progress time on a live stream before it is treated as failed (reconnect → retry/failover). None disables the watchdog.
close_spool_reserve_secs	5.0	Tail of a bounded close/shutdown window reserved for the emergency spool flush (capped at half the window). 0 disables it.
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	(default spool)	The on-disk failover spool. Left unset: the best-effort default under METRANA_DISK_SPOOL_DIR (~/.metrana/spools) plus a <hostname> component, dropped with a warning if unusable. A directory path or DiskConfig requires the spool there (MetranaSpoolUnavailableError otherwise). 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.
err_initial_backoff_secs / err_max_backoff_secs	1.0 / 60.0	Backoff between disk I/O retries.
coalesce_min_batch	None	Records batched per fsync while spooling; None sizes it from max_pending_requests.
coalesce_timeout_secs	1.0	Longest a partial batch waits before it is fsync’d.
recovery_initial_backoff_secs / recovery_max_backoff_secs	60.0 / 900.0	Backoff of the recovery channel’s gRPC retries until its first successful re-delivery.
metadata_checkpoint_interval_secs	60.0	How often a healthy run rolls its step-cursor journal into a fresh snapshot (see How it works). None turns the journal and the periodic snapshot off: metadata is then written only at failover, so a crash on the gRPC channel resumes with no cursors.
foreign_cursor_dirs	[]	Other machines’ spool bases for this run, read for their step cursors only. The default spool fills this in with the sibling <hostname> directories; an explicit disk= leaves it empty.

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 and upload 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_num_encoder_threads	min(4, cpu_count)	Encoder threads; each env is pinned to one, so more threads = more envs encoding in parallel.
rendering_max_concurrent_encoders	16	Global cap on encoders open at once, across all threads.
rendering_queue_max_size	None	Bound on each encoder thread’s frame queue.
upload_renderings	True	Upload finalized renderings to the portal: "all"/True, "triggered", or "off"/False.
rendering_upload_concurrency	4	Videos uploaded in parallel.
rendering_upload_warn_threshold	100	Pending-upload backlog depth at which a one-shot warning fires.
rendering_delete_after_upload	True	Delete the local .mp4 once its video commits. Under upload_renderings="triggered", renderings with no trigger event are always discarded regardless of this setting.
rendering_upload_close_timeout	None	Seconds to drain pending uploads on close(). None waits indefinitely.
rendering_storage	None	s3://bucket/prefix to store rendering bytes in your own bucket as references. Needs the s3 extra.
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.