# Metrics and steps

Shape your metric keys and steps well up front — it is what makes runs easy to
compare later and keeps the training loop light.

## Name metrics by namespace

Use slash-separated metric keys:

```text
train/loss
train/reward
val/accuracy
eval/return_mean
test/macro_f1
optimizer/grad_norm
system/gpu_memory_mb
```

The dashboard groups panels and catalog entries by prefix. Namespaces also make
search and Compare rows readable when a project has many keys.

Good defaults:

| Namespace | Typical use |
| --- | --- |
| `train/` | Training loss, reward, throughput, gradient health. |
| `val/` | Validation loss, validation accuracy, validation calibration. |
| `eval/` | Offline or periodic evaluation metrics. |
| `test/` | Final held-out metrics. |
| `optimizer/` | Learning rate, grad norm, scheduler values. |
| `model/` | Weight norm, parameter count, architecture metadata. |
| `system/` | CPU, GPU, memory, and runtime counters. |

## Choose step semantics

Steps must be finite, nonnegative numbers.

```python
run.log_metrics({"train/loss": 0.42}, step=10)
```

Use one meaning consistently inside a project:

| Workflow | Recommended step |
| --- | --- |
| Epoch training | Epoch number. |
| Long training loop | Optimizer step or global batch step. |
| RL | Environment step, episode index, or evaluation interval. Pick one per metric namespace. |
| Distributed training | Global step shared by all ranks. |

The UI expects a metric series to move forward over time. The SDK warns when a
new value for the same metric uses a lower step than a value already logged in
the process.

## Batch scalar values

Prefer one `log_metrics(...)` call per step:

```python
run.log_metrics(
    {
        "train/loss": loss,
        "train/tokens_per_second": tokens_per_second,
        "optimizer/grad_norm": grad_norm,
        "eval/accuracy": eval_accuracy,
    },
    step=global_step,
)
```

Avoid one network call per metric unless a metric is produced by a separate
process. The hosted API accepts up to 1,000 scalar metrics per batch; the SDK
does not preflight the batch count before the request.

## Use timestamps when needed

If you omit a timestamp, the SDK stamps each point with the client's wall-clock
time at the moment of the `log` call in the default async mode and in spool
mode. Only in `upload_mode="sync"` does the server record its own ingest time
instead. Provide an explicit timestamp when you replay data or when step order
and wall-clock order are intentionally different:

```python
run.log_metrics(
    {"train/loss": 0.18},
    step=21,
    timestamp="2026-05-10T12:00:00Z",
)
```

Charts can use step or logged time as the x-axis. Step is usually better for
model comparison; time is useful for wall-clock debugging.

## Know how axes scale

Accuracy, precision, recall, F1, and AUC usually live in `0..1`. The dashboard
uses normalized y-axes for common unit-bounded metrics so small differences are
legible across runs. Return, reward, loss, and arbitrary custom metrics
auto-scale to observed values.

## Understand summary values

Run lists and Compare use maintained summaries instead of scanning every metric
point on every page load. For each run and key, the server tracks count, min,
max, latest, latest step, best, and aggregate moments used for mean/variance.
Raw history remains available through bounded series endpoints, so large charts
request only the keys and run IDs they need.

## Next steps

- [SDK logging](/docs/sdk/logging.md) — create runs and log from the loop
- [Buffering, offline replay, and spool mode](/docs/sdk/reliability.md) — upload modes and durability
- [Distributed training](/docs/sdk/distributed-training.md) — rank metrics and global steps
- [Metrics and charts in the dashboard](/docs/dashboard/metrics-charts.md)
- [Query runs and metrics](/docs/sdk/querying-data.md) — read series back from scripts

## Agent navigation

- [Docs index](/llms.txt)
- [Full docs bundle](/llms-full.txt)

### Get Started

- [Overview](/docs/index.md)
- [Quickstart](/docs/quickstart.md)
- [Core Concepts](/docs/concepts/core-concepts.md)
- [Pricing](/docs/pricing.md)
- [Benchmarks](/docs/benchmarks.md)
- [Examples](/docs/guides/examples.md)
- [Troubleshooting](/docs/troubleshooting.md)

### SDK

- [Installation Auth](/docs/sdk/installation-auth.md)
- [Logging](/docs/sdk/logging.md)
- [Tracing](/docs/sdk/tracing.md)
- [Metrics Steps](/docs/sdk/metrics-steps.md) (current page)
- [Config Tags Notes](/docs/sdk/config-tags-notes.md)
- [Artifacts Checkpoints](/docs/sdk/artifacts-checkpoints.md)
- [Rich Objects](/docs/sdk/rich-objects.md)
- [Distributed Training](/docs/sdk/distributed-training.md)
- [Console System Integrations](/docs/sdk/console-system-integrations.md)
- [Reliability](/docs/sdk/reliability.md)
- [Cli Login](/docs/sdk/cli-login.md)
- [Querying Data](/docs/sdk/querying-data.md)
- [Agent Mcp](/docs/sdk/agent-mcp.md)
- [Examples Patterns](/docs/sdk/examples-patterns.md)

### Integrations

- [Overview](/docs/integrations/overview.md)
- [Pytorch Lightning](/docs/integrations/pytorch-lightning.md)
- [Huggingface Transformers](/docs/integrations/huggingface-transformers.md)
- [Keras](/docs/integrations/keras.md)
- [Wandb](/docs/integrations/wandb.md)

### Dashboard

- [Tour](/docs/dashboard/tour.md)
- [Organizations Workspaces](/docs/dashboard/organizations-workspaces.md)
- [Runs Workspace](/docs/dashboard/runs-workspace.md)
- [Metrics Charts](/docs/dashboard/metrics-charts.md)
- [Run Detail](/docs/dashboard/run-detail.md)
- [Traces](/docs/dashboard/traces.md)
- [Compare Runs](/docs/dashboard/compare-runs.md)
- [Research Dashboards](/docs/dashboard/research-dashboards.md)
- [Artifacts Files](/docs/dashboard/artifacts-files.md)
- [Run Health](/docs/dashboard/alerts.md)
- [Datasets](/docs/dashboard/datasets.md)
- [Checkpoints](/docs/dashboard/checkpoints.md)
- [Reports](/docs/dashboard/reports.md)
- [Settings Api Keys](/docs/dashboard/settings-api-keys.md)
- [Api Tab](/docs/dashboard/api-tab.md)
- [Onboarding Team Billing](/docs/dashboard/onboarding-team-billing.md)

### Data

- [Imports](/docs/guides/imports.md)
- [W&B alternative](/docs/guides/wandb-alternative.md)
- [InstantML vs MLflow](/docs/guides/instantml-vs-mlflow.md)
- [W&B import guide](/docs/guides/wandb-import-guide.md)
- [W&B and Neptune imports](/docs/guides/wandb-neptune-imports.md)
- [Export Usage Limits](/docs/guides/export-usage-limits.md)
- [Pricing Limits Billing](/docs/guides/pricing-limits-billing.md)
- [Auth Billing Storage](/docs/guides/auth-billing-storage.md)
- [Customer Owned Clickhouse](/docs/guides/customer-owned-clickhouse.md)
- [Observability](/docs/guides/observability.md)

### API

**Practical API guides**

- [Authentication](/docs/api/authentication.md)
- [Errors And Limits](/docs/api/errors-and-limits.md)
- [Health Observability](/docs/api/health-observability.md)
- [Projects Runs](/docs/api/projects-runs.md)
- [Metrics Series](/docs/api/metrics-series.md)
- [Attributes Objects](/docs/api/attributes-objects.md)
- [Artifacts](/docs/api/artifacts.md)
- [Reports](/docs/api/reports.md)
- [Iframe Embeds](/docs/api/iframe-embeds.md)
- [Import Export Usage](/docs/api/import-export-usage.md)
- [Dashboard Control State](/docs/api/dashboard-control-state.md)
**Architecture**

- [System Overview](/docs/architecture/system-overview.md)
- [Service Planes](/docs/architecture/service-planes.md)
- [Storage Model](/docs/architecture/storage-model.md)
- [Google Clickhouse](/docs/architecture/google-clickhouse.md)
- [Auth Tenancy](/docs/architecture/auth-tenancy.md)
- [Schema Reference](/docs/architecture/schema-reference.md)

### API Reference

- [API Reference](/docs/api-reference.md)