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

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. Here is the minimal code required to enable real-time tracking:

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:

# 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 demonstrates Trackio with GRPO trainers, while 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, train_grpo_example.py, and 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 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.

Can I use Trackio with trainers other than SFTTrainer?

Yes. The huggingface/skills repository includes train_grpo_example.py for GRPO trainers and 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}