Quickstart

Get TraceCtrl running end-to-end in 5 minutes

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

1. Clone the repository

   git clone https://github.com/cloudsineai/tracectrl.git
   cd tracectrl
   
2. Choose your setup method

   TUI Wizard (Recommended)

   The TUI wizard walks you through configuration, writes your .env file, and launches the stack.

   pip install textual rich
   python setup/tui.py
   

   Manual Setup

   cp .env.example .env
   docker compose up -d
   

   Development Mode

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

3. Verify the stack is running

   docker compose ps
   curl http://localhost:8000/api/v1/health
   

   You should see:

   {"status": "ok", "version": "0.1.0"}
   

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

1. Install the SDK

   pip install -e ./sdk/tracectrl
   pip install -e ./sdk/tracectrl-instrumentation-langchain  # or your framework
   
2. Add 3 lines before your agent code

   import tracectrl
   
   tracectrl.configure(
       service_name="my-agent-service",
       endpoint="http://localhost:4317",
   )
   
   from tracectrl.instrumentation.langchain import LangChainInstrumentor
   LangChainInstrumentor().instrument()
   

   These lines must come before any framework imports to ensure all modules are patched.

3. Run your agent normally

   from langchain_openai import ChatOpenAI
   from langchain.agents import create_openai_tools_agent, AgentExecutor
   
   llm = ChatOpenAI(model="gpt-4o")
   # ... define tools, prompt, agent
   agent_executor.invoke({"input": "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.