Documentation Index
Fetch the complete documentation index at: https://docs.tracectrl.ai/llms.txt
Use this file to discover all available pages before exploring further.
Prerequisites
- Docker and Docker Compose v2
- Python 3.10+ for the SDK in your agent
- Node.js 20+ only if developing the dashboard
Clone the repository
git clone https://github.com/tracectrl/tracectrl.git
cd tracectrl
Choose your setup method
CLI Wizard (Recommended)
Manual Setup
Development Mode
The CLI wizard walks you through configuration, writes your .env file, and launches the stack.pip install tracectrl
tracectrl setup
pip install textual rich
python setup/tui.py
cp .env.example .env
docker compose up -d
Hot reload for engine and UI:docker compose -f docker-compose.yml -f docker-compose.dev.yml up
# Or use the Makefile shortcut
make dev
Verify the stack is running
You should see:TraceCtrl Doctor
[OK] Engine API (http://localhost:8000/api/v1/health)
[OK] Dashboard UI (http://localhost:3000)
[OK] OTel Collector (HTTP) (http://localhost:4318/v1/traces)
All services are running.
docker compose ps
curl http://localhost:8000/api/v1/health
Services & Ports
| Service | Port | Purpose |
|---|
| ClickHouse | 9000 (native), 8123 (HTTP) | Span storage, agent inventory, topology |
| OTel Collector | 4317 (gRPC), 4318 (HTTP) | Receives spans from SDK |
| TraceCtrl Engine | 8000 | REST API, pipeline scheduler |
| TraceCtrl Dashboard | 3000 | Topology graph, session explorer |
Instrument Your Agent
Install the SDK
pip install tracectrl tracectrl-instrumentation-strands
pip install -e ./sdk/tracectrl-instrumentation-langchain
Add a few lines before your agent code
import tracectrl
tracectrl.configure(
service_name="my-agent-service",
endpoint="http://localhost:4317",
)
tracectrl.tag_agent(name="my-agent", role="primary")
from tracectrl.instrumentation.strands import StrandsInstrumentor
StrandsInstrumentor().instrument()
These lines must come before any framework imports to ensure all modules are patched.
Tag your agent. tracectrl.tag_agent(...) attaches identity attributes
(tracectrl.agent.id, tracectrl.agent.name, tracectrl.agent.role) to
every span emitted from this process. Without it, the engine cannot group
spans into the agent inventory or score per-agent risk. For multi-agent
processes, use tag_agents({...}) and call tag_agent inside each agent’s
execution scope.
Run your agent normally
from strands import Agent
from strands.models import BedrockModel
agent = Agent(model=BedrockModel(model_id="anthropic.claude-3-5-sonnet"))
agent("Summarize my latest emails")
Verify Data Flow
After running your agent, wait ~60 seconds for the pipeline to process, then:
Check spans in ClickHouse
docker exec -it $(docker compose ps -q clickhouse) clickhouse-client \
--query "SELECT
SpanAttributes['tracectrl.agent.id'] AS agent_id,
SpanAttributes['tracectrl.agent.name'] AS agent_name,
SpanAttributes['tracectrl.tool.category'] AS tool_category,
SpanName
FROM tracectrl.otel_traces
WHERE SpanAttributes['tracectrl.agent.id'] != ''
LIMIT 20
FORMAT Pretty"
Check the agent inventory
docker exec -it $(docker compose ps -q clickhouse) clickhouse-client \
--query "SELECT agent_id, name, framework, model, tools_observed, maturity
FROM tracectrl.agent_inventory FINAL
FORMAT Pretty"
Query the Engine API
# Full topology graph
curl http://localhost:8000/api/v1/topology/graph | python -m json.tool
# Agent inventory
curl http://localhost:8000/api/v1/risk/agents | python -m json.tool
View the Dashboard
Open http://localhost:3000 in your browser.
- Topology — Interactive graph showing agents, tools, and their connections
- Sessions — Trace explorer with full span trees and waterfall timelines
The pipeline runs every 60 seconds by default. If you don’t see data immediately, wait for the next pipeline cycle and check docker compose logs tracectrl-engine.
