metrana 0.0.9

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"

    # Aggregation rules
    aggregation_rules: list[AggregationRule] | None = None,

    # 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 env_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 env_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 env_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 env_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)

Aggregation Rules

Aggregation rules tell the ingestion worker how to derive new series from existing ones. They are declared once at run creation and applied automatically as data arrives.

from metrana import AggregationRule, AggregationFn

metrana.init(
    ...,
    aggregation_rules=[
        # Mean and max reward collapsed across environments.
        # aggregate_over_labels=["environment_id"] strips environment_id from
        # the output, merging all per-environment series into one.
        AggregationRule(
            source_scale="EPISODE",
            output_scale="EPISODE",
            fns=[AggregationFn.AGGREGATION_FN_MEAN, AggregationFn.AGGREGATION_FN_MAX],
            aggregate_over_labels=["environment_id"],
            output_name_suffix="/across_envs",
        ),
        # Min and sum of a specific metric per episode
        AggregationRule(
            metric_name="reward",
            source_scale="EPISODE",
            output_scale="EPISODE",
            fns=[AggregationFn.AGGREGATION_FN_MIN, AggregationFn.AGGREGATION_FN_SUM],
            output_metric_name="reward/final",
        ),
    ],
)

Rule fields

Field	Type	Description
metric_name	str | None	Metric to apply the rule to. If absent, applies to every metric matching source_scale and aggregate_over_labels
source_scale	str	Scale of the source series (e.g. "EPISODE", "ENVIRONMENT_STEP")
output_scale	str	Scale of the derived output series
fns	list[AggregationFn]	Aggregation functions to apply. Each function produces a separate output series. At least one required.
aggregate_over_labels	list[str]	Labels to aggregate over and strip from the output. Series that share the same values for all other labels are merged together, and these labels disappear from the result. Empty list merges all matching series unconditionally.
output_metric_name	str | None	Output series name. Only valid when metric_name is set; defaults to metric_name
output_name_suffix	str | None	Suffix appended to each source metric name when metric_name is absent. Ignored when both metric_name and output_metric_name are set

Aggregation functions

Value	Description
AggregationFn.AGGREGATION_FN_MEAN	Mean of values in the group
AggregationFn.AGGREGATION_FN_MAX	Maximum value in the group
AggregationFn.AGGREGATION_FN_SUM	Sum of values in the group
AggregationFn.AGGREGATION_FN_MIN	Minimum value in the group
AggregationFn.AGGREGATION_FN_STD_DEV	Standard deviation of values in the group
AggregationFn.AGGREGATION_FN_COUNT	Count of values in the group

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)