941028e705
- Add release-gate.yml: 11-job pipeline (lint, tests, Docker build/smoke, Trivy scan, dep audit, audit checks, e2e API+UI, PR summary comment) - Fix CI double-trigger on release branches (push + PR) - Add CODE_OF_CONDUCT.md, SECURITY.md, PR template - Add docs: git-workflow, architecture (ADR), release, operations, community - Add profiles/fastapi-vue for automated audit checks - Add docs/PROCESSES.md: index of 19 available processes
105 lines
2.5 KiB
Markdown
105 lines
2.5 KiB
Markdown
# Monitoring Checklist
|
|
|
|
What to monitor in a Docling Studio deployment.
|
|
|
|
## Health Endpoint
|
|
|
|
The primary monitoring signal is the health endpoint:
|
|
|
|
```bash
|
|
curl -s http://localhost:3000/api/health
|
|
```
|
|
|
|
Expected response:
|
|
```json
|
|
{
|
|
"status": "ok",
|
|
"engine": "local",
|
|
"version": "0.3.0",
|
|
"deploymentMode": "self-hosted"
|
|
}
|
|
```
|
|
|
|
**Alert if**: status != "ok", endpoint unreachable, or response time > 5s.
|
|
|
|
## Four Golden Signals
|
|
|
|
### 1. Latency
|
|
|
|
| Endpoint | Expected | Alert threshold |
|
|
|----------|----------|-----------------|
|
|
| `GET /api/health` | < 100ms | > 1s |
|
|
| `POST /api/documents` (upload) | < 2s | > 10s |
|
|
| `POST /api/analyses` (create) | < 500ms (queuing only) | > 5s |
|
|
| `GET /api/analyses/:id` (results) | < 500ms | > 3s |
|
|
|
|
### 2. Traffic
|
|
|
|
| Metric | What to watch |
|
|
|--------|---------------|
|
|
| Requests per minute | Baseline for normal usage |
|
|
| Uploads per hour | Capacity planning |
|
|
| Concurrent analyses | Should stay <= `MAX_CONCURRENT_ANALYSES` |
|
|
|
|
### 3. Errors
|
|
|
|
| Signal | Alert threshold |
|
|
|--------|-----------------|
|
|
| HTTP 5xx rate | > 1% of requests |
|
|
| Analysis failure rate | > 10% of analyses |
|
|
| Rate limit hits (429) | Spike = possible abuse |
|
|
|
|
### 4. Saturation
|
|
|
|
| Resource | Check command | Alert threshold |
|
|
|----------|---------------|-----------------|
|
|
| CPU | `docker stats` | > 90% sustained |
|
|
| Memory | `docker stats` | > 85% (especially in local mode with PyTorch) |
|
|
| Disk (SQLite + uploads) | `du -sh data/` | > 80% of volume |
|
|
| Docker container restarts | `docker inspect --format='{{.RestartCount}}'` | > 0 |
|
|
|
|
## Docker Health Check
|
|
|
|
The `docker-compose.yml` includes a built-in health check:
|
|
|
|
```yaml
|
|
healthcheck:
|
|
test: ["CMD", "curl", "-f", "http://localhost:3000/api/health"]
|
|
interval: 30s
|
|
timeout: 10s
|
|
retries: 3
|
|
```
|
|
|
|
Docker will mark the container as `unhealthy` after 3 consecutive failures.
|
|
|
|
## Log Monitoring
|
|
|
|
### Backend logs (uvicorn)
|
|
|
|
```bash
|
|
docker compose logs -f backend
|
|
```
|
|
|
|
Watch for:
|
|
- `ERROR` or `CRITICAL` log levels
|
|
- `TimeoutError` from Docling processing
|
|
- `sqlite3.OperationalError` (DB issues)
|
|
- `429 Too Many Requests` spikes
|
|
|
|
### Frontend logs (nginx)
|
|
|
|
```bash
|
|
docker compose logs -f frontend
|
|
```
|
|
|
|
Watch for:
|
|
- `502 Bad Gateway` (backend down)
|
|
- `413 Request Entity Too Large` (file size limit)
|
|
|
|
## Recommended Setup
|
|
|
|
For production deployments, consider:
|
|
|
|
1. **Uptime monitor** — ping `/api/health` every 60s (UptimeRobot, Healthchecks.io)
|
|
2. **Log aggregation** — ship Docker logs to a central service
|
|
3. **Alerting** — notify on container restart, health check failure, or error spike
|