trackio/pr_708/en/track.md

Track

Introduction

Trackio helps you organize your experiments within a project. A project is a collection of runs, where each run represents a single execution of your code with a specific set of parameters and results.

Initialization

To start tracking an experiment with Trackio, you first need to initialize a project with the init() function:

import trackio

trackio.init(project="my_project")

• If the project already exists, it will be loaded.
• If not, Trackio will create a new one.

In both cases, a new run is started automatically, ready for you to log data.

Naming your run

It's a good idea to give each run a meaningful name for easier organization and later reference. You can set a name using the name parameter:

trackio.init(project="my_project", name="my_first_run")

If no name is provided, Trackio generates a default one.

Grouping runs

You can organize related runs into groups using the group parameter. This is particularly useful when you're running multiple experiments with different configurations but want to compare them together:

# Group runs by experiment type
trackio.init(project="my_project", name="baseline_run_1", group="baseline")
trackio.init(project="my_project", name="augmented_run_1", group="augmented")
trackio.init(project="my_project", name="tuned_run_1", group="tuned")

Runs with the same group name can be grouped together in sidebar, making it easier to compare related experiments. You can also group runs by any other configuration parameter (see Tracking Configuration below).

Remote logging (Hugging Face Space or self-hosted server)

By default, metrics are stored locally and you open the dashboard on your machine. You can instead send metrics to:

• A Hugging Face Space, by passing space_id (or setting TRACKIO_SPACE_ID). Trackio can create or reuse the Space and sync data there.
• A self-hosted Trackio server (HTTP or HTTPS), by passing server_url (or setting TRACKIO_SERVER_URL). Use the write-access URL from trackio.show() (optionally with write_token in the query), or a base URL plus TRACKIO_WRITE_TOKEN. The client authenticates with the same write token the dashboard uses (not your Hugging Face token).

If both a Space and a self-hosted URL are configured (space_id / TRACKIO_SPACE_ID together with server_url / TRACKIO_SERVER_URL), the Space takes precedence and the self-hosted URL is ignored. Options such as dataset_id (deprecated; use bucket_id instead) and bucket_id apply to Hugging Face deployments; when only server_url is in effect, configure storage on the host that runs the server (see Environment Variables).

For setup steps (running trackio show, binding to 0.0.0.0, write tokens), see Self-host the Server.

The built-in dashboard polls for new runs and metrics every 1 second on localhost and every 2 seconds when opened on a Hugging Face Space (*.hf.space), to ease rate limits on the Space URL.

Logging Data

Once your run is initialized, you can start logging data using the log() function:

trackio.log({"loss": 0.05})

Trackio is written defensively so Trackio-side failures should never take down your main experiment code. Under normal usage, issues inside Trackio's logging, flushing, or delivery paths degrade to warnings and local buffering rather than exceptions from your training loop.

Each call to log() automatically increments the step counter. If you want to log multiple metrics at once, pass them together:

trackio.log({
    "loss": 0.05,
    "accuracy": 0.95,
})

Logging tables

You can log tabular data using the Table class. This is useful for tracking results like predictions, or any structured data. Tables can include image columns using the Image class.

import pandas as pd

df = pd.DataFrame(
    {
        "prompt": ["Trackio", "Logging is"],
        "completion": ["is great!", "easy and fun!"],
        "reward": [0.123, 0.456],
    }
)
trackio.log(
    {
        ...
        "texts": trackio.Table(dataframe=df),
    }
)