Configuration

configure()

The entry point for all of Kostrack. Call once at application startup before making any LLM API calls.

Signature

import kostrack

kostrack.configure(
    dsn: str | None = None,
    service_id: str = "default",
    flush_interval: float = 5.0,
    max_batch_size: int = 100,
    sqlite_path: Path | None = None,
    fail_open: bool = True,
    log_level: str = "WARNING",
)

Parameters

Parameter	Type	Default	Description
`dsn`	str	None	PostgreSQL DSN. Falls back to `KOSTRACK_DSN` env var if not passed.
`service_id`	str	"default"	Identifies this service in `writer_health` and Grafana queries. Use your app name.
`flush_interval`	float	5.0	Seconds between write batches. Lower = more frequent writes, higher DB load.
`max_batch_size`	int	100	Maximum rows per TimescaleDB insert.
`sqlite_path`	Path	None	Override default SQLite buffer location (`~/.kostrack/buffer.db`).
`fail_open`	bool	True	If True, all write errors are swallowed silently. If False, raises after SQLite also fails.
`log_level`	str	"WARNING"	Log level for all `kostrack.*` loggers. Set to `"DEBUG"` during development.

health()

Returns the current state of the async writer — useful for monitoring endpoints:

kostrack.health()
# {
#   "status": "ok",
#   "timescale_available": True,
#   "sqlite_backlog": 0,
#   "queue_depth": 0,
#   "written_timescale": 1247,
#   "written_sqlite": 0,
#   "failed": 0,
#   "last_flush": "2026-03-20T08:00:01Z"
# }

shutdown()

Flushes the remaining in-memory queue before the process exits. Call in your shutdown handler:

kostrack.shutdown(timeout=10.0)

Important

If you don't call shutdown(), any records still in the in-memory queue at process exit will be lost. Records already flushed to SQLite are safe.

← Previous

Quick Start

Environment Vars