Quick Start

From zero to live cost data in Grafana in under five minutes. You need Docker, Python 3.11+, and at least one LLM API key.

Step 1 — Clone and configure

git clone https://github.com/bphiri/kostrack.git
cd kostrack
cp .env.example .env

Edit .env and set your passwords:

TSDB_PASSWORD=your_secure_password
GRAFANA_PASSWORD=your_grafana_password
KOSTRACK_DSN=postgresql://kostrack:your_secure_password@localhost/kostrack

Step 2 — Start the stack

docker compose up -d

This starts TimescaleDB on localhost:5432 and Grafana on localhost:3000. The database schema and all seed pricing data load automatically from init-db.sql on first run.

Verify both services are healthy:

docker compose ps

Step 3 — Install the SDK

pip install kostrack

Or install from the repo for local development:

pip install -e ./sdk

Step 4 — Instrument your app

Add three lines at startup and swap your provider import:

import kostrack

# Configure once — reads KOSTRACK_DSN env var if dsn= not passed
kostrack.configure(
    dsn="postgresql://kostrack:your_password@localhost/kostrack",
    service_id="my-app",
)

# Before: from anthropic import Anthropic
from kostrack import Anthropic

client = Anthropic(
    tags={
        "project": "my-app",
        "feature": "summariser",
        "environment": "production",
    }
)

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Summarise this..."}],
)

Step 5 — Open Grafana

Go to http://localhost:3000 and log in with admin / your GRAFANA_PASSWORD.

The Kostrack — Overview dashboard loads automatically. Make a few API calls and refresh — you'll see spend by provider, spend over time, and a live call table.

export ANTHROPIC_API_KEY=sk-ant-...
export KOSTRACK_DSN=postgresql://kostrack:password@localhost/kostrack

cd sdk
python tests/integration_test.py

Next steps