139 lines
3.7 KiB
Markdown
139 lines
3.7 KiB
Markdown
# 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 |
|