Documentation

tracellm trace

Trace prompts, tool calls, retries, and model responses.

Overview

The tracellm trace command sends a prompt to your configured LLM provider and captures the full execution as a trace. It simulates a production RAG + agent workflow — embedding, vector search, reranking, planning, tool chaining, and generation — and records every span with timing and metadata.

Syntax

terminalCopy

bash

tracellm trace [OPTIONS] PROMPT

Argument	Type	Required	Description
PROMPT	string	Yes	The prompt text to trace (positional)

Option	Type	Default	Description
--model	str	gpt-4.1-mini	Model name label for the trace
--project	str	default	Project identifier or display name
--environment	str	development	Environment label
--api-key	str	None	TraceLLM API key for project resolution

What Happens Internally

Context resolution — If --api-key is provided, the project ID, name, and environment are looked up from MongoDB. Otherwise the provided flags are used directly.
Event stream starts — A rich live trace stream displays timestamped events as they occur: query embedding, vector search, context reranking, agent planning, context allocation, tool chaining, and LLM generation.
Simulation runs — The internal simulation executes a multi-step agentic workflow with random delays, retries, and embedding dimensions to produce realistic trace data.
Trace finalized — Latency, token counts, status, and all step data are assembled into a trace payload.
Persistence — The trace is saved to MongoDB via save_trace_payload.
Summary rendered — A trace report card is printed showing model, latency, tokens, retries, status, timestamp, and trace ID.

Example Output

Terminal outputCopy

text

  Tracing request...

  query.embed        Embedding prompt
  vector.search      Searching vector index
  context.rerank     Reranking context
  agent.plan         Planning tool execution
  context.allocate   Allocating context window
  tool.chain         Running tool chain
  llm.generate       Generating answer

  ╭── Trace Summary ─────────────────────────────────────────╮
  │                                                          │
  │  Model       gpt-4.1-mini                                │
  │  Latency     3,420 ms                                    │
  │  Tokens      1,247                                       │
  │  Retries     1                                           │
  │  Status      SUCCESS                                     │
  │  Timestamp   2026-05-31T14:22:10Z                        │
  │  Trace ID    tr_2kf9q3m1                                 │
  │                                                          │
  ╰──────────────────────────────────────────────────────────╯

  Trace complete

Common Errors

Error	Cause	Fix
Prompt is required	No prompt argument provided	Add a prompt string: tracellm trace "your prompt"
Trace persistence failed	MongoDB is unavailable	Start MongoDB or check your MONGO_URL
Simulation error	Internal trace step failed	Check the error output — it is captured in the trace

Troubleshooting

Warning

The trace command simulates an LLM workflow end-to-end, including random retries. If you see a yellow warning about retries, this is expected behavior — the workflow automatically retries failed tool calls.