Quickstart

Prerequisites

Docker and Docker Compose v2
Python 3.10+ for the SDK in your agent
Node.js 20+ only if developing the dashboard

Start the Platform

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

Or from source:

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

In dev mode, the engine auto-reloads on Python changes (port 8000) and the UI runs Vite dev server with HMR (port 5173).

Verify the stack is running

tracectrl doctor

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.

Or manually:

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

For frameworks not yet on PyPI (LangChain, CrewAI, Google ADK), install from the repo:

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")

Every LLM call, tool invocation, and chain execution is now captured as OpenTelemetry spans enriched with TraceCtrl security attributes.

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.

Getting Started

SDK

Framework Instrumentors

Security

Platform

Prerequisites

Start the Platform

Services & Ports

Instrument Your Agent

Verify Data Flow

Check spans in ClickHouse

Check the agent inventory

Query the Engine API

View the Dashboard

​Prerequisites

​Start the Platform

​Services & Ports

​Instrument Your Agent

​Verify Data Flow

​Check spans in ClickHouse

​Check the agent inventory

​Query the Engine API

​View the Dashboard

Prerequisites

Start the Platform

Services & Ports

Instrument Your Agent

Verify Data Flow

Check spans in ClickHouse

Check the agent inventory

Query the Engine API

View the Dashboard