Skip to main content
Documentation
Documentation

Direct tracking

Log runs directly with the tracking client.

The tracking client is the lowest-level way to get a run to show up on the Hub. Create a client, pick a project, and open a with block — anything inside it is a tracked run.

If you prefer to wrap a whole function instead of a block, see Decorator tracking — it also gives you a hand with device management, keeping outputs organized, and automatic run lineage.

Prerequisites

Before following this guide, make sure you have completed the setup guide to:

  • Create an Embedl Hub account
  • Install the embedl-hub Python library
  • Configure an API key

Creating a client

Import Client, construct it, and pick a project. If the project does not exist yet, it is created automatically.

from embedl_hub.tracking import Client
client = Client()
client.set_project("my-project")

Opening a run

client.start_run(type) returns a context manager. Everything inside the with block is scoped to that run — the run is marked finished when the block exits, or failed if an exception propagates out.

with client.start_run("train"):
    train_model()

The type argument categorizes the run on the Hub. Use a built-in type from RunType for common categories:

from embedl_hub.tracking import RunType
with client.start_run(RunType.COMPILE):
    ...

Or use a custom string for anything domain-specific:

with client.start_run("evaluate"):
    ...

You can also pass name=... to override the display name on the Hub.

Logging data

Inside the with block, use the client to record parameters, metrics, and artifacts:

from pathlib import Path
with client.start_run("train"):
    client.log_param("learning_rate", "0.001")
    client.log_metric("accuracy", 0.923)
    client.log_metric("val_loss", 0.081, step=10)
    client.log_artifact(Path("outputs/model.onnx"))

All logged data appears on the Hub run page alongside the run’s status and duration.

Chaining runs

Pass parent_run_id=... to link a run to a previous one. The parent run appears as the predecessor in the Hub’s lineage view.

with client.start_run("prep") as prep:
    ...
with client.start_run("train", parent_run_id=prep.id):
    ...

When to reach for the decorator

Direct tracking is the minimum viable path — great when you just want a run to show up for an existing block of code. If you also want:

  • A run-scoped local artifact directory to write outputs into — for clear organization and traceability
  • Automatic connection to remote devices over SSH, with per-device artifact directories
  • Automatic lineage when passing results between functions

…then use the decorator instead. It wraps the client with a HubContext that handles all of the above.

Complete example

from pathlib import Path
from embedl_hub.tracking import Client
client = Client()
client.set_project("my-project")
with client.start_run("prep") as prep:
    client.log_param("source", "data/raw.csv")
    clean_data("data/raw.csv", "data/clean.csv")
with client.start_run("train", parent_run_id=prep.id):
    accuracy = train_model("data/clean.csv")
    client.log_metric("accuracy", accuracy)
    client.log_artifact(Path("outputs/model.onnx"))

Both runs show up on the Hub, linked as a lineage chain.