TraceML

1.3.0 · active · verified Fri Apr 17

TraceML is the client-side engine for ML/Data tracking, visualization, dashboards, and model UI, designed specifically for integration with the Polyaxon MLOps platform. It allows users to log metrics, parameters, artifacts, and manage experiment runs programmatically. The current version is 1.3.0, and it maintains a relatively frequent release cadence, often aligning with Polyaxon platform updates.

Common errors

```
ModuleNotFoundError: No module named 'traceml'
```
cause The `traceml` library is not installed in the current Python environment.

fix `pip install traceml`
```
polyaxon.exceptions.PolyaxonClientException: Unauthorized. Invalid token or credentials.
```
cause The client is unable to authenticate with the Polyaxon API. This is usually due to a missing, expired, or incorrect authentication token or improperly configured Polyaxon CLI.

fix Set the `POLYAXON_TOKEN` environment variable with a valid API token or configure your Polyaxon CLI (`polyaxon login`) and ensure it's accessible by the `traceml` client.
```
requests.exceptions.ConnectionError: ('Connection refused', ...)
```
cause The `traceml` client cannot reach the Polyaxon API server. This could be due to the server being down, an incorrect host configuration, or network issues preventing access.

fix Verify that your Polyaxon server is running and accessible from your machine. Check the `POLYAXON_HOST` environment variable or your Polyaxon CLI configuration (`polyaxon config show`) to ensure the correct host and port are used.

Warnings

gotcha Tracking data not appearing in the Polyaxon UI or being incomplete.
Fix: Ensure the `run.start()` context manager is used for automatic run finalization and artifact uploading. Verify Polyaxon server is running and accessible if tracking remotely. If `is_offline=True` is used, data is stored locally and will not appear in the Polyaxon UI. Check `polyaxon config show` for current client configuration.
gotcha Confusion between `traceml.tracking.run` and `traceml.client.PolyaxonClient` for experiment tracking.
Fix: `traceml.tracking.run` provides a higher-level, context-managed interface ideal for logging metrics, parameters, and artifacts within an experiment. Use `PolyaxonClient` for lower-level API interactions like managing projects, models, or users directly. For most experiment tracking tasks, `run` is the preferred entry point.
gotcha Issues with authentication or connecting to the Polyaxon backend.
Fix: Ensure the `POLYAXON_TOKEN` environment variable is set with a valid API token or `~/.polyaxon/config.yaml` is correctly configured with valid credentials and a reachable host. Verify network connectivity to the Polyaxon API endpoint.

Install

pip install traceml Install traceml

Imports

run
```
from traceml.tracking import run
```

PolyaxonClient

from traceml.client import PolyaxonClient

V1ArtifactKind

from traceml.artifacts import V1ArtifactKind

Quickstart

Demonstrates how to initialize a TraceML run, log a metric, a parameter, and declare an artifact kind. By default, it runs in offline mode for local execution without a Polyaxon server. To track to a remote Polyaxon instance, ensure authentication is configured (e.g., via `POLYAXON_TOKEN` environment variable) and set `is_offline=False`.

import os
from traceml.tracking import run
from traceml.artifacts import V1ArtifactKind

# Ensure Polyaxon is configured. For remote tracking, POLYAXON_TOKEN env var must be set
# or ~/.polyaxon/config.yaml configured. For this quickstart to run standalone
# without a Polyaxon server, 'is_offline=True' is used.

# Log a simple metric and declare a model artifact
with run.start(
    project="quickstart-traceml",
    name="my-first-experiment",
    tags=["python", "demo"],
    is_offline=True  # Set to False to track to a Polyaxon server
) as r:
    print(f"Started run with UUID: {r.uuid}")
    r.log_metric("accuracy", 0.925)
    r.log_param("learning_rate", 0.001)
    # Log an artifact type. The actual model file would be uploaded later.
    r.log_outputs(model=V1ArtifactKind.MODEL)
    print("Logged metric, param, and model artifact kind.")
print("Run finished.")

view raw JSON →