claude-plugins/infraestrutura/skills/easypanel-monitor/SKILL.md

---
name: easypanel-monitor
description: Monitorizacao de servicos EasyPanel -- estado de todos os servicos Docker, uso de recursos, disco e logs de erros com tabela resumo OK/DOWN/WARN.
---

# /easypanel-monitor - Monitorizacao EasyPanel

Verificacao rapida do estado de todos os servicos no EasyPanel (VM 101) com identificacao de problemas.

---

## Quando usar

- Verificacao diaria do estado dos servicos
- Apos alertas de servicos down
- Antes de deploys (validar estado actual)
- Diagnostico rapido de problemas de recursos

## Quando nao usar

- Para troubleshooting aprofundado de um servico especifico (usar `/easypanel-troubleshoot`)
- Para rollback de versao (usar `/easypanel-rollback`)
- Para deploy de servicos (usar `/easypanel-deploy`)

---

## Sintaxe

```bash
/easypanel-monitor              # Check completo (servicos + recursos + disco)
/easypanel-monitor quick        # Apenas estado dos servicos (OK/DOWN)
/easypanel-monitor <servico>    # Detalhe de um servico especifico (logs + stats)
```

---

## Servidor alvo

| Alias SSH | IP | Porta | Funcao |
|-----------|-----|-------|--------|
| **easy** | 5.9.90.70 | 22 | EasyPanel (VM 101) |

```javascript
mcp__ssh-unified__ssh_execute({
  server: "easy",
  command: "<comando>"
})
```

---

## Workflow completo

### Passo 1: Estado dos servicos (docker service ls)

```bash
docker service ls --format "table {{.Name}}\t{{.Replicas}}\t{{.Image}}\t{{.Ports}}"
```

**Classificacao:**
- **OK** - Replicas X/X (todas activas)
- **DOWN** - Replicas 0/X (nenhuma activa)
- **WARN** - Replicas parciais ou servico sem replicas esperadas

### Passo 2: Identificar servicos DOWN (0/N replicas)

```bash
docker service ls --format "{{.Name}} {{.Replicas}}" | awk '$2 ~ /^0\//'
```

Para cada servico DOWN, obter logs:

```bash
docker service logs <nome-servico> --tail 10 --no-trunc 2>&1
```

### Passo 3: Uso de recursos via API (preferido)

```bash
TOKEN=$(cat /etc/easypanel/.api-token)

# Stats do sistema — retorna estrutura aninhada
curl -s "http://localhost:3000/api/trpc/monitor.getSystemStats" \
  -H "Authorization: Bearer $TOKEN"
```

**Estrutura real da resposta (verificado 24-03-2026):**
```json
{
  "result": {
    "data": {
      "json": {
        "uptime": 3118351.41,
        "memInfo": {
          "totalMemMb": 32096.51,
          "usedMemMb": 16885.52,
          "freeMemMb": 15210.99,
          "usedMemPercentage": 52.61,
          "freeMemPercentage": 47.39
        },
        "diskInfo": {
          "totalGb": "192.7",
          "usedGb": "89.7",
          "freeGb": "103.0",
          "usedPercentage": "46.5",
          "freePercentage": "53.5"
        },
        "cpuInfo": {
          "usedPercentage": 13.65,
          "count": 6,
          "loadavg": [5.58, 6.34, 6.51]
        },
        "network": {
          "inputMb": 0,
          "outputMb": 0
        }
      }
    }
  }
}
```

**Campos a usar:**
- CPU: `cpuInfo.usedPercentage`
- RAM: `memInfo.usedMemPercentage` e `memInfo.usedMemMb`
- Disco: `diskInfo.usedPercentage` e `diskInfo.usedGb`

**Fallback via SSH (se API indisponivel):**
```bash
docker stats --no-stream --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.MemPerc}}\t{{.NetIO}}\t{{.BlockIO}}"
```

**Thresholds:**

| Metrica | OK | WARN | CRITICAL |
|---------|-----|------|----------|
| CPU | <70% | 70-90% | >90% |
| RAM | <70% | 70-85% | >85% |
| RAM absoluto | <512MB | 512MB-1GB | >1GB |

### Passo 4: Espaco em disco (via API ou fallback)

Usar `diskInfo` da resposta do passo 3. Fallback:

```bash
df -h / /var/lib/docker
```

**Thresholds:**

| Disco | OK | WARN | CRITICAL |
|-------|-----|------|----------|
| / | <70% | 70-85% | >85% |
| /var/lib/docker | <70% | 70-85% | >85% |

Verificar imagens Docker nao utilizadas:

```bash
docker system df
```

### Passo 5: Logs de erros recentes (servicos com problemas)

Para servicos DOWN ou WARN:

```bash
docker service logs <nome-servico> --tail 10 --no-trunc 2>&1 | grep -iE "error|fatal|panic|oom|killed|fail"
```

### Passo 6: Verificar tarefas falhadas

```bash
docker service ls -q | xargs -I {} docker service ps {} --format "{{.Name}} {{.CurrentState}} {{.Error}}" --filter "desired-state=shutdown" 2>/dev/null | grep -i "failed\|rejected\|error" | head -20
```

---

## Template de output

