litellm-pulse 0.2.0__py3-none-any.whl

litellm_pulse/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

litellm_pulse/app.py

@@ -0,0 +1,389 @@
+"""LiteLLM Pulse — a lightweight LiteLLM metrics exporter with SQLite time-series storage."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+from collections import deque
+from contextlib import asynccontextmanager, suppress
+from datetime import UTC, datetime, timedelta, tzinfo
+from typing import Any
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+import httpx
+import uvicorn
+from fastapi import FastAPI
+from fastapi.responses import JSONResponse
+
+from .db import (
+    METRIC_KEYS,
+    get_history,
+    get_latest,
+    get_window_aggregate,
+    open_db,
+    purge_old,
+    store_snapshot,
+)
+from .parser import parse_prometheus_text
+
+logger = logging.getLogger("litellm-pulse")
+
+# ---------------------------------------------------------------------------
+# Configuration (all env-var driven, prefixed with LITELLM_PULSE_)
+# ---------------------------------------------------------------------------
+
+METRICS_URL = os.environ.get("LITELLM_PULSE_METRICS_URL", "http://litellm:4000/metrics/")
+SCRAPE_INTERVAL = int(os.environ.get("LITELLM_PULSE_SCRAPE_INTERVAL", "60"))
+PORT = int(os.environ.get("LITELLM_PULSE_PORT", "8000"))
+HOST = os.environ.get("LITELLM_PULSE_HOST", "0.0.0.0")
+VERIFY_SSL = os.environ.get("LITELLM_PULSE_VERIFY_SSL", "false").lower() == "true"
+SCRAPE_TIMEOUT = float(os.environ.get("LITELLM_PULSE_SCRAPE_TIMEOUT", "30"))
+LOG_LEVEL = os.environ.get("LITELLM_PULSE_LOG_LEVEL", "info").upper()
+DB_PATH = os.environ.get("LITELLM_PULSE_DB_PATH", "./data/litellm_pulse.db")
+DB_RETENTION_DAYS = int(os.environ.get("LITELLM_PULSE_DB_RETENTION_DAYS", "90"))
+HISTORY_SIZE = int(os.environ.get("LITELLM_PULSE_HISTORY_SIZE", "168"))
+METRICS_API_KEY = os.environ.get("LITELLM_PULSE_METRICS_API_KEY", "")
+
+# Timezone for API output and window boundaries. DB always stores UTC.
+_TZ: tzinfo = UTC
+_tz_name = os.environ.get("LITELLM_PULSE_TIMEZONE", "UTC")
+try:
+    _TZ = ZoneInfo(_tz_name)
+except ZoneInfoNotFoundError:
+    logger.warning("Unknown timezone %r — falling back to UTC", _tz_name)
+except Exception:
+    logger.exception("Failed to load timezone %r — falling back to UTC", _tz_name)
+
+# Default metric mappings — LiteLLM Prometheus metric names.
+# Each can be overridden via env var LITELLM_PULSE_METRIC_<FRIENDLY_NAME>.
+DEFAULT_METRIC_MAP = {
+    "requests": "litellm_proxy_total_requests_metric_total",
+    "failed_requests": "litellm_proxy_failed_requests_metric_total",
+    "tokens": "litellm_total_tokens_metric_total",
+    "input_tokens": "litellm_input_tokens_metric_total",
+    "output_tokens": "litellm_output_tokens_metric_total",
+    "reasoning_tokens": "litellm_output_reasoning_tokens_metric_total",
+    "cost": "litellm_spend_metric_total",
+    "in_flight_requests": "litellm_in_flight_requests",
+}
+
+METRIC_MAP: dict[str, str] = {}
+for _friendly, _prom in DEFAULT_METRIC_MAP.items():
+    METRIC_MAP[_friendly] = os.environ.get(f"LITELLM_PULSE_METRIC_{_friendly.upper()}", _prom)
+
+# ---------------------------------------------------------------------------
+# State
+# ---------------------------------------------------------------------------
+
+_raw_metrics: dict[str, float] = {}
+_previous_raw: dict[str, float] = {}
+_last_scrape: datetime | None = None
+_last_error: str | None = None
+_history: deque[dict[str, Any]] = deque(maxlen=HISTORY_SIZE) if HISTORY_SIZE > 0 else None
+_db: Any = None  # sqlite3.Connection
+
+
+# ---------------------------------------------------------------------------
+# Reset detection & delta computation
+# ---------------------------------------------------------------------------
+
+
+def _detect_reset(prev: dict[str, float], curr: dict[str, float]) -> bool:
+    """Return True if any tracked counter appears to have reset (dropped >50%)."""
+    if not prev:
+        return False
+    for key in METRIC_MAP:
+        prom_name = METRIC_MAP[key]
+        old_val = prev.get(prom_name)
+        new_val = curr.get(prom_name)
+        if old_val is not None and new_val is not None and old_val > 0 and new_val < old_val * 0.5:
+            return True
+    return False
+
+
+def _compute_deltas(
+    prev: dict[str, float], curr: dict[str, float], is_reset: bool
+) -> dict[str, float]:
+    """Compute per-metric deltas. On reset, delta is the current value (from 0)."""
+    deltas: dict[str, float] = {}
+    for friendly, prom_name in METRIC_MAP.items():
+        curr_val = curr.get(prom_name, 0.0)
+        if is_reset:
+            deltas[friendly] = curr_val
+        else:
+            deltas[friendly] = curr_val - prev.get(prom_name, 0.0)
+    return deltas
+
+
+# ---------------------------------------------------------------------------
+# Window boundaries
+# ---------------------------------------------------------------------------
+
+
+def _format_ts(ts: int | float) -> str:
+    """Format a UTC Unix timestamp as an ISO 8601 string in the configured timezone."""
+    return datetime.fromtimestamp(ts, tz=_TZ).isoformat()
+
+
+def _start_of_day() -> int:
+    now = datetime.now(_TZ)
+    start = now.replace(hour=0, minute=0, second=0, microsecond=0)
+    return int(start.timestamp())
+
+
+def _start_of_week() -> int:
+    now = datetime.now(_TZ)
+    start_of_day = now.replace(hour=0, minute=0, second=0, microsecond=0)
+    start = start_of_day - timedelta(days=start_of_day.weekday())
+    return int(start.timestamp())
+
+
+def _start_of_month() -> int:
+    now = datetime.now(_TZ)
+    start = now.replace(day=1, hour=0, minute=0, second=0, microsecond=0)
+    return int(start.timestamp())
+
+
+# ---------------------------------------------------------------------------
+# Scraper
+# ---------------------------------------------------------------------------
+
+
+async def _scrape(client: httpx.AsyncClient) -> None:
+    global _raw_metrics, _previous_raw, _last_scrape, _last_error
+
+    try:
+        resp = await client.get(METRICS_URL, timeout=SCRAPE_TIMEOUT)
+        resp.raise_for_status()
+        _raw_metrics = parse_prometheus_text(resp.text)
+        now = datetime.now(UTC)
+        _last_scrape = now
+        _last_error = None
+
+        is_reset = _detect_reset(_previous_raw, _raw_metrics)
+        deltas = _compute_deltas(_previous_raw, _raw_metrics, is_reset)
+
+        if is_reset:
+            logger.warning("Counter reset detected — treating as fresh LiteLLM session")
+
+        if _db is not None:
+            ts = int(now.timestamp())
+            raw_by_friendly = {
+                friendly: _raw_metrics.get(prom_name, 0.0)
+                for friendly, prom_name in METRIC_MAP.items()
+            }
+            store_snapshot(_db, ts, raw_by_friendly, deltas, is_reset)
+
+        if _history is not None:
+            entry: dict[str, Any] = {
+                "ts": int(now.timestamp()),
+                "is_reset": is_reset,
+            }
+            for friendly, prom_name in METRIC_MAP.items():
+                val = _raw_metrics.get(prom_name, 0.0)
+                entry[friendly] = val
+                entry[f"{friendly}_delta"] = deltas.get(friendly, 0.0)
+            _history.append(entry)
+
+        _previous_raw = dict(_raw_metrics)
+
+        logger.debug(
+            "Scraped %s — %d metric families, reset=%s",
+            METRICS_URL,
+            len(_raw_metrics),
+            is_reset,
+        )
+
+    except Exception as exc:
+        _last_error = str(exc)
+        logger.warning("Scrape failed: %s", exc)
+
+
+def _build_auth_headers() -> dict[str, str] | None:
+    if METRICS_API_KEY and METRICS_API_KEY.strip():
+        return {"Authorization": f"Bearer {METRICS_API_KEY.strip()}"}
+    return None
+
+
+async def _scraper_loop() -> None:
+    async with httpx.AsyncClient(verify=VERIFY_SSL, headers=_build_auth_headers()) as client:
+        while True:
+            await _scrape(client)
+            await asyncio.sleep(SCRAPE_INTERVAL)
+
+
+async def _purge_loop() -> None:
+    while True:
+        await asyncio.sleep(3600)  # Run hourly
+        if _db is not None:
+            try:
+                purge_old(_db, DB_RETENTION_DAYS)
+            except Exception as exc:
+                logger.warning("Purge failed: %s", exc)
+
+
+# ---------------------------------------------------------------------------
+# FastAPI
+# ---------------------------------------------------------------------------
+
+
+@asynccontextmanager
+async def lifespan(_app: FastAPI):
+    global _db, _previous_raw
+    logging.basicConfig(
+        level=LOG_LEVEL,
+        format="%(asctime)s %(levelname)-8s %(name)s — %(message)s",
+    )
+
+    try:
+        _db = open_db(DB_PATH)
+        latest = get_latest(_db)
+        if latest:
+            _previous_raw = {METRIC_MAP[k]: latest.get(k, 0.0) for k in METRIC_KEYS}
+            logger.info("Recovered state from DB — %d metrics loaded", len(_previous_raw))
+        else:
+            logger.info("DB empty — starting fresh")
+    except Exception as exc:
+        logger.error("Failed to open DB: %s — continuing without persistence", exc)
+        _db = None
+
+    scrape_task = asyncio.create_task(_scraper_loop())
+    purge_task = asyncio.create_task(_purge_loop())
+    logger.info(
+        "LiteLLM Pulse started — scraping %s every %ds, DB: %s, timezone: %s, auth: %s",
+        METRICS_URL,
+        SCRAPE_INTERVAL,
+        DB_PATH if _db else "disabled",
+        str(_TZ),
+        "enabled" if METRICS_API_KEY and METRICS_API_KEY.strip() else "disabled",
+    )
+    yield
+    scrape_task.cancel()
+    purge_task.cancel()
+    with suppress(asyncio.CancelledError):
+        await scrape_task
+    with suppress(asyncio.CancelledError):
+        await purge_task
+    if _db is not None:
+        _db.close()
+
+
+app = FastAPI(
+    title="LiteLLM Pulse",
+    description="A lightweight metrics exporter for LiteLLM with SQLite time-series storage.",
+    version="0.0.0",
+    lifespan=lifespan,
+)
+
+
+def _summary() -> dict:
+    data: dict[str, float | None | str] = {}
+
+    for friendly, prom_name in METRIC_MAP.items():
+        data[friendly] = _raw_metrics.get(prom_name, 0.0)
+
+    if _db is not None:
+        daily = get_window_aggregate(_db, _start_of_day())
+        weekly = get_window_aggregate(_db, _start_of_week())
+        monthly = get_window_aggregate(_db, _start_of_month())
+        for friendly in METRIC_MAP:
+            data[f"{friendly}_daily"] = daily.get(friendly, 0.0)
+            data[f"{friendly}_weekly"] = weekly.get(friendly, 0.0)
+            data[f"{friendly}_monthly"] = monthly.get(friendly, 0.0)
+    else:
+        for friendly in METRIC_MAP:
+            data[f"{friendly}_daily"] = 0.0
+            data[f"{friendly}_weekly"] = 0.0
+            data[f"{friendly}_monthly"] = 0.0
+
+    data["last_scrape"] = _format_ts(_last_scrape.timestamp()) if _last_scrape else None
+    data["source"] = METRICS_URL
+    if _last_error:
+        data["error"] = _last_error
+    return data
+
+
+@app.get("/")
+async def root():
+    return _summary()
+
+
+@app.get("/api/v1/metrics")
+async def all_metrics():
+    return _summary()
+
+
+@app.get("/api/v1/metrics/{name}")
+async def get_metric(name: str):
+    valid_names = set(METRIC_MAP.keys())
+    valid_suffixes = {"daily", "weekly", "monthly"}
+    parts = name.rsplit("_", 1)
+    if len(parts) == 2 and parts[1] in valid_suffixes:
+        base, suffix = parts
+        if base in valid_names:
+            return {
+                "name": name,
+                "value": _summary().get(name, 0.0),
+                "last_scrape": _format_ts(_last_scrape.timestamp()) if _last_scrape else None,
+            }
+    if name in valid_names:
+        prom_name = METRIC_MAP[name]
+        return {
+            "name": name,
+            "value": _raw_metrics.get(prom_name, 0.0),
+            "last_scrape": _format_ts(_last_scrape.timestamp()) if _last_scrape else None,
+        }
+    return JSONResponse(
+        status_code=404,
+        content={
+            "error": f"Unknown metric: {name}",
+            "available": list(METRIC_MAP.keys()),
+        },
+    )
+
+
+@app.get("/api/v1/history")
+async def history(limit: int = 168):
+    if _db is not None:
+        snapshots = get_history(_db, limit=limit, tz=_TZ)
+        return {
+            "snapshots": snapshots,
+            "count": len(snapshots),
+            "source": "sqlite",
+        }
+    if _history is not None:
+        snapshots = []
+        for entry in list(_history)[-limit:]:
+            out = {k: v for k, v in entry.items() if k != "ts"}
+            out["timestamp"] = _format_ts(entry["ts"])
+            snapshots.append(out)
+        return {
+            "snapshots": snapshots,
+            "count": len(snapshots),
+            "source": "memory",
+        }
+    return {"snapshots": [], "count": 0, "source": "disabled"}
+
+
+@app.get("/raw")
+async def raw_metrics():
+    return _raw_metrics
+
+
+@app.get("/health")
+async def health():
+    return {"status": "ok" if _last_scrape else "starting"}
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+
+def main():
+    uvicorn.run(app, host=HOST, port=PORT, log_level=LOG_LEVEL.lower())
+
+
+if __name__ == "__main__":
+    main()

litellm_pulse/db.py

@@ -0,0 +1,179 @@
+"""SQLite-backed time-series storage for scrape snapshots."""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+from datetime import UTC, datetime, tzinfo
+from pathlib import Path
+
+logger = logging.getLogger("litellm-pulse")
+
+# All friendly metric names — defines the columns in the scrapes table.
+METRIC_KEYS = [
+    "requests",
+    "failed_requests",
+    "tokens",
+    "input_tokens",
+    "output_tokens",
+    "reasoning_tokens",
+    "cost",
+    "in_flight_requests",
+]
+
+
+def open_db(path: str) -> sqlite3.Connection:
+    """Open (or create) the SQLite database with WAL mode and the scrapes table.
+
+    Args:
+        path: Filesystem path to the .db file. Parent directories are created.
+
+    Returns:
+        A sqlite3 Connection with row factory set, WAL mode enabled.
+    """
+    db_path = Path(path)
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+
+    conn = sqlite3.connect(str(db_path), check_same_thread=False)
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute("PRAGMA synchronous=NORMAL")
+
+    columns = [
+        "id INTEGER PRIMARY KEY AUTOINCREMENT",
+        "ts INTEGER NOT NULL",
+        "is_reset INTEGER DEFAULT 0",
+    ]
+    for key in METRIC_KEYS:
+        columns.append(f"raw_{key} REAL DEFAULT 0")
+    for key in METRIC_KEYS:
+        columns.append(f"delta_{key} REAL DEFAULT 0")
+
+    conn.execute(f"CREATE TABLE IF NOT EXISTS scrapes ({', '.join(columns)})")
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_scrapes_ts ON scrapes(ts)")
+    conn.commit()
+
+    logger.info("SQLite database opened at %s", db_path)
+    return conn
+
+
+def store_snapshot(
+    conn: sqlite3.Connection,
+    ts: int,
+    raw: dict[str, float],
+    deltas: dict[str, float],
+    is_reset: bool,
+) -> None:
+    """Store one scrape snapshot with raw cumulative values and precomputed deltas.
+
+    Args:
+        conn: SQLite connection.
+        ts: Unix epoch timestamp (seconds).
+        raw: Mapping of friendly metric names to raw cumulative values.
+        deltas: Mapping of friendly metric names to delta values.
+        is_reset: Whether a counter reset was detected this scrape.
+    """
+    raw_cols = ", ".join(f"raw_{k}" for k in METRIC_KEYS)
+    delta_cols = ", ".join(f"delta_{k}" for k in METRIC_KEYS)
+    raw_vals = ", ".join(str(raw.get(k, 0.0)) for k in METRIC_KEYS)
+    delta_vals = ", ".join(str(deltas.get(k, 0.0)) for k in METRIC_KEYS)
+
+    conn.execute(
+        f"INSERT INTO scrapes (ts, is_reset, {raw_cols}, {delta_cols}) "
+        f"VALUES (?, ?, {raw_vals}, {delta_vals})",
+        (ts, 1 if is_reset else 0),
+    )
+    conn.commit()
+
+
+def get_latest(conn: sqlite3.Connection) -> dict[str, float] | None:
+    """Return the raw cumulative values from the most recent scrape, or None.
+
+    Args:
+        conn: SQLite connection.
+
+    Returns:
+        Dict mapping friendly metric names to raw cumulative values, or None
+        if the database is empty.
+    """
+    row = conn.execute("SELECT * FROM scrapes ORDER BY ts DESC LIMIT 1").fetchone()
+    if row is None:
+        return None
+    return {k: row[f"raw_{k}"] for k in METRIC_KEYS}
+
+
+def get_latest_ts(conn: sqlite3.Connection) -> int | None:
+    """Return the Unix timestamp of the most recent scrape, or None if empty."""
+    row = conn.execute("SELECT ts FROM scrapes ORDER BY ts DESC LIMIT 1").fetchone()
+    return row["ts"] if row else None
+
+
+def get_window_aggregate(conn: sqlite3.Connection, start_ts: int) -> dict[str, float]:
+    """Return SUM of deltas for all scrapes at or after ``start_ts``.
+
+    Args:
+        conn: SQLite connection.
+        start_ts: Unix epoch timestamp (seconds) — start of the aggregation window.
+
+    Returns:
+        Dict mapping friendly metric names to summed deltas over the window.
+    """
+    cols = ", ".join(f"COALESCE(SUM(delta_{k}), 0) AS {k}" for k in METRIC_KEYS)
+    row = conn.execute(f"SELECT {cols} FROM scrapes WHERE ts >= ?", (start_ts,)).fetchone()
+    return {k: row[k] for k in METRIC_KEYS}
+
+
+def get_history(conn: sqlite3.Connection, limit: int = 168, tz: tzinfo = UTC) -> list[dict]:
+    """Return the most recent ``limit`` scrape snapshots as a list of dicts.
+
+    Args:
+        conn: SQLite connection.
+        limit: Maximum number of snapshots to return.
+        tz: Timezone to use when formatting the ``timestamp`` field (the DB
+            always stores UTC Unix timestamps; conversion happens here).
+
+    Returns:
+        List of dicts, each with ``timestamp`` (ISO string in ``tz``),
+        ``is_reset``, raw values, and delta values.
+    """
+    rows = conn.execute(
+        f"SELECT ts, is_reset, {', '.join(f'raw_{k}' for k in METRIC_KEYS)}, "
+        f"{', '.join(f'delta_{k}' for k in METRIC_KEYS)} "
+        f"FROM scrapes ORDER BY ts DESC LIMIT ?",
+        (limit,),
+    ).fetchall()
+
+    results = []
+    for row in rows:
+        entry: dict[str, float | int | str] = {
+            "timestamp": datetime.fromtimestamp(row["ts"], tz=tz).isoformat(),
+            "is_reset": bool(row["is_reset"]),
+        }
+        for k in METRIC_KEYS:
+            entry[k] = row[f"raw_{k}"]
+            entry[f"{k}_delta"] = row[f"delta_{k}"]
+        results.append(entry)
+
+    results.reverse()
+    return results
+
+
+def purge_old(conn: sqlite3.Connection, retention_days: int) -> int:
+    """Delete scrapes older than ``retention_days`` days.
+
+    Args:
+        conn: SQLite connection.
+        retention_days: Number of days of data to retain.
+
+    Returns:
+        Number of rows deleted.
+    """
+    cursor = conn.execute(
+        "DELETE FROM scrapes WHERE ts < strftime('%s', 'now', ?)",
+        (f"-{retention_days} days",),
+    )
+    conn.commit()
+    deleted = cursor.rowcount
+    if deleted:
+        logger.info("Purged %d old scrapes (older than %d days)", deleted, retention_days)
+    return deleted

litellm_pulse/parser.py

@@ -0,0 +1,39 @@
+"""Prometheus text format parser."""
+
+from __future__ import annotations
+
+import re
+from collections import defaultdict
+
+_LINE_RE = re.compile(
+    r"^(?P<name>[a-zA-Z_:][a-zA-Z0-9_:]*)"
+    r"(?:\{[^}]*\})?"
+    r"\s+"
+    r"(?P<value>[-+]?\d*\.?\d+(?:[eE][-+]?\d+)?)"
+)
+
+
+def parse_prometheus_text(text: str) -> dict[str, float]:
+    """Parse Prometheus text exposition format and sum values per metric family.
+
+    Labels are ignored — all samples sharing the same metric name are summed.
+    This is useful for counter metrics where you want the grand total across
+    all label combinations.
+
+    Args:
+        text: Raw Prometheus text exposition format string.
+
+    Returns:
+        Dict mapping metric names to their summed float values.
+    """
+    totals: dict[str, float] = defaultdict(float)
+
+    for line in text.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        match = _LINE_RE.match(line)
+        if match:
+            totals[match.group("name")] += float(match.group("value"))
+
+    return dict(totals)

litellm_pulse-0.2.0.dist-info/METADATA

@@ -0,0 +1,500 @@
+Metadata-Version: 2.4
+Name: litellm-pulse
+Version: 0.2.0
+Summary: A lightweight metrics exporter for LiteLLM — scrapes Prometheus metrics and serves JSON for dashboards like Homepage and Home Assistant.
+Project-URL: Homepage, https://github.com/jakepenzak/litellm-pulse
+Project-URL: Repository, https://github.com/jakepenzak/litellm-pulse
+Project-URL: Issues, https://github.com/jakepenzak/litellm-pulse/issues
+Author: Jake Pieniazek
+License: MIT
+License-File: LICENSE
+Keywords: home-assistant,homepage,litellm,metrics,prometheus
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: uvicorn[standard]>=0.34.0
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/jakepenzak/litellm-pulse/main/assets/litellm-pulse.svg" alt="LiteLLM Pulse" width="320">
+</p>
+
+<p align="center">
+  <a href="https://github.com/jakepenzak/litellm-pulse/releases"><img src="https://img.shields.io/github/v/release/jakepenzak/litellm-pulse" alt="GitHub release"></a>
+  <a href="https://pypi.org/project/litellm-pulse/"><img src="https://img.shields.io/pypi/v/litellm-pulse" alt="PyPI version"></a>
+  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11+-blue" alt="Python 3.11+"></a>
+  <a href="https://github.com/jakepenzak/litellm-pulse/blob/main/LICENSE"><img src="https://img.shields.io/github/license/jakepenzak/litellm-pulse" alt="License: MIT"></a>
+  <a href="https://github.com/jakepenzak/litellm-pulse"><img src="https://img.shields.io/badge/status-beta-yellow" alt="Development Status"></a>
+  <br>
+  <a href="https://github.com/jakepenzak/litellm-pulse/actions/workflows/ci.yml"><img src="https://github.com/jakepenzak/litellm-pulse/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/jakepenzak/litellm-pulse/actions/workflows/release.yml"><img src="https://github.com/jakepenzak/litellm-pulse/actions/workflows/release.yml/badge.svg" alt="Release"></a>
+</p>
+
+
+
+A lightweight metrics exporter for [LiteLLM](https://github.com/BerriAI/litellm) — scrapes Prometheus metrics, stores them in SQLite, and serves JSON for dashboards like [Homepage](https://gethomepage.dev) and home automation systems like [Home Assistant](https://www.home-assistant.io).
+
+## Why
+
+LiteLLM exposes usage metrics in Prometheus format, but consuming them typically means standing up Prometheus, Grafana, and an alertmanager — a stack that's overkill if you just want to see "how much did I spend today?" on a dashboard. For homelab enthusiasts running LiteLLM alongside services like Homepage and Home Assistant, that's a lot of overhead for very simple needs.
+
+LiteLLM Pulse is a lightweight observability layer that sits between LiteLLM's `/metrics` endpoint and a JSON-based REST API. It scrapes Prometheus text format on a schedule, stores time-series snapshots in SQLite, and serves clean JSON that any HTTP client can consume — no Prometheus server, no Grafana dashboards, no query language to learn.
+
+It is **not** designed to replace Prometheus or Grafana. If you need multi-source metrics, complex alerting rules, or rich visual dashboards, use those tools. LiteLLM Pulse is for the 90% case: you have a single LiteLLM instance, you want today's token spend on your Homepage dashboard, and you don't want to run three more containers to get it.
+
+## What It Does
+
+LiteLLM exposes usage metrics (requests, tokens, spend) in Prometheus text format as cumulative counters. LiteLLM Pulse scrapes that endpoint on a schedule, parses the metrics, stores snapshots in SQLite, and serves them as clean JSON over a REST API.
+
+Beyond raw cumulative totals, LiteLLM Pulse computes **deltas** (change since last scrape), and **daily/weekly/monthly aggregates** (sum of deltas since the start of the current day/week/month) — all backed by SQLite for persistence across restarts.
+
+```
+LiteLLM /metrics  ──scrape──▶  LiteLLM Pulse  ──JSON──▶  Homepage / Home Assistant / anything
+                                    │
+                                    ▼
+                                SQLite
+                           (time-series storage)
+```
+
+## LiteLLM Setup
+
+> **The LiteLLM `/metrics` endpoint is not enabled by default.** You must configure LiteLLM to publish Prometheus metrics before LiteLLM Pulse can scrape them.
+
+Add the `prometheus` callback to your LiteLLM proxy config (`config.yaml`):
+
+```yaml
+litellm_settings:
+  callbacks:
+    - prometheus
+```
+
+Start LiteLLM and verify the endpoint:
+
+```bash
+curl http://localhost:4000/metrics/
+```
+
+If you see Prometheus-formatted text, LiteLLM is publishing metrics and you're ready to set up LiteLLM Pulse.
+
+See the [LiteLLM Prometheus docs](https://docs.litellm.ai/docs/proxy/prometheus) for advanced configuration options.
+
+## Quick Start
+
+### Docker Compose
+
+```yaml
+services:
+  litellm-pulse:
+    image: ghcr.io/jakepenzak/litellm-pulse:latest
+    container_name: litellm-pulse
+    restart: unless-stopped
+    environment:
+      LITELLM_PULSE_METRICS_URL: "http://litellm:4000/metrics/"
+      LITELLM_PULSE_SCRAPE_INTERVAL: "60"
+      LITELLM_PULSE_PORT: "8000"
+      LITELLM_PULSE_TIMEZONE: "America/New_York"
+      # LITELLM_PULSE_METRICS_API_KEY: "sk-your-litellm-api-key"
+    ports:
+      - "8000:8000"
+    volumes:
+      - litellm-pulse-data:/app/data
+
+volumes:
+  litellm-pulse-data:
+```
+
+### Docker Run
+
+```bash
+docker run -d \
+  --name litellm-pulse \
+  -p 8000:8000 \
+  -e LITELLM_PULSE_METRICS_URL=http://litellm:4000/metrics/ \
+  -e LITELLM_PULSE_SCRAPE_INTERVAL=60 \
+  -e LITELLM_PULSE_TIMEZONE=America/New_York \
+  -v litellm-pulse-data:/app/data \
+  ghcr.io/jakepenzak/litellm-pulse:latest
+```
+
+### Running Locally (with uv)
+
+```bash
+uv sync
+uv run litellm-pulse
+```
+
+### Running from PyPI
+
+```bash
+uvx litellm-pulse                                # run directly
+uv tool install litellm-pulse && litellm-pulse   # install permanently
+pip install litellm-pulse && litellm-pulse       # with pip
+```
+
+## Configuration
+
+All configuration is via environment variables prefixed with `LITELLM_PULSE_`. No config files required.
+
+### Core Settings
+
+| Variable | Default | Description |
+|---|---|---|
+| `LITELLM_PULSE_METRICS_URL` | `http://litellm:4000/metrics/` | Prometheus metrics endpoint to scrape |
+| `LITELLM_PULSE_SCRAPE_INTERVAL` | `60` | Seconds between scrapes |
+| `LITELLM_PULSE_PORT` | `8000` | Port to serve the API on |
+| `LITELLM_PULSE_HOST` | `0.0.0.0` | Address to bind to |
+| `LITELLM_PULSE_VERIFY_SSL` | `false` | Whether to verify TLS certificates when scraping |
+| `LITELLM_PULSE_SCRAPE_TIMEOUT` | `30` | Request timeout in seconds |
+| `LITELLM_PULSE_LOG_LEVEL` | `info` | Log level (`debug`, `info`, `warning`, `error`) |
+| `LITELLM_PULSE_TIMEZONE` | `UTC` | Timezone for API timestamps and day/week/month boundaries (IANA name, e.g. `America/New_York`) |
+| `LITELLM_PULSE_METRICS_API_KEY` | _(empty)_ | LiteLLM API key for authenticated `/metrics` endpoints. Only needed if your LiteLLM proxy has [`require_auth_for_metrics_endpoint`](https://docs.litellm.ai/docs/proxy/prometheus#add-authentication-on-metrics-endpoint) set to `true`. |
+
+> **When to use `LITELLM_PULSE_METRICS_API_KEY`:** If your LiteLLM proxy config includes `require_auth_for_metrics_endpoint: true` under `litellm_settings`, the `/metrics` endpoint requires authentication via a `Bearer` token. Set `LITELLM_PULSE_METRICS_API_KEY` to a valid LiteLLM API key so LiteLLM Pulse can authenticate. If this variable is left empty (the default), no `Authorization` header is sent — matching the default unauthenticated LiteLLM behavior.
+
+### SQLite / Time-Series Settings
+
+| Variable | Default | Description |
+|---|---|---|
+| `LITELLM_PULSE_DB_PATH` | `./data/litellm_pulse.db` | Path to the SQLite database file |
+| `LITELLM_PULSE_DB_RETENTION_DAYS` | `90` | Auto-purge data older than N days (hourly purge cycle) |
+| `LITELLM_PULSE_HISTORY_SIZE` | `168` | Max snapshots in the in-memory ring buffer (used as fallback if DB is unavailable) |
+
+> **Timezone note:** The database always stores timestamps as UTC. The `LITELLM_PULSE_TIMEZONE` setting only affects API output (timestamps are converted to the configured timezone) and aggregate window boundaries (daily/weekly/monthly resets are computed against the configured timezone's midnight/Monday/1st). Set it to any valid [IANA timezone name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) (e.g. `America/New_York`, `Europe/London`). Invalid values fall back to UTC with a warning.
+
+### Metric Mappings
+
+Each tracked metric maps a friendly name to a Prometheus metric name. Override any of them by setting the corresponding `LITELLM_PULSE_METRIC_*` env var.
+
+| Variable | Default |
+|---|---|
+| `LITELLM_PULSE_METRIC_REQUESTS` | `litellm_proxy_total_requests_metric_total` |
+| `LITELLM_PULSE_METRIC_FAILED_REQUESTS` | `litellm_proxy_failed_requests_metric_total` |
+| `LITELLM_PULSE_METRIC_TOKENS` | `litellm_total_tokens_metric_total` |
+| `LITELLM_PULSE_METRIC_INPUT_TOKENS` | `litellm_input_tokens_metric_total` |
+| `LITELLM_PULSE_METRIC_OUTPUT_TOKENS` | `litellm_output_tokens_metric_total` |
+| `LITELLM_PULSE_METRIC_REASONING_TOKENS` | `litellm_output_reasoning_tokens_metric_total` |
+| `LITELLM_PULSE_METRIC_COST` | `litellm_spend_metric_total` |
+| `LITELLM_PULSE_METRIC_IN_FLIGHT_REQUESTS` | `litellm_in_flight_requests` |
+
+## API Endpoints
+
+### `GET /` or `GET /api/v1/metrics`
+
+Returns all tracked metrics: cumulative totals, daily/weekly/monthly aggregates, and metadata.
+
+```json
+{
+  "requests": 1234,
+  "failed_requests": 5,
+  "tokens": 567890,
+  "input_tokens": 300000,
+  "output_tokens": 267890,
+  "reasoning_tokens": 0,
+  "cost": 12.345678,
+  "in_flight_requests": 2,
+  "requests_daily": 215,
+  "requests_weekly": 1200,
+  "requests_monthly": 3400,
+  "tokens_daily": 45000,
+  "tokens_weekly": 310000,
+  "tokens_monthly": 780000,
+  "cost_daily": 0.02,
+  "cost_weekly": 0.15,
+  "cost_monthly": 0.52,
+  "last_scrape": "2025-06-21T12:00:00+00:00",
+  "source": "http://litellm:4000/metrics/"
+}
+```
+
+Every tracked metric gets `_daily`, `_weekly`, and `_monthly` suffixes:
+
+| Suffix | Meaning |
+|---|---|
+| _(none)_ | Cumulative total since LiteLLM started (raw counter value) |
+| `_daily` | Sum of deltas since start of today (midnight in the configured timezone) |
+| `_weekly` | Sum of deltas since start of this week (Monday in the configured timezone) |
+| `_monthly` | Sum of deltas since start of this month (1st in the configured timezone) |
+
+### `GET /api/v1/metrics/{name}`
+
+Returns a single metric by friendly name. Also supports `_daily`, `_weekly`, `_monthly` suffixes.
+
+```
+GET /api/v1/metrics/cost
+GET /api/v1/metrics/cost_daily
+GET /api/v1/metrics/tokens_weekly
+```
+
+```json
+{
+  "name": "cost_daily",
+  "value": 0.02,
+  "last_scrape": "2025-06-21T12:00:00+00:00"
+}
+```
+
+### `GET /api/v1/history?limit=168`
+
+Returns the most recent scrape snapshots as a JSON array (newest last). Draws from SQLite if available, falls back to in-memory ring buffer.
+
+```json
+{
+  "snapshots": [
+    {
+      "timestamp": "2025-06-21T12:00:00+00:00",
+      "is_reset": false,
+      "requests": 1234,
+      "requests_delta": 3,
+      "tokens": 567890,
+      "tokens_delta": 24500,
+      "cost": 12.3456,
+      "cost_delta": 0.0231
+    }
+  ],
+  "count": 168,
+  "source": "sqlite"
+}
+```
+
+### `GET /raw`
+
+Returns all raw parsed Prometheus metrics (every metric family found, summed). Useful for debugging.
+
+### `GET /health`
+
+Returns `{"status": "ok"}` once the first successful scrape has completed.
+
+## How Deltas & Aggregates Work
+
+LiteLLM's Prometheus metrics are **counters** — they grow cumulatively and only reset when the LiteLLM process restarts. LiteLLM Pulse handles this as follows:
+
+1. **Each scrape** stores the raw cumulative value and a computed delta (change since the previous scrape).
+2. **Daily/weekly/monthly** values are computed as `SUM(delta)` for all scrapes within the time window.
+3. **Counter reset detection**: If any counter drops by more than 50%, LiteLLM Pulse assumes LiteLLM restarted. The delta for that scrape is set to the current value (treating it as starting from 0), and `is_reset=true` is recorded in the database. This ensures daily/weekly/monthly sums remain correct even across LiteLLM restarts.
+
+## State Recovery
+
+| Scenario | Behavior |
+|---|---|
+| **Fresh start** | DB empty → first scrape has no deltas, second scrape onward has valid deltas |
+| **App restart** | Reads last row from DB → restores last-known raw counters → seamless continuation |
+| **LiteLLM restart** | Counters drop → reset detected → delta computed from 0, `is_reset=1` stored → daily sums remain correct |
+| **DB corrupted** | `open_db()` catches SQLite errors, starts fresh with a warning log |
+| **Disk full** | Writes fail → `error` field set in API response → recovers when disk space returns |
+
+## Integrations
+
+### Homepage (Custom API Widget)
+
+Add a service entry in `services.yaml` with a `customapi` widget:
+
+```yaml
+- LiteLLM:
+    icon: https://cdn.jsdelivr.net/gh/selfhst/icons/png/litellm.png
+    href: https://litellm.home.lan
+    description: LLM proxy and management
+    widget:
+      type: customapi
+      url: http://litellm-pulse:8000/api/v1/metrics
+      refreshInterval: 60000
+      mappings:
+        - field: requests
+          label: Total Requests
+          format: number
+        - field: cost_daily
+          label: Spend Today
+          format: float
+          prefix: "$"
+        - field: cost_monthly
+          label: Spend This Month
+          format: float
+          prefix: "$"
+        - field: tokens_daily
+          label: Tokens Today
+          format: number
+```
+
+### Home Assistant (REST Sensors)
+
+Add RESTful sensors to `configuration.yaml`. The [`rest`](https://www.home-assistant.io/integrations/rest) integration lets you define multiple sensors from a single HTTP request, which avoids polling the LiteLLM Pulse endpoint more than necessary:
+
+```yaml
+rest:
+  - resource: http://litellm-pulse:8000/api/v1/metrics
+    scan_interval: 60        # seconds between polls (default: 30)
+    timeout: 10              # seconds before the sensor is marked unavailable
+    verify_ssl: true
+    sensor:
+      - name: LiteLLM Requests
+        unique_id: litellm_requests
+        value_template: "{{ value_json.requests }}"
+        unit_of_measurement: "req"
+        device_class: duration
+        state_class: total_increasing
+      - name: LiteLLM Tokens
+        unique_id: litellm_tokens
+        value_template: "{{ value_json.tokens }}"
+        unit_of_measurement: "tokens"
+        state_class: total_increasing
+      - name: LiteLLM Spend
+        unique_id: litellm_spend
+        value_template: "{{ value_json.cost }}"
+        unit_of_measurement: "USD"
+        state_class: total_increasing
+      - name: LiteLLM Spend Today
+        unique_id: litellm_spend_today
+        value_template: "{{ value_json.cost_daily }}"
+        unit_of_measurement: "USD"
+        state_class: measurement
+        force_update: true
+      - name: LiteLLM Spend This Month
+        unique_id: litellm_spend_this_month
+        value_template: "{{ value_json.cost_monthly }}"
+        unit_of_measurement: "USD"
+        state_class: measurement
+        force_update: true
+      - name: LiteLLM Tokens Today
+        unique_id: litellm_tokens_today
+        value_template: "{{ value_json.tokens_daily }}"
+        unit_of_measurement: "tokens"
+        state_class: measurement
+        force_update: true
+```
+
+If you only need a single metric, you can use the [`sensor.rest`](https://www.home-assistant.io/integrations/sensor.rest/) platform instead, which polls the endpoint once per sensor:
+
+```yaml
+sensor:
+  - platform: rest
+    resource: http://litellm-pulse:8000/api/v1/metrics/cost_daily
+    name: LiteLLM Spend Today
+    unique_id: litellm_spend_today
+    value_template: "{{ value_json.value }}"
+    unit_of_measurement: "USD"
+    state_class: measurement
+    force_update: true
+```
+
+> **Tip:** To refresh a sensor on demand (outside the polling schedule), call the `homeassistant.update_entity` action targeting the sensor entity.
+
+
+## Contributing
+
+Contributions are welcome! Please read the guidelines below before opening a pull request.
+
+### Pull Request Process
+
+1. Fork the repository and create a feature branch from `main`
+2. Run `uv run pre-commit install` to set up local git hooks
+3. Make your changes, ensuring `pre-commit run --all-files` passes
+4. Add or update tests as appropriate
+5. Open a pull request with a clear description of the changes
+
+### Conventional Commits
+
+**Pull request titles must follow the [Conventional Commits](https://www.conventionalcommits.org/) specification.** This is enforced by branch protection rules and is required for the release automation to work correctly.
+
+The format is:
+
+```
+<type>(<scope>): <description>
+```
+
+#### Allowed Types
+
+| Type | Description |
+|---|---|
+| `feat` | A new feature |
+| `fix` | A bug fix |
+| `docs` | Documentation only changes |
+| `style` | Changes that do not affect the meaning of the code (formatting, etc.) |
+| `refactor` | A code change that neither fixes a bug nor adds a feature |
+| `perf` | A code change that improves performance |
+| `test` | Adding or correcting tests |
+| `ci` | Changes to CI configuration files and scripts |
+| `chore` | Other changes that don't modify src or test files |
+| `build` | Changes that affect the build system or dependencies |
+
+#### Examples
+
+- `feat: add Prometheus push gateway support`
+- `fix(db): handle negative deltas on counter reset`
+- `docs: update Home Assistant integration examples`
+- `ci: add Python 3.13 to test matrix`
+- `refactor(parser): simplify metric extraction logic`
+
+#### Scopes (optional)
+
+Common scopes: `parser`, `db`, `app`, `ci`, `docker`, `deps`
+
+### Releases
+
+Releases are managed automatically by [release-please](https://github.com/googleapis/release-please) using the [manifest-driven](https://github.com/googleapis/release-please/blob/main/docs/manifest-releaser.md) approach. Configuration lives in [`.github/release-please-config.json`](.github/release-please-config.json) and version tracking in [`.github/.release-please-manifest.json`](.github/.release-please-manifest.json).
+
+When PRs with conventional commit titles are merged to `main`:
+
+1. release-please maintains a "release PR" that accumulates changes and updates `CHANGELOG.md`
+2. When the release PR is merged, a new GitHub Release is created with an auto-generated changelog (with emoji section headers)
+3. release-please bumps the version in `pyproject.toml` and `litellm_pulse/__init__.py`
+4. The Docker build & publish workflow is triggered by the `release: published` event
+5. Images are tagged with semantic version (e.g., `v1.2.3`), major/minor aliases (e.g., `1.2`, `1`), and `latest`
+
+### Setup
+
+```bash
+make venv                  # sync deps + install pre-commit hooks
+# or: uv sync --all-extras --all-groups --frozen && uv run pre-commit install
+```
+
+### Running
+
+```bash
+uv run litellm-pulse       # run the server locally
+# or: make run
+```
+
+### Linting & Formatting
+
+Linting and formatting are enforced via [pre-commit](https://pre-commit.com) with [ruff](https://docs.astral.sh/ruff):
+
+```bash
+uv run pre-commit install           # install git hooks (run once)
+uv run pre-commit run --all-files   # run all checks manually
+```
+
+This runs `ruff check --fix` and `ruff format` across the codebase. The same checks run in CI on every push and pull request.
+
+### Testing
+
+```bash
+uv run pytest -v           # run tests
+# or: make tests           # runs pytest
+# or: make coverage        # serve HTML coverage report at http://localhost:8080
+```
+
+> Run `make help` to see all available targets.
+
+### CI/CD
+
+| Workflow | Trigger | What it does |
+|---|---|---|
+| **CI** ([ci.yml](.github/workflows/ci.yml)) | Push to `main`, PRs | Runs pre-commit (ruff lint + format) and pytest on Python 3.11 & 3.12 |
+| **Release** ([release.yml](.github/workflows/release.yml)) |  Push to `main` | Runs `release-please` suite. On releases created via `release-please`, builds Docker image and publishes to `ghcr.io/jakepenzak/litellm-pulse` with semantic version tags, and publishes the package to PyPI |
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Disclaimer
+
+LiteLLM Pulse is an independent, community-developed project created to provide monitoring and analytics for LiteLLM deployments.
+
+This project is **not affiliated with, endorsed by, sponsored by, or maintained by** LiteLLM or Berri AI.
+
+"LiteLLM" and any associated trademarks, service marks, logos, or trade names are the property of their respective owners and are used here solely to identify compatibility with the LiteLLM ecosystem.

litellm_pulse-0.2.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+litellm_pulse/__init__.py,sha256=Zn1KFblwuFHiDRdRAiRnDBRkbPttWh44jKa5zG2ov0E,22
+litellm_pulse/app.py,sha256=z6JaKXkEEgQVT6Skh-9hvNyoZdMkFDScCAA3G4alFVw,13026
+litellm_pulse/db.py,sha256=2Ffv88S95cp-klGHo1ghV2bWHC9C_knOdEjSanChe7U,5825
+litellm_pulse/parser.py,sha256=Depph4QMG19NUqLt5L7gDCbbaFZyyCYo707fDgsImVU,1087
+litellm_pulse-0.2.0.dist-info/METADATA,sha256=9Ou73d8kXNWYBm0Q-ThwaQjUu4l_EjG47r7ne-CFxZc,21015
+litellm_pulse-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+litellm_pulse-0.2.0.dist-info/entry_points.txt,sha256=-S5Z4mFATM9MtooC3yYvCqGEfe0FU5eMA_AbmoO8haQ,57
+litellm_pulse-0.2.0.dist-info/licenses/LICENSE,sha256=Tb9yMSN4l7RG0TSrXnzo1YE1zHUb53l4RLeVYaSPzZ0,1071
+litellm_pulse-0.2.0.dist-info/RECORD,,

litellm_pulse-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

litellm_pulse-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+litellm-pulse = litellm_pulse.app:main

litellm_pulse-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jake Pieniazek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.