Saúde e monitoramento

O que sondar, o que acompanhar e o que as probes não conseguem informar.

Markdown

Probes

Endpoint	Responde	Use para
GET /health/live	200 {"status":"ok"} enquanto o processo atende requisições	Liveness
GET /health/ready	200 {"status":"ok"} quando o PostgreSQL responde; caso contrário, 503 {"status":"unavailable"}	Readiness: direcione tráfego somente depois que estiver pronto

livenessProbe:
  httpGet: { path: /health/live, port: 8080 }
readinessProbe:
  httpGet: { path: /health/ready, port: 8080 }
  timeoutSeconds: 5

Defina timeoutSeconds na probe de readiness. Se o PostgreSQL aceita conexões mas para de responder, a verificação pode esperar muito mais do que isso, e o timeout faz a probe falhar em vez de travar.

O que a readiness não verifica

A readiness verifica apenas o banco de dados. Ela não verifica se a chave de acesso é válida nem se a Unico está acessível. Uma chave de acesso errada aparece como erros no create, não como uma probe com falha. Inclua uma requisição de create real nas suas verificações pós-implantação.

Logs

Os logs são linhas JSON na saída padrão, com timestamp, severity, service e message. Falhas que envolvem um processo armazenado incluem o id dele. Erros cometidos pelo chamador (400, 404, 409, 422) não são registrados.

Uma inicialização saudável registra estas linhas, nesta ordem, entre as mensagens de conexão com o PostgreSQL (o version e o count do catálogo mudam a cada versão do catálogo):

{"severity":"INFO","timestamp":"2026-11-03T14:02:11.482913407Z","message":"attribute catalog loaded","service":"human-plugin","version":"2026-10-29.1","count":53,"url":"https://human-token-assets.unico.app/attribute-catalog.json"}
{"severity":"INFO","timestamp":"2026-11-03T14:02:11.731050212Z","message":"database schema ready","service":"human-plugin"}
{"severity":"INFO","timestamp":"2026-11-03T14:02:11.733418901Z","message":"human plugin listening","service":"human-plugin","addr":":8080"}

Sobre o que alertar

• Readiness falhando: o banco de dados está inacessível.
• Respostas 503 DATABASE_UNAVAILABLE ou 502 UPSTREAM_UNAVAILABLE repetidas às chamadas do seu back-end.
• Reinícios do container: um loop de reinício geralmente indica uma configuração ausente, um catálogo inacessível ou um problema no banco de dados. O log informa qual.
• Linhas de log de nível de erro, como creating process ou retrieving process.

O Human Plugin não exporta métricas. Use seu gateway ou service mesh para taxas de requisição e latência.