Docs

Send traces from your agents using an API key, then observe and debug runs as an interactive timeline graph.

Quickstart

Sign up at /signup and log in at /login.
Create an ingest API key at /api-keys (shown once).
Instrument your agent via the Python SDK (recommended) or send traces via the HTTP API.
Open /app to view traces (user-scoped).

Security: never commit API keys to git. Put them in env vars (e.g., DEBUGGER_API_KEY).

Integration levels

The ingest endpoint supports two payload formats: events (new, SDK) and steps (legacy/manual).

Python SDK

Wrap your agent code with trace_agent(). SDK sends raw events; backend builds steps + metrics.

View SDK quickstart →

HTTP API (events)

Send raw events from any language. Backend classifies LLM/tool steps and computes latency/tokens when possible.

View HTTP ingest →

HTTP API (legacy steps)

Send fully-formed steps with parentId links. UI renders what you send.

View steps payload →

Python SDK

The SDK is designed to be “dumb and fast”: it collects raw HTTP/function events and the backend converts them into steps.

Install

cd python_sdk
pip install -e .

Use

import os
from universal_debugger import trace_agent

os.environ["DEBUGGER_API_KEY"] = "aadb_your_api_key_here"
# Optional if you run your own deployment:
# os.environ["DEBUGGER_BASE_URL"] = "https://www.tracelensapp.com"

with trace_agent("my-agent"):
    run_my_agent()

Optional: mark tools

from universal_debugger import trace_tool

@trace_tool("search_kb")
def search_kb(query: str) -> str:
    ...

HTTP API · POST /api/traces

Send an ingest request with x-api-key. Provide either events or steps.

Headers

POST /api/traces
x-api-key: aadb_...
Content-Type: application/json

Response

HTTP/1.1 201 Created
{ "id": "cm..." }

Events payload (recommended)

{
  "trace": { "appName": "my-agent", "status": "success" },
  "events": [
    {
      "id": "evt_1",
      "type": "http",
      "method": "POST",
      "url": "https://api.openai.com/v1/chat/completions",
      "request_body": { "model": "gpt-5.1", "messages": [/* ... */] },
      "response_status": 200,
      "response_body": { "usage": { "total_tokens": 120 } },
      "started_at": "2025-12-01T10:00:00.000Z",
      "ended_at": "2025-12-01T10:00:01.000Z"
    }
  ]
}

Legacy steps payload

If you already have steps (with parent-child links), you can send them directly:

{
  "trace": { "appName": "my-agent", "status": "success" },
  "steps": [
    {
      "id": "step_1",
      "type": "llm",
      "name": "Plan",
      "parentId": null,
      "startedAt": "2025-12-01T10:00:00.000Z",
      "endedAt": "2025-12-01T10:00:01.000Z",
      "inputPreview": "User: ...",
      "outputPreview": "Plan: ...",
      "metadata": { "model": "gpt-5.1", "tokens": 120 }
    }
  ]
}

Troubleshooting

401/403 ingest → check x-api-key is active and copied correctly from /api-keys.
400 → your payload must include either non-empty events or steps.
UI shows no traces → confirm ingest returns an id, then log in and refresh /app.
429 → rate limit or monthly free-tier cap.