Documentation

tracellm start

Start the local TraceLLM runtime.

Overview

The tracellm start command boots the entire TraceLLM observability stack: the FastAPI backend server, WebSocket endpoint, and — optionally — the frontend dashboard. It is the standard way to launch a local development environment.

Syntax

terminalCopy

bash

tracellm start [OPTIONS]

Option	Type	Default	Description
--port, -p	int	8000	Port for the API server
--dashboard, -d	flag	false	Open the dashboard in your browser
--dashboard-port	int	3000	Port for the frontend dashboard

What Happens Internally

Loads environment variables from a .env file using python-dotenv.
Checks MongoDB connectivity by pinging the server at MONGO_URL. If unreachable, logs a yellow warning and continues — the API will start without persistence.
Starts the FastAPI server via a subprocess.Popen running uvicorn app.main:app on the specified port with live reload enabled.
Performs a health check by polling http://127.0.0.1:<port>/ with a 15-second timeout. The check retries every 500ms.
Opens the dashboard (if --dashboard is set) in the default browser using webbrowser.open.
Renders a status table showing API Server, MongoDB, Dashboard, and WebSocket status.
Blocks on the API process until Ctrl+C is pressed, then terminates the uvicorn process gracefully.

Example Output

Terminal outputCopy

text

  ╭─── TraceLLM ───────────────────────────────────────────────╮
  │                                                          │
  │   ████████╗██████╗  █████╗  ██████╗███████╗             │
  │   ╚══██╔══╝██╔══██╗██╔══██╗██╔════╝██╔════╝             │
  │      ██║   ██████╔╝███████║██║     █████╗               │
  │      ██║   ██╔══██╗██╔══██║██║     ██╔══╝               │
  │      ██║   ██║  ██║██║  ██║╚██████╗███████╗             │
  │      ╚═╝   ╚═╝  ╚═╝╚═╝  ╚═╝ ╚═════╝╚══════╝             │
  │                                                          │
  │   LLM Observability Platform                             │
  ╰──────────────────────────────────────────────────────────╯

  TraceLLM starting...

  ✓ MongoDB connected
  ✓ API ready
  ✓ WebSocket ready

  ╭── TraceLLM Stack ────────────────────────────────────────╮
  │                                                          │
  │  API Server   ● http://127.0.0.1:8000                    │
  │  MongoDB      ● Connected                                │
  │  Dashboard    ● http://localhost:3000                     │
  │  WebSocket    ws://127.0.0.1:8000/ws                     │
  │                                                          │
  ╰──────────────────────────────────────────────────────────╯

Environment Variables

Variable	Required	Description
MONGO_URL	No (warning if missing)	MongoDB connection string for trace persistence

Warning

Without MONGO_URL, the API starts but traces are not persisted. Set it to a valid MongoDB URI before running traces.

Common Errors

Error	Cause	Fix
Port already in use	Another process is using the port	Use --port to specify a different port
MongoDB not reachable	MongoDB is not running or MONGO_URL is wrong	Start MongoDB or check your MONGO_URL value
API failed to start	Dependency issue or port conflict	Check the uvicorn logs for the exact error

Troubleshooting

Info

If the health check times out, ensure no firewall is blocking the port and that all dependencies are installed. Run pip install tracellm[all] to ensure all extras are available.