{"id":10306,"library":"traceml","title":"TraceML","description":"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.","status":"active","version":"1.3.0","language":"en","source_language":"en","source_url":"https://github.com/polyaxon/traceml","tags":["mlops","experiment-tracking","data-versioning","model-management","polyaxon"],"install":[{"cmd":"pip install traceml","lang":"bash","label":"Install traceml"}],"dependencies":[],"imports":[{"symbol":"run","correct":"from traceml.tracking import run"},{"symbol":"PolyaxonClient","correct":"from traceml.client import PolyaxonClient"},{"symbol":"V1ArtifactKind","correct":"from traceml.artifacts import V1ArtifactKind"}],"quickstart":{"code":"import os\nfrom traceml.tracking import run\nfrom traceml.artifacts import V1ArtifactKind\n\n# Ensure Polyaxon is configured. For remote tracking, POLYAXON_TOKEN env var must be set\n# or ~/.polyaxon/config.yaml configured. For this quickstart to run standalone\n# without a Polyaxon server, 'is_offline=True' is used.\n\n# Log a simple metric and declare a model artifact\nwith run.start(\n    project=\"quickstart-traceml\",\n    name=\"my-first-experiment\",\n    tags=[\"python\", \"demo\"],\n    is_offline=True  # Set to False to track to a Polyaxon server\n) as r:\n    print(f\"Started run with UUID: {r.uuid}\")\n    r.log_metric(\"accuracy\", 0.925)\n    r.log_param(\"learning_rate\", 0.001)\n    # Log an artifact type. The actual model file would be uploaded later.\n    r.log_outputs(model=V1ArtifactKind.MODEL)\n    print(\"Logged metric, param, and model artifact kind.\")\nprint(\"Run finished.\")\n","lang":"python","description":"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`."},"warnings":[{"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.","message":"Tracking data not appearing in the Polyaxon UI or being incomplete.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Confusion between `traceml.tracking.run` and `traceml.client.PolyaxonClient` for experiment tracking.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Issues with authentication or connecting to the Polyaxon backend.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"`pip install traceml`","cause":"The `traceml` library is not installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'traceml'"},{"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.","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.","error":"polyaxon.exceptions.PolyaxonClientException: Unauthorized. Invalid token or credentials."},{"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.","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.","error":"requests.exceptions.ConnectionError: ('Connection refused', ...)"}]}