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

name, description

name	description
easypanel-monitor	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

/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)

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

---

Workflow completo

Passo 1: Estado dos servicos (docker service ls)

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)

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

Para cada servico DOWN, obter logs:

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

Passo 3: Uso de recursos via API (preferido)

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):

{
  "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):

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:

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:

docker system df

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

Para servicos DOWN ou WARN:

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

Passo 6: Verificar tarefas falhadas

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

## 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:

## 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>:

# 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.

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.

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

Adicionar nova linha após cada erro corrigido.