FAQ
Answers to common questions about TraceLLM.
General Questions
What is TraceLLM?
TraceLLM is an open-source, local-first observability platform for LLMs and AI agents. It captures every step of every execution — prompts, responses, tool calls, latency, token usage, and errors — so you can debug, replay, and analyze your AI workflows.
Is TraceLLM free?
Yes. TraceLLM is fully open-source under the MIT license. There are no paid tiers, no cloud lock-in, and no usage limits. You run it entirely on your own infrastructure.
Does TraceLLM send my data anywhere?
No. By default, all trace data is stored locally in your MongoDB instance. No data leaves your machine unless you choose to export it manually.
Installation & Setup
What are the system requirements?
Python 3.10 or later, MongoDB 6.0 or later, and pip. TraceLLM works on Linux, macOS, and Windows (via WSL2).
Do I need a GPU?
No. TraceLLM is an observability platform — it does not run LLMs itself. It records and visualizes calls made to external LLM providers or local models. No GPU required.
Can I use MongoDB Atlas?
Yes. Set MONGO_URL to your Atlas connection string. Works with any MongoDB-compatible service.
Tracing & Instrumentation
What can I trace?
Any Python function can be traced with the @trace decorator. The OpenAI and LangChain integrations automatically trace LLM calls, tool executions, and chain operations without manual instrumentation.
Can I trace async functions?
Yes. The @trace decorator detects async def functions automatically and uses an async wrapper that preserves the event loop context.
What is the difference between @trace and @trace_tool?
@trace creates a top-level trace document with its own trace ID, latency, and metadata. @trace_tool records individual steps and attaches them to the nearest parent @trace context. Use @trace for orchestration functions and @trace_tool for individual tool calls.
Dashboard & CLI
The dashboard shows no traces. What should I check?
Ensure (1) the backend is running (tracellm start), (2) MongoDB is accessible, and (3) you have actually created traces. Run tracellm trace "test" to generate one.
Can I use TraceLLM without the dashboard?
Yes. The CLI supports trace, replay, monitor, and export commands — all fully functional without the web dashboard. The dashboard is optional.
How do I export trace data?
Use tracellm export --format json or tracellm export --format csv. Exported files are written to the ./exports/ directory.
Performance & Reliability
Does tracing add latency to my application?
The overhead is minimal (sub-millisecond for the decorator itself). MongoDB persistence and WebSocket broadcast happen asynchronously and do not block the instrumented function.
What happens if MongoDB is down?
The instrumented function runs normally. The trace is finalized in memory but not persisted. A yellow "Trace persistence skipped" warning is logged. Once MongoDB is back, previously skipped traces are not retroactively saved.
How many traces can TraceLLM handle?
The limit is effectively your MongoDB capacity. The API defaults to returning 50 traces per request (configurable up to 200). Analytics processes up to 5000 documents. For larger workloads, filter by project or time range.