```markdown
## EasyPanel Monitor - [DATA]

**Servidor:** easy.descomplicar.pt (5.9.90.70)

### Estado dos servicos

| Servico | Replicas | Estado | CPU | RAM | Notas |
|---------|----------|--------|-----|-----|-------|
| descomplicar_api | 1/1 | OK | 2.3% | 128MB | - |
| descomplicar_n8n | 1/1 | OK | 5.1% | 256MB | - |
| descomplicar_db | 0/1 | DOWN | - | - | Connection refused |
| descomplicar_redis | 1/1 | WARN | 85% | 490MB | CPU elevado |

**Resumo:** X/Y servicos OK | Z DOWN | W WARN

### Disco

| Mount | Usado | Disponivel | % | Estado |
|-------|-------|------------|---|--------|
| / | 45G | 55G | 45% | OK |
| /var/lib/docker | 30G | 70G | 30% | OK |

Docker system: X imagens, Y containers, Z volumes (total: XGB)

### Alertas

**CRITICAL:**
- descomplicar_db: 0/1 replicas - servico DOWN
  Logs: `[erro relevante dos logs]`

**WARN:**
- descomplicar_redis: CPU a 85% (threshold 70%)

### Accoes recomendadas

1. [URGENTE] Investigar descomplicar_db: `/easypanel-troubleshoot db`
2. [IMPORTANTE] Monitorizar descomplicar_redis - CPU elevado
3. [MELHORIA] Limpar imagens Docker nao utilizadas: `docker system prune`
```

---

## Modo quick

Apenas passo 1 e 2. Output resumido:

```markdown
## EasyPanel Quick Check - [DATA]

| Servico | Estado |
|---------|--------|
| descomplicar_api | OK |
| descomplicar_n8n | OK |
| descomplicar_db | DOWN |

**X/Y OK** | Z alertas
```

---

## Modo servico especifico

Para `/easypanel-monitor <servico>`:

```bash
# Estado
docker service inspect <servico> --pretty

# Tarefas (historico)
docker service ps <servico>

# Logs (ultimas 50 linhas)
docker service logs <servico> --tail 50 --no-trunc 2>&1

# Stats do container
docker stats --no-stream --filter "name=<servico>"
```

---

## Integracao com API EasyPanel

A API e o metodo **preferido** (ver `/easypanel-api`). Os comandos Docker sao fallback.

```bash
TOKEN=$(cat /etc/easypanel/.api-token)

# Stats do sistema (CPU, RAM, Disco — ver estrutura no Passo 3)
curl -s "http://localhost:3000/api/trpc/monitor.getSystemStats" \
  -H "Authorization: Bearer $TOKEN"

# Stats Docker tasks (actual/desired replicas por servico)
# Resposta: {"serviceName": {"actual": 1, "desired": 1}, ...}
curl -s "http://localhost:3000/api/trpc/monitor.getDockerTaskStats" \
  -H "Authorization: Bearer $TOKEN"

# Projectos e servicos
curl -s "http://localhost:3000/api/trpc/projects.listProjectsAndServices" \
  -H "Authorization: Bearer $TOKEN"
```

**Nota de seguranca:** `inspectService` expoe variaveis de ambiente em texto limpo (incluindo passwords e tokens). Nunca incluir output bruto de `inspectService` em reports — sanitizar sempre.

---

## MCPs necessarios

- `ssh-unified` - Acesso ao servidor easy (obrigatorio)
- `mcp-time` - Data/hora para o report (obrigatorio)
- `desk-crm-v3` - Comentar resultado em tarefa (opcional)

---

## Anti-patterns

| Anti-pattern | Problema | Solucao |
|--------------|----------|---------|
| Ignorar servicos DOWN | Problemas acumulam | Sempre investigar com /easypanel-troubleshoot |
| Nao verificar disco | Disco cheio causa crash geral | Incluir df -h sempre |
| docker stats sem --no-stream | Bloqueia terminal | Sempre usar --no-stream |
| Ignorar tarefas falhadas | Crash loops nao detectados | Verificar desired-state=shutdown |
| Nao limpar imagens | Disco enche | docker system prune periodico |

---

## Checklist de execucao

- [ ] Conectar via SSH ao servidor easy
- [ ] docker service ls (estado de todos os servicos)
- [ ] Identificar servicos DOWN (0/N replicas)
- [ ] docker stats --no-stream (recursos)
- [ ] df -h (espaco em disco)
- [ ] docker system df (uso Docker)
- [ ] Logs de servicos com problemas (--tail 10)
- [ ] Tarefas falhadas (docker service ps --filter)
- [ ] Classificar cada servico: OK / WARN / DOWN
- [ ] Gerar tabela resumo
- [ ] Listar accoes recomendadas priorizadas
- [ ] Report formatado (Markdown)

---

## Skills relacionadas

| Skill | Quando usar |
|-------|-------------|
| `/easypanel-troubleshoot` | Diagnostico aprofundado de servico com problema |
| `/easypanel-rollback` | Reverter deploy falhado |
| `/easypanel-deploy` | Deploy de novo servico ou actualizacao |
| `/easypanel-validate` | Validacao pos-deploy |
| `/easypanel-api` | Referencia API tRPC |
| `/server-health` | Health check do servidor CWP (nao EasyPanel) |

---

*Skill v1.1.0 | 24-03-2026 | Descomplicar(r) | Fix: estrutura real monitor.getSystemStats (nested memInfo/cpuInfo/diskInfo)*

---

## Healing Log

Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar.

```jsonl
{"date":"","issue":"","fix":"","source":"user|auto"}
```

*Adicionar nova linha após cada erro corrigido.*