Logs, métricas e saúde

Um NNS em produção tem três superfícies de leitura. Nenhuma delas é a porta do Actuator.

o que você quer	onde	porta
o que aconteceu	log em linha JSON, no stdout do container	—
quanto está consumindo	/metrics, em texto Prometheus	NN_METRICS_ADDR (:9090)
o pod pode servir?	/live e /ready	a porta de serviço (:8080)

Logs

Todo registro sai como uma linha JSON, no mesmo formato do runtime da plataforma:

{"time":"2026-10-08T14:03:11.482Z","level":"info","msg":"sample: item criado","component":"sample","release_id":"sample@0.1.0","item_id":"it_7","request_id":"…","correlation_id":"…"}

chave	o que é
time, level, msg	as chaves fixas do contrato
component	o componente que registra
release_id	a release que está rodando
pares chave-valor	o contexto que você adiciona
ids de correlação	no fim da linha
trace_id	quando há traço de entrada
logger	só em registro que não é do SDK
error, exception, stack	em exceção; a pilha sai sem as mensagens

Você escreve com SLF4J, e o SDK cuida do formato:

log.atInfo().addKeyValue("item_id", id).log("sample: item criado");

Toda linha passa pela redação central: chave sensível, valor com forma de segredo e o texto de exceção são redigidos. Isso vale inclusive para os registros do framework e do servidor — o formato é do serviço inteiro, não só do seu código.

Correlação é obrigatória: request_id, correlation_id e action_id atravessam a requisição do início ao fim. Se você perder a correlação em código assíncrono, o diagnóstico do operador fica impossível — é o primeiro item de qualquer investigação.

Ler os logs de um pod, no cluster:

kubectl logs -n nns-sample deploy/nns-sample-0-1-0 -f

Métricas

As métricas são do Micrometer, injetado no serviço. A porta de management serve só GET/HEAD /metrics, em texto Prometheus:

kubectl port-forward -n nns-sample svc/nns-sample-0-1-0 9090:9090
curl -s localhost:9090/metrics | head

série	o que diz
http.server.request.duration	a latência das requisições, com o rótulo do método da rota
nns.periodic.runs{task, outcome}	quantas vezes cada tarefa periódica rodou, e como terminou

O contrato são os nomes e os rótulos que saem nesse texto — e não o contrário: nada é prometido pela porta de serviço. Nada do Actuator aparece na 8080.

Saúde

kubectl port-forward -n nns-sample svc/nns-sample-0-1-0 8080:8080
curl -i localhost:8080/live
curl -i localhost:8080/ready

• /live responde se o processo está vivo; não olha dependência.
• /ready responde se o pod pode servir. Os checks rodam em paralelo, 2 s cada, e um check que não termina no prazo deixa o pod unready.

Um check do /ready é um HealthIndicator comum, declarado como bean — o nome do bean é o nome do check. Os checks db e schema vêm do SDK quando o serviço declara banco. Para levar a mensagem ao corpo:

NnsHealth.degraded("fila de itens acima do limiar");
NnsHealth.unavailable("banco inacessível");

Só dependência local no /ready. Dependência remota fora do ar não derruba o pod. E o /ready sob carga direta estoura o prazo dos checks: ele é alcançável só pelos probes (a NetworkPolicy não abre a 8080 para o resto do cluster) — não o use como página de diagnóstico.

O estado da release, que não é do pod

O que você lê acima é o processo. O estado da release (validada, implantando, ativa, substituída, desabilitada) e as fases da operação são do Module Manager:

./nnconsolew modules show <id>
./nnconsolew modules show <id> <release>

Durante um deploy, um FAILED_RECONCILABLE indica que repetir o deploy retoma do checkpoint. Os estados e as fases estão em Upgrade e rollback.

O que o módulo não faz

• Não publica superfície anônima de métrica ou de diagnóstico: as superfícies públicas da plataforma são dela.
• Não manda telemetria por OTLP: o traço vem do traceparent de entrada e o trace_id aparece na linha de log.
• Não inventa stack de observabilidade própria. A do NNS é esta, e ela é contrato.