186 lines
4.9 KiB
Markdown
186 lines
4.9 KiB
Markdown
---
|
|
name: clip-health
|
|
description: Diagnóstico rápido Paperclip — serviço, BD, heartbeats falhados, budget, disco. Usar quando "clip health", "saúde clip", "diagnóstico paperclip", "clip problemas".
|
|
context: fork
|
|
layer: wiki
|
|
---
|
|
|
|
# /clip-health — Diagnostico Paperclip
|
|
|
|
Verificacao rapida da saude do sistema Clip.
|
|
|
|
## Constantes
|
|
|
|
```
|
|
BD: PGPASSWORD="paperclip" psql -h localhost -p 54329 -U paperclip -d paperclip
|
|
PAPERCLIP_DIR: /home/ealmeida/paperclip
|
|
INSTANCE_DIR: /home/ealmeida/.paperclip/instances/default
|
|
```
|
|
|
|
## Procedimento
|
|
|
|
Executar todas as verificacoes em paralelo, depois apresentar relatorio.
|
|
|
|
### Check 1: Serviço
|
|
|
|
```bash
|
|
ps aux | grep -E "paperclip.*src/index|pnpm.*paperclipai" | grep -v grep | head -5
|
|
```
|
|
|
|
- Processos encontrados = OK
|
|
- Nenhum processo = CRITICO (iniciar com: `cd /home/ealmeida/paperclip && pnpm --filter @paperclipai/server dev`)
|
|
|
|
Verificar também memória partilhada PostgreSQL (causa do bug POSIX shared memory):
|
|
```bash
|
|
ls /dev/shm/PostgreSQL.* 2>/dev/null && echo "POSIX OK" || echo "POSIX em falta — BD pode falhar ao ligar"
|
|
```
|
|
|
|
- POSIX OK = OK
|
|
- POSIX em falta + processos activos = AVISO (PostgreSQL perdeu shared memory — reiniciar Paperclip)
|
|
- POSIX em falta + sem processos = CRITICO
|
|
|
|
### Check 2: Base de dados
|
|
|
|
Conexao:
|
|
```sql
|
|
SELECT 1 as connected;
|
|
```
|
|
|
|
Tamanho:
|
|
```sql
|
|
SELECT pg_size_pretty(pg_database_size('paperclip')) as db_size;
|
|
```
|
|
|
|
Contagens:
|
|
```sql
|
|
SELECT
|
|
(SELECT COUNT(*) FROM agents WHERE company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f') as agentes,
|
|
(SELECT COUNT(*) FROM issues WHERE company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f') as issues,
|
|
(SELECT COUNT(*) FROM heartbeat_runs hr JOIN agents a ON hr.agent_id = a.id WHERE a.company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f') as heartbeats;
|
|
```
|
|
|
|
- Conexao OK = OK
|
|
- Conexao falha = CRITICO
|
|
|
|
### Check 3: Heartbeats falhados (24h)
|
|
|
|
```sql
|
|
SELECT a.name, hr.status, LEFT(hr.error, 70) as erro, hr.started_at::timestamp(0)
|
|
FROM heartbeat_runs hr JOIN agents a ON hr.agent_id = a.id
|
|
WHERE a.company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f'
|
|
AND hr.status IN ('failed','error')
|
|
AND hr.started_at > NOW() - INTERVAL '24 hours'
|
|
ORDER BY hr.started_at DESC
|
|
LIMIT 20;
|
|
```
|
|
|
|
- 0 falhas = OK
|
|
- 1-2 falhas = AVISO
|
|
- 3+ falhas = CRITICO
|
|
|
|
### Check 4: Budget
|
|
|
|
```sql
|
|
SELECT name, budget_monthly_cents, spent_monthly_cents,
|
|
CASE WHEN budget_monthly_cents > 0
|
|
THEN ROUND(spent_monthly_cents::numeric / budget_monthly_cents * 100, 1)
|
|
ELSE 0 END as pct
|
|
FROM agents
|
|
WHERE company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f'
|
|
AND budget_monthly_cents > 0
|
|
AND spent_monthly_cents > 0
|
|
ORDER BY pct DESC;
|
|
```
|
|
|
|
- <80% = OK
|
|
- 80-95% = AVISO
|
|
- >95% = CRITICO
|
|
|
|
### Check 5: Disco
|
|
|
|
```bash
|
|
df -h /home/ealmeida/.paperclip/ | tail -1
|
|
```
|
|
|
|
```bash
|
|
du -sh /home/ealmeida/.paperclip/instances/default/db/ 2>/dev/null
|
|
du -sh /home/ealmeida/.paperclip/instances/default/logs/ 2>/dev/null
|
|
du -sh /home/ealmeida/.paperclip/instances/default/data/ 2>/dev/null
|
|
```
|
|
|
|
- >30% livre = OK
|
|
- 15-30% livre = AVISO
|
|
- <15% livre = CRITICO
|
|
|
|
### Check 6: API Health
|
|
|
|
```bash
|
|
curl -s --max-time 5 http://localhost:3100/health 2>/dev/null || echo "FALHA"
|
|
```
|
|
|
|
Esperado: `{"status":"ok","version":"...","deploymentMode":"authenticated","bootstrapStatus":"ready"}`
|
|
|
|
- `status: ok` = OK
|
|
- `{"error":"Board access required"}` = AVISO (API responde mas sem auth — BD operacional)
|
|
- FALHA/timeout = CRITICO (servidor não responde)
|
|
|
|
### Check 7: Gateway MCPs
|
|
|
|
```bash
|
|
curl -s --max-time 5 https://gateway.descomplicar.pt/health 2>/dev/null || echo "FALHA"
|
|
```
|
|
|
|
- Responde = OK
|
|
- Timeout/falha = AVISO
|
|
|
|
### Check 8: Referencias orfas na BD
|
|
|
|
Budget policies e incidents a referenciar entidades inexistentes:
|
|
|
|
Invocar tool MCP: `mcp__paperclip__diag_budget_orphans`
|
|
|
|
- 0 orfaos = OK
|
|
- 1+ orfaos = CRITICO (causa "Agent not found" no dashboard, apagar com DELETE)
|
|
|
|
### Check 9: Instancias duplicadas
|
|
|
|
```bash
|
|
ss -tlnp | grep -E "310[0-9]" | wc -l
|
|
```
|
|
|
|
- 1 instancia = OK
|
|
- 2+ instancias = CRITICO (processos orfaos do pnpm, matar com `kill -9` os PIDs com PPID=1)
|
|
|
|
Detalhe dos processos:
|
|
```bash
|
|
ss -tlnp | grep -E "310[0-9]"
|
|
```
|
|
|
|
### Check 10: Porta vs Cloudflare Tunnel
|
|
|
|
```bash
|
|
TUNNEL_PORT=$(grep -A1 "clip.descomplicar.pt" ~/.cloudflared/config.yml | grep service | grep -oP ':\K[0-9]+')
|
|
ACTUAL_PORT=$(ss -tlnp | grep -E "310[0-9]" | head -1 | grep -oP ':310[0-9]' | tr -d ':')
|
|
echo "Tunnel: $TUNNEL_PORT | Servidor: $ACTUAL_PORT"
|
|
```
|
|
|
|
- Iguais = OK
|
|
- Diferentes = CRITICO (tunnel a apontar para porta errada, dashboard inacessivel)
|
|
|
|
### Check 11: Agentes sem permissoes bash
|
|
|
|
Invocar tool MCP: `mcp__paperclip__diag_agents_without_skip_permissions`
|
|
|
|
- 0 = OK
|
|
- 1+ = CRITICO (agentes vao ficar bloqueados ao executar bash — corrigir com `/clip-agent`)
|
|
|
|
### Check 12: Agentes sem heartbeat
|
|
|
|
Invocar tool MCP: `mcp__paperclip__diag_agents_missing_heartbeat`
|
|
|
|
- 0 = OK
|
|
- 1+ = AVISO (agentes nao acordam — podem nao processar issues)
|
|
|
|
### Check 13: Routine triggers com kind errado ou next_run_at NULL
|
|
|
|
Invocar tool MCP: `mcp__pap |