Quickstart

From zero to ingesting events in under 2 minutes.

1. Install

Build from source:

$ git clone https://github.com/bravo1goingdark/keplor.git
$ cd keplor
$ cargo build --release --features keplor-cli/mimalloc
$ cp target/release/keplor /usr/local/bin/

Add --features keplor-server/simd-json for the AVX-accelerated JSON parser, or RUSTFLAGS="-C target-cpu=native" to autovectorize for the host CPU. See build-time perf knobs.

2. Start the server

$ keplor run

Binds to 0.0.0.0:8080 and creates ./keplor_data/ — the KeplorDB data directory with one segment tree per retention tier. No config needed.

Verify:

$ curl http://localhost:8080/health
{"status":"ok","version":"0.1.0","db":"connected","queue_depth":0,"queue_capacity":32768,"queue_utilization_pct":0}

3. Send your first event

$ curl -X POST http://localhost:8080/v1/events \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "provider": "openai",
    "usage": {"input_tokens": 500, "output_tokens": 200},
    "latency": {"total_ms": 1200, "ttft_ms": 180},
    "user_id": "alice",
    "source": "my-app"
  }'

Response (201 Created):

{
  "id": "01J5XQKR...",
  "cost_nanodollars": 6250000,
  "model": "gpt-4o",
  "provider": "openai"
}

Cost is auto-computed. 6250000 nanodollars = $0.00625.

For hot-path traffic that doesn’t need per-event flush confirmation, append ?durable=false — the request returns 202 Accepted immediately, p50 drops from ~5 ms to ~1.5 ms.

4. Query it back

$ curl "http://localhost:8080/v1/events?user_id=alice&limit=5"

Or from the CLI:

$ keplor query --user-id alice
ID                           PROVIDER       MODEL                   TOKENS       COST ($)
--------------------------------------------------------------------------------------------
01J5XQKR...                  openai         gpt-4o                     700     0.00625000

1 event(s)

5. Check stats

$ keplor stats --data-dir ./keplor_data
=== Keplor Storage Statistics ===
Data dir:             ./keplor_data
Total events:         1
Total bytes on disk:  47.3 KB
Tiers:                free, pro, team

Next steps

Integration Guide — Python, Node.js, LiteLLM, S3/R2 setup, tiered retention.
API Reference — full endpoint docs.
Configuration — auth, archival, retention tiers, tuning.
CLI Reference — all commands.