metrana 0.1.1

Inephany client library to use Metrana.

Metrana Client Library

Metrana is a metrics tracking client for ML/RL training runs. It provides a simple three-function API to log metrics from training loops to the Metrana ingestion service, with asynchronous batching, configurable backpressure handling, and automatic retry on failure.

Installation

pip install metrana

The metrana-protobuf dependency is pulled in automatically.

Quick Start

import metrana

metrana.init(
    api_key="your-api-key",
    workspace_name="my-workspace",
    project_name="my-project",
    run_name="run-001",
)

for step in range(1000):
    loss, accuracy = train_step()
    metrana.log("loss", loss)
    metrana.log("accuracy", accuracy)

metrana.close()

The API key can also be provided via the METRANA_API_KEY environment variable, in which case api_key can be omitted from init().

API Reference

metrana.init()

Initialises the logger. Must be called once before log() or close().

metrana.init(
    api_key: str,
    workspace_name: str,
    project_name: str,
    run_name: str,
    experiment_name: str | None = None,

    # Behavioural strategies (can also be set via environment variables)
    resume_strategy: str | None = None,       # "Never" | "Allow"
    backpressure_strategy: str | None = None, # "DropNew" | "Block" | "Raise"
    error_strategy: str | None = None,        # "Silent" | "Warn" | "RaiseOnLog" | "RaiseOnClose"
    close_strategy: str | None = None,        # "Immediate" | "CompletePending" | "CompleteAll"
    log_level: str | None = None,             # "Trace" | "Debug" | "Info" | "Success" | "Warn" | "Error" | "Critical" | "Off"

    # Advanced
    num_dispatch_workers: int = 4,
    ingestion_url: str | None = None,         # Overrides the default API endpoint
)

metrana.log()

Logs a single metric value. Thread-safe and non-blocking by default.

metrana.log(
    metric_name: str,           # Name of the metric series
    value: float | int,         # Metric value
    scale: str | None = None,   # "ML_STEP" | "EPISODE" | "ENVIRONMENT_STEP" (default: "ML_STEP")
    step: int | None = None,    # Explicit step index; auto-increments per series if omitted. Not advised — prefer auto-increment.
    labels: dict[str, str] | None = None,  # Additional series labels
    timestamp: int | None = None,          # Unix nanoseconds; defaults to now
)

metrana.close()

Shuts down the logger. Behaviour depends on the configured close_strategy.

metrana.close()

metrana.log_rl_step()

Convenience wrapper for log() that fixes the scale to ML_STEP. Use this when logging per-gradient-update metrics from an RL training loop.

metrana.log_rl_step(
    metric_name: str,           # Name of the metric series
    value: float | int,         # Metric value
    step: int | None = None,    # Explicit step index; auto-increments per series if omitted. Not advised — prefer auto-increment.
    labels: dict[str, str] | None = None,  # Additional series labels
    timestamp: int | None = None,          # Unix nanoseconds; defaults to now
)

metrana.log_rl_episode()

Logs a metric on the EPISODE scale. Designed for per-episode summaries such as total reward or episode length. Automatically attaches rl_step and environment_id as labels so episode data can be correlated with training progress and individual environments.

metrana.log_rl_episode(
    metric_name: str,           # Name of the metric series
    value: float | int,         # Metric value
    episode: int | None = None, # Episode index used as the step; auto-increments if omitted. Not advised — prefer auto-increment.
    rl_step: int | None = None, # Training step recorded as the "rl_step" label
    env_id: int | None = None,  # Environment ID recorded as the "environment_id" label
    labels: dict[str, str] | None = None,  # Additional series labels
    timestamp: int | None = None,          # Unix nanoseconds; defaults to now
)

A one-time warning is emitted if either rl_step or environment_id is absent and not already present in labels.

metrana.log_rl_environment_step()

Logs a metric on the ENVIRONMENT_STEP scale. Designed for per-interaction data such as per-step rewards or observations. Automatically attaches episode, rl_step, and environment_id as labels.

metrana.log_rl_environment_step(
    metric_name: str,            # Name of the metric series
    value: float | int,          # Metric value
    env_step: int | None = None, # Environment step index used as the step; auto-increments if omitted. Not advised — prefer auto-increment.
    episode: int | None = None,  # Episode index recorded as the "episode" label
    rl_step: int | None = None,  # Training step recorded as the "rl_step" label
    env_id: int | None = None,   # Environment ID recorded as the "environment_id" label
    labels: dict[str, str] | None = None,  # Additional series labels
    timestamp: int | None = None,          # Unix nanoseconds; defaults to now
)

A one-time warning is emitted for each of episode, rl_step, and environment_id that is absent and not already present in labels.

Metric Scales

Scale	Use when
ML_STEP	One entry per gradient update / training step (default)
EPISODE	One entry per RL episode
ENVIRONMENT_STEP	One entry per RL environment interaction

Pass the scale name as a string or use metrana.StandardMetricScale:

from metrana import StandardMetricScale
metrana.log("reward", reward, scale=StandardMetricScale.EPISODE)

Strategies

Backpressure strategy

Controls what happens when the internal event queue is full.

Value	Behaviour
DropNew	Silently discard the incoming event (default)
Block	Block the calling thread until space is available
Raise	Raise MetranaEventQueueFullError

Error strategy

Controls how API errors are surfaced to the caller.

Value	Behaviour
Silent	Ignore errors
Warn	Log a warning and continue (default)
RaiseOnLog	Raise on the next log() call if errors have occurred
RaiseOnClose	Raise on close() if errors have occurred

Resume strategy

Controls what happens when a run with the same name already exists.

Value	Behaviour
Allow	Create a new run or resume an existing one (default)
Never	Always create a new run; raise if it already exists

Close strategy

Controls how pending events are handled on shutdown.

Value	Behaviour
Immediate	Shut down immediately, discarding pending events
CompletePending	Complete API requests already in flight, but discard events still queued (default)
CompleteAll	Wait for all queued events including those not yet dispatched

Environment Variables

All strategies and several other settings can be configured without code changes:

Variable	Default	Accepted values
METRANA_API_KEY	—	Your API key
METRANA_BACKPRESSURE_STRATEGY	DropNew	DropNew, Block, Raise
METRANA_ERROR_MODES	Warn	Silent, Warn, RaiseOnLog, RaiseOnClose
METRANA_RESUME_STRATEGY	Allow	Allow, Never
METRANA_CLOSE_STRATEGY	CompletePending	Immediate, CompletePending, CompleteAll
METRANA_LOG_LEVEL	Success	Trace, Debug, Info, Success, Warn, Error, Critical, Off
METRANA_EVENT_QUEUE_MAX_SIZE	unbounded	Integer (0 = unbounded)
METRANA_DISPATCH_QUEUE_MAX_SIZE	unbounded	Integer (0 = unbounded)
METRANA_ERROR_QUEUE_MAX_SIZE	unbounded	Integer (0 = unbounded)