← Back to Documentation

5-Minute Quickstart

Get Kalibr running locally and view your first traced LLM call in under five minutes.

Note: This guide assumes a local Docker environment. For production deployment, see System Overview.

Prerequisites

  • Python 3.10+ (python --version)
  • Docker Desktop or Docker + Docker Compose
  • OpenAI API key — Get one here

Step 1 — Start Kalibr

git clone https://github.com/kalibr-ai/kalibr.git
cd kalibr
docker compose up -d

This launches:

Service Port Purpose
ClickHouse 9000 Trace + cost analytics
MongoDB 27017 Metadata store
Backend API 8001 FastAPI REST API
Dashboard 3000 React UI
OTel Bridge background Syncs spans → ClickHouse

Verify health:

curl http://localhost:8001/api/health
# {"status":"ok","clickhouse":"connected","mongodb":"connected"}

Step 2 — Install the SDK

For most users:

pip install kalibr

For local development:

pip install -e sdk/python

Confirm:

python -c "import kalibr; print(kalibr.__version__)"

Step 3 — Trace Your First LLM Call

Create example.py:

import os, kalibr
from openai import OpenAI

os.environ["OPENAI_API_KEY"] = "sk-..."

client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Say hello in 5 words"}]
)

print("Response:", response.choices[0].message.content)
print("Trace ID:", kalibr.get_trace_id())

Run:

python example.py

Expected:

Response: Hello, how can I help?
Trace ID: dd88823c-745d-4ea1-bd17-0f8437f1b478

Step 4 — View Your Trace

Option A — Dashboard (Recommended)

Visit http://localhost:3000

  • Spans Viewer: all spans by service/model
  • Cost Dashboard: cost breakdown by provider
  • Performance: latency histograms
  • Provider Comparison: per-vendor metrics

Option B — API

curl http://localhost:8001/api/otel/spans | jq .

Option C — JSONL (Local)

cat /tmp/kalibr_otel_spans.jsonl | jq .

Option D — ClickHouse Query

docker exec -it kalibr-clickhouse clickhouse-client
SELECT trace_id, provider, model_name, cost_usd, duration_ms
FROM kalibr.traces
ORDER BY timestamp DESC
LIMIT 5;

Step 5 — Understand What Happened

  1. SDK import activates auto-instrumentation.
  2. LLM call creates a span with model + cost data.
  3. OTel Bridge syncs spans to ClickHouse.
  4. Dashboard/API visualize trace and cost metrics.

Troubleshooting

No spans?

  • Check /tmp/kalibr_otel_spans.jsonl
  • docker ps | grep otel-bridge
  • curl http://localhost:8123/ping

Import error:

cd sdk/python && pip install -e .

Permissions:

sudo chmod 666 /tmp/kalibr_otel_spans.jsonl

Docker issues:

docker compose logs backend
docker compose down && docker compose up -d
← Documentation Index SDK Integration →