Documentation

First Trace

Create and inspect your first TraceLLM execution record.

First Trace

This walkthrough creates your first trace, explains what happens at each internal stage, and shows you how to inspect and replay the result.

Tracey Guide

I'll walk you through creating your first trace step by step. Follow along in your terminal — it only takes a minute.

Run Your First Trace

Make sure TraceLLM is installed and the stack is running, then execute:

terminalCopy

bash

tracellm trace "Explain transformers"

TraceLLM sends the prompt to your configured LLM provider, captures the response, and records the full execution as a trace. The terminal output shows:

Example outputCopy

text

Trace ID:     tr_2kf9q3m1
Model:        gpt-4o
Latency:      1.24s
Prompt Tokens:  12
Completion Tokens: 184
Status:       success

A transformer is a neural network architecture...

What Happens Internally

Each trace passes through seven distinct stages. Understanding these stages helps you debug issues and interpret the data in the dashboard.

Request Created

The CLI constructs a request using your prompt and the default model configuration. It selects the LLM provider based on environment variables or the local config file.

Trace Generated

A trace object is created with a unique ID (tr_ prefix), a timestamp, and metadata including the model name, provider, and prompt length.

Metrics Captured

As the LLM call executes, TraceLLM records latency, token usage (prompt and completion), and estimated cost. These metrics power the analytics dashboard.

Stored in MongoDB

The complete trace document — including spans, events, and all metadata — is persisted to the traces collection in MongoDB. This enables historical querying and replay.

WebSocket Event Emitted

A real-time event is pushed to all connected WebSocket clients. The dashboard listens on this channel and updates without needing to poll.

Dashboard Updated

The dashboard receives the event and renders the trace in the trace list. Clicking the trace opens the inspector with the full execution graph.

Replay Available

Once stored, the trace is immediately replayable via tracellm replay <id>. Replay re-executes the trace using captured inputs and preserves the original spans.

Inspect in the Dashboard

Open http://localhost:3000 and find your trace in the list. Click it to see:

Trace inspector screenshot placeholder

The full prompt and model response
A waterfall view of every span and its duration
Token usage broken down per call
Any errors or retries that occurred

Next Steps

Instrument your code

Use the @trace decorator to automatically trace Python functions.

Integrate with OpenAI

Trace OpenAI requests with zero-config SDK integration.

Explore the dashboard

Browse traces, analytics, and live logs in the web UI.

Export trace data

Export traces as JSON for sharing or offline analysis.