# LibreChat Analytics Dashboard

Usage analytics dashboard for LibreChat. Queries the existing MongoDB to show model/agent usage, costs, and top users with time filtering.

## Features

- **Overview** — Total cost, tokens, active users, conversations with time-series charts
- **Users** — Top users ranked by cost with token and conversation counts
- **Models** — Model breakdown with prompt/completion token and cost split
- **Agents** — Agent usage with underlying model resolution
- **Time Filtering** — 24H, 7D, 30D, or custom date range
- **Auto-refresh** — Updates every 60 seconds
- **API Key Auth** — Dashboard protected by API key

## Prerequisites

- Docker and Docker Compose
- Access to LibreChat's MongoDB (same Docker network)

## Quick Start

### 1. Clone the repo

```bash
git clone git@bitbucket.org:zlalani/librechat-analytics.git
cd librechat-analytics
```

### 2. Configure environment

```bash
cp .env.example .env
```

Edit `.env`:
```
MONGO_URI=mongodb://mongodb:27017/LibreChat
DASHBOARD_API_KEY=your-secure-key-here
PORT=3001
```

**Important:** Change `DASHBOARD_API_KEY` to a secure value. This key is required to access the dashboard.

### 3. Build and run

```bash
docker compose up -d --build
```

### 4. Connect to LibreChat's Docker network

The analytics container needs to reach LibreChat's MongoDB. Connect it to the same network:

```bash
docker network connect librechat_default librechat-analytics
```

> **Note:** If your LibreChat network has a different name, check with `docker network ls`.

### 5. Verify

```bash
# Health check (no auth required)
curl http://localhost:3001/health

# Test API (requires API key)
curl -H "x-api-key: your-secure-key-here" http://localhost:3001/api/summary?period=30d
```

### 6. Access the dashboard

Open `http://localhost:3001` in your browser. You'll be prompted to enter the API key on first visit.

## Nginx Proxy (Optional)

To expose via LibreChat's existing nginx, add to the nginx config (before `location /api`):

```nginx
location /analytics/ {
    proxy_pass http://librechat-analytics:3001/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}
```

Then restart nginx:
```bash
docker exec <nginx-container> nginx -s reload
```

Dashboard will be available at `https://your-domain/analytics/`.

## Server Deployment

### On the server:

```bash
cd /opt
git clone git@bitbucket.org:zlalani/librechat-analytics.git
cd librechat-analytics
cp .env.example .env
# Edit .env with your MONGO_URI and DASHBOARD_API_KEY
docker compose up -d --build
docker network connect librechat_default librechat-analytics
```

### Updating:

```bash
cd /opt/librechat-analytics
git pull
docker compose up -d --build
```

## Ports

| Service | Port | Notes |
|---------|------|-------|
| Analytics Dashboard | 3001 | Bound to 127.0.0.1 only |

Does not clash with LibreChat (3080) or Code Interpreter (8000/8005).

## Cost Calculation

Costs come directly from LibreChat's `transactions` collection. LibreChat stores `tokenValue = rawAmount × rate` where rate is USD per 1M tokens. The dashboard reads these pre-calculated values — it does not independently calculate pricing.

## API Endpoints

All require `x-api-key` header. All accept `?period=24h|7d|30d|custom&start=ISO&end=ISO`.

| Endpoint | Description |
|----------|-------------|
| `GET /health` | Health check (no auth) |
| `GET /api/summary` | Total tokens, cost, users, conversations |
| `GET /api/top-users?limit=10` | Users ranked by cost |
| `GET /api/top-models?limit=10` | Models ranked by cost (resolves agent IDs to underlying LLM) |
| `GET /api/top-agents?limit=10` | Agents ranked by cost |
| `GET /api/cost-breakdown` | Per-model input vs output cost split |
| `GET /api/usage-over-time` | Time-series tokens and cost |