# Logging

Structured event logging with timestamps, levels, and optional metadata. For numeric series use [Metrics](/metrics.md); for hyperparameters use [Parameters](/parameters.md).

## Basic Usage

```python
from ml_dash import Experiment

with Experiment(prefix="alice/project/my-experiment").run as exp:
    exp.log("Training started")
    exp.log("GPU memory low", level="warn")
    exp.log("Failed to load checkpoint", level="error")
```

## Log Levels

`debug`, `info` (default), `warn`, `error`, `fatal`.

```python
exp.log("Detailed debugging info", level="debug")
exp.log("Learning rate decreased", level="warn")
exp.log("Out of memory - aborting", level="fatal")
```

## Structured Metadata

Attach arbitrary fields via `metadata=`:

```python
exp.log(
    "Epoch completed",
    level="info",
    metadata={"epoch": 5, "train_loss": 0.234, "val_loss": 0.456},
)
```

## Error Tracking

```python
try:
    result = risky_operation()
except Exception as e:
    exp.log(
        f"Operation failed: {e}",
        level="error",
        metadata={"error_type": type(e).__name__},
    )
    raise
```

## Storage and Retrieval

**Local mode** writes JSONL to `.dash/<prefix>/logs/logs.jsonl`. Each line:

```json
{"timestamp": "2025-10-29T10:30:00Z", "level": "info", "message": "Training started", "metadata": null, "sequenceNumber": 0}
```

**Remote mode** stores entries in MongoDB, indexed by timestamp and level. Retrieve via the dashboard UI or the experiment API.

---

**Next:** Learn about [Parameters](/parameters.md) to track hyperparameters and configuration.