# Using Trackio for Real-Time Training Metrics on Hugging Face Spaces: A Complete Guide

> Learn how to use Trackio for real-time training metrics on Hugging Face Spaces. Monitor loss, learning rate, and system data live with this comprehensive guide.

- Repository: [Hugging Face/skills](https://github.com/huggingface/skills)
- Tags: tutorial
- Published: 2026-03-08

---

**Trackio automatically captures loss, learning rate, and system metrics during TRL training loops, storing them locally in SQLite and syncing to a Hugging Face Space for live dashboard monitoring.**

Trackio is an experiment-tracking library that integrates tightly with the 🤗 Transformers and TRL training loops. When a training script runs on a Hugging Face Space, Trackio can capture metrics in real time and serve them through a live dashboard. This guide explains how to implement Trackio in the `huggingface/skills` repository to monitor your model training without modifying your training loop code.

## How Trackio Integrates with TRL Training

Trackio hooks into the standard TRL trainer callbacks to capture metrics automatically. The integration follows a three-step lifecycle that requires minimal configuration in your training script.

### The Three-Step Architecture

**Initialization** – `trackio.init` creates a new run and optionally links it to a Hugging Face Space via the `space_id` parameter. This sets up a local SQLite database for metric storage and prepares the remote sync target if specified.

**Automatic Logging** – When you configure a TRL trainer (such as `SFTTrainer`) with `report_to="trackio"` and a matching `project` name, Trackio registers callbacks that log standard metrics including loss, step count, epoch, and learning rate. You can supplement these with custom metrics using `trackio.log`.

**Finalization** – Calling `trackio.finish()` flushes pending writes to the database and triggers the optional sync to your Hugging Face Space. The dashboard becomes available locally via `trackio.show()` or remotely at your Space URL.

## Setting Up Trackio in Your Training Script

The complete implementation is demonstrated in [`skills/hugging-face-model-trainer/scripts/train_sft_example.py`](https://github.com/huggingface/skills/blob/main/skills/hugging-face-model-trainer/scripts/train_sft_example.py). Here is the minimal code required to enable real-time tracking:

```python
import trackio
from datasets import load_dataset
from trl import SFTTrainer, SFTConfig
from peft import LoraConfig

# Initialize Trackio run with optional Space sync

trackio.init(project="my-ml-project", space_id="username/trackio")

# Load and split dataset

dataset = load_dataset("trl-lib/Capybara", split="train")
train, eval = dataset.train_test_split(test_size=0.1, seed=42).values()

# Configure trainer for automatic Trackio reporting

config = SFTConfig(
    output_dir="my-model",
    push_to_hub=False,
    num_train_epochs=2,
    per_device_train_batch_size=4,
    report_to="trackio",          # Enables automatic metric capture

    project="my-ml-project",      # Must match init() project name

    run_name="demo-run"
)

# Optional LoRA configuration

peft_cfg = LoraConfig(r=8, lora_alpha=32, task_type="CAUSAL_LM")

trainer = SFTTrainer(
    model="Qwen/Qwen2.5-0.5B",
    train_dataset=train,
    eval_dataset=eval,
    args=config,
    peft_config=peft_cfg,
)

trainer.train()          # Metrics logged automatically during training

trackio.finish()         # Flush logs and sync to Space

```

After execution, the script outputs a link to the dashboard at `https://huggingface.co/spaces/username/trackio`, enabling real-time monitoring of training progress.

## Configuring Automatic Metric Reporting

The integration requires only two configuration changes to existing TRL code: setting `report_to="trackio"` in your trainer configuration and ensuring the `project` name matches your `trackio.init()` call.

### Standard Metrics vs. Custom Logging

By default, Trackio captures **loss**, **learning rate**, **epoch**, and **step** metrics through the trainer's callback system. For custom values such as validation perplexity or reward scores, use the explicit logging function:

```python

# Inside training loop or evaluation callback

trackio.log({"validation_perplexity": 12.5, "custom_reward": 0.85})

```

These custom metrics appear alongside standard training metrics in the SQLite database and remote dashboard.

## Viewing Real-Time Metrics on Hugging Face Spaces

Trackio provides dual interfaces for metric visualization: a local dashboard for development and a public Space URL for collaboration.

### Local vs. Remote Dashboards

**Local viewing** – Run `trackio.show()` after `trackio.finish()` to launch the dashboard from your local SQLite database. This is useful for debugging before pushing to a Space.

**Remote viewing** – When you provide a `space_id` during initialization, `trackio.finish()` syncs the entire project to your Hugging Face Space. The dashboard becomes accessible at `https://huggingface.co/spaces/{username}/{space_name}` without requiring additional deployment steps.

The repository includes additional examples for other trainer types: [`train_grpo_example.py`](https://github.com/huggingface/skills/blob/main/train_grpo_example.py) demonstrates Trackio with GRPO trainers, while [`train_dpo_example.py`](https://github.com/huggingface/skills/blob/main/train_dpo_example.py) shows integration with DPO training loops.

## Summary

- **Trackio** integrates with TRL trainers via the `report_to="trackio"` configuration parameter.
- **Initialization** requires `trackio.init(project="name", space_id="optional")` to set up local SQLite storage and remote sync targets.
- **Automatic logging** captures loss, learning rate, and system metrics without code changes; custom metrics use `trackio.log`.
- **Finalization** with `trackio.finish()` ensures data integrity and triggers sync to Hugging Face Spaces for live dashboard access.
- **Source files** [`train_sft_example.py`](https://github.com/huggingface/skills/blob/main/train_sft_example.py), [`train_grpo_example.py`](https://github.com/huggingface/skills/blob/main/train_grpo_example.py), and [`train_dpo_example.py`](https://github.com/huggingface/skills/blob/main/train_dpo_example.py) provide complete implementation patterns.

## Frequently Asked Questions

### What metrics does Trackio capture automatically?

Trackio automatically logs **loss**, **learning rate**, **epoch number**, **step count**, and **system metrics** (including GPU utilization) when configured with `report_to="trackio"` in TRL trainers. These values are stored in a local SQLite database and synced to your Space dashboard according to the [`logging_metrics.md`](https://github.com/huggingface/skills/blob/main/logging_metrics.md) reference implementation.

### Do I need to modify my training loop to use Trackio?

No. The integration works through TRL's callback system. You only need to call `trackio.init()` before training and `trackio.finish()` after. The trainer handles all metric capture automatically when `report_to="trackio"` is set in the configuration, as shown in [`skills/hugging-face-model-trainer/scripts/train_sft_example.py`](https://github.com/huggingface/skills/blob/main/skills/hugging-face-model-trainer/scripts/train_sft_example.py).

### Can I use Trackio with trainers other than SFTTrainer?

Yes. The `huggingface/skills` repository includes [`train_grpo_example.py`](https://github.com/huggingface/skills/blob/main/train_grpo_example.py) for GRPO trainers and [`train_dpo_example.py`](https://github.com/huggingface/skills/blob/main/train_dpo_example.py) for DPO trainers. The same `report_to="trackio"` parameter works across all TRL trainer classes, with identical initialization and finalization patterns.

### How does the SQLite storage work?

Trackio creates a local SQLite database during `trackio.init()` to store all metric values durably. This ensures no data loss if the training process crashes. The database persists until `trackio.finish()` is called, at which point it can be queried locally or synced to a Hugging Face Space using `trackio.sync` for remote access.