# Metrics

Time-series data that changes over the course of a run: loss, accuracy, learning rate, and any custom scalars you want to chart.

## Streams

Every metric value lives on a *stream*. A stream is just a named series identified by a prefix, like `train` or `eval`. You select one by calling `exp.metrics(prefix)`, then `.log(...)` appends a point.

The unprefixed `exp.metrics.log(...)` writes to the root stream, which is the right place for run-wide scalars like `epoch` or `step`.

## Basic Logging

Log scalars by keyword. Nested `dict`s automatically route to child streams:

```python
from ml_dash import Experiment

with Experiment(prefix="alice/project/my-experiment").run as exp:
    for epoch in range(10):
        train_loss, train_acc = train_one_epoch(model)
        eval_loss, eval_acc = evaluate(model)

        exp.metrics.log(
            epoch=epoch,
            train=dict(loss=train_loss, accuracy=train_acc),
            eval=dict(loss=eval_loss, accuracy=eval_acc),
        )
```

The `train=dict(...)` form is equivalent to `exp.metrics("train").log(...)`. Pick whichever reads better at the call site.

## Explicit Streams

When metrics for a stream are produced at different points in the loop, address each stream directly and flush once you have a coherent snapshot:

```python
for epoch in range(10):
    exp.metrics("train").log(loss=train_loss, accuracy=train_acc)
    exp.metrics("eval").log(loss=eval_loss, accuracy=eval_acc)
    exp.metrics.log(epoch=epoch).flush()
```

Stream names are arbitrary; `system`, `lr`, `grad_norm`, etc. all work the same way.

## Reading

Read points back by index range:

```python
result = exp.metrics("train").read(start_index=0, limit=10)
for point in result["data"]:
    print(point["index"], point["data"])
```

## Per-Batch Logging

Logging every batch with `.log()` is fine but produces a lot of points. To accumulate batch-level values and emit one summarized row per epoch, see [Buffering](/buffering.md).

For configuration like learning rate and batch size, use [Parameters](/parameters.md). For text events and structured logs, see [Logging](/logging.md).

---

**Next:** Learn about [Files](/files.md) to upload models, plots, and artifacts.