Getting Started

Getting Started

Full version: Quickstart on the docs site.

1. Run Tracely

Everything in Docker, pre-populated (the fastest way to see the whole product):

git clone https://github.com/Jwuthri/Tracely && cd Tracely
docker compose --profile demo up -d --build --wait
open http://localhost:3001

This starts ClickHouse, Postgres, Redis, MinIO, the API (:8000), the Celery worker and the UI (:3001), runs every migration, seeds the default project + ingest key tracely_dev_key, and fills the workspace with traces, clusters, cases and gate runs.

docker compose down stops it (-v wipes data). Remap ports with TRACELY_WEB_PORT / TRACELY_BACKEND_PORT.

Don't want to host anything? Use the hosted cloud at tracely-studio.xyz (API: https://api.tracely-studio.xyz), or one-click deploy on Railway — see Self Hosting.

2. Send your first trace

pip install "tracely-ai[openai]"     # or [anthropic], [langchain], [all]

import tracely_sdk as tracely

tracely.init(
    endpoint="http://localhost:8000",   # the API, not the UI
    api_key="tracely_dev_key",          # an ingest key = your workspace
    service_name="support-agent",       # names the agent
    env="prod",                         # prod | staging | ci | dev — the gating axis
    instrument="auto",                  # auto-detect openai / anthropic / google / mistral / langchain
)

with tracely.trace(agent="support-agent", conversation="conv-1", user="u_42"):
    client.chat.completions.create(model="gpt-4o", messages=[...])

tracely.flush()   # scripts / Lambdas / tests: don't lose the last spans

Any OTLP/HTTP exporter works too: POST {endpoint}/v1/traces with Authorization: Bearer <key>. Tracely reads standard gen_ai.* / OpenInference attributes plus the tracely.* hints (tracely.agent.id, tracely.conversation.id, tracely.env, …). Non-Python services are covered on the docs site under Custom spans.

The six things that silently break a workspace

1. Declare the agent name (service_name= / agent=). Framework attributes like gen_ai.agent.name are ignored on purpose; name nothing and everything lands under default.
2. Pass the same conversation= to every turn. Without it a 12-turn thread is 12 unrelated rows.
3. env is the gating axis. prod failures become cases; ci traces are what the gate grades. Don't tag CI runs prod.
4. Mark errors. A tool returning {"error": …} as a successful span is invisible to detection, clustering and the gate. Use tracely.error(span, msg) or raise inside @observe.
5. flush() before exit in short-lived processes.
6. Honour traceparent if Tracely drives your agent (scenarios / simulate), or the gate only sees text in / text out.

3. Next

• Add an evaluator column on the Traces page (structural checks need no model; LLM judges need a workspace OpenRouter key in Settings) → Evaluations
• Promote a failing trace to a regression case, then wire the gate → CI Gate
• Let your coding agent do it: npx skills add https://github.com/Jwuthri/Tracely --skill tracely, or add the MCP server: claude mcp add --transport http tracely http://localhost:8000/mcp --header "Authorization: Bearer tracely_dev_key"