Guarantees & retries

Metrana favours delivering your data over shaving microseconds off the hot path — while never blocking it forever. The defaults are chosen so a healthy run pays almost nothing and an unhealthy one fails loudly instead of silently dropping metrics.

Three knobs govern what happens as delivery comes under pressure: backpressure (queue full), retries (a send fails), and the delivery policy (everything has given up).

Backpressure: when the queue is full

backpressure_strategy (default "block") decides what an enqueue does when the in-process queue is full:

Strategy	Behaviour
"block" (default)	Wait for room rather than dropping. Bounded — the queue only stays full while delivery is stuck, which the retry policy itself bounds (and a disk spool drains quickly).
"drop_new"	Drop the new points. Protects the loop, but can lose data under sustained pressure.
"raise"	Raise MetranaEventQueueFullError.

The non-blocking policies wait up to enqueue_timeout_secs (default 0.1) for the queue to drain before they drop or raise.

Retries: when a send fails

max_send_retries (default 15) controls how many times a failed gRPC send is retried, with exponential backoff from send_retry_initial_backoff_secs (default 0.05) to send_retry_max_backoff_secs (default 15.0) — about 1.7 minutes total at the defaults.

When the retry budget is spent, the logger fails over to the disk spool if one is configured; otherwise the delivery policy below applies. max_send_retries=None retries gRPC forever.

Delivery policy: when everything gives up

delivery_policy (default "all_or_crash") decides what happens once every channel (gRPC and, if configured, the disk spool) has given up:

Policy	Behaviour
"all_or_crash" (default)	Stop the logger so the next log / flush / close raises MetranaSenderError. For an experiment tracker, a loud failure beats a silent hole.
"tolerate_loss"	Drop the data and keep the process running — for callers who would rather lose metrics than the job.

What the defaults actually guarantee

With the defaults (block + all_or_crash) and no disk spool:

• Transient outages survive — they’re retried.
• The only silent-loss path is a hard process kill (kill -9, or exiting without close()).
• A sustained outage (longer than the ~2-min retry budget) still loses the buffered window — but loudly: the loop blocks, then all_or_crash stops the logger and the next call raises.

So without a spool, “favouring delivery” means fail loud, not survive.

Close the gap with a disk spool

A disk spool turns a sustained outage into a transparent failover — data is written to disk and delivered when the backend returns. It’s off by default but strongly recommended for any real run. (Or opt into tolerate_loss / drop_new to drop-and-continue instead of block-then-crash.)

Rendering errors are separate

rendering_error_strategy (default "warn") governs only the Python rendering pipeline’s frame-encoding errors ("silent", "warn", "raise_on_log", "raise_on_close"). Engine delivery of metrics and attributes is governed by delivery_policy, not this. See Renderings.

See also

• Lifecycle: flush, close, shutdown — durability barriers and timeouts.
• Disk spool — the recommended durability layer.
• Errors — the exception types these policies raise.