Operação
Operações
O que observar depois que a stack está rodando, como é a saturação vista de fora, como são os logs e o que significa a falha de cada probe. Para a verificação no momento da instalação ("isso subiu saudável?"), veja a seção "Verifique" do seu caminho de instalação; esta página trata da operação em regime.
O que observar
Os dois serviços de backend expõem métricas Prometheus em listener próprio (ORBIT_METRICS_ADDR /
NOCTURNE_METRICS_ADDR, default :9090; veja configuration.md). O CONTRACT.md
garante que existem três formatos de métrica; ele não fixa a string exata do nome da
métrica, que por convenção é prefixada por serviço (orbit_... / nocturne_...). Confirme
o nome literal do seu build com curl localhost:9090/metrics (com port-forward ou, no
compose, publicada diretamente). Construa alertas e dashboards sobre estas
três:
| Formato da métrica | Tipo | O que ela diz |
|---|---|---|
*_provider_requests_total{tier,outcome} | counter | Volume de requisições por tier de modelo (reasoning/fast) e por desfecho. Uma taxa crescente de outcome="error" contra um total estável aponta para o provedor, já que a carga não mudou. |
*_stream_duration_seconds | histogram, com buckets até 300s | Quanto tempo um stream SSE de chat roda. O default do NOCTURNE_TIMEOUT do nocturne é 120s: se o p99 aqui está subindo em direção a esse teto, os chamadores estão prestes a começar a dar timeout. |
| gauge de requisições em andamento | gauge | Requisições/streams concorrentes neste momento. Este é o seu sinal de saturação para planejamento de capacidade e ajuste de HPA: um gauge parado perto do teto prático de concorrência da sua contagem de réplicas significa que é hora de escalar o nocturne em vez de procurar um bug. |
Crie um alerta específico para dois comportamentos, porque um dashboard ingênuo de taxa de sucesso pode deixá-los passar:
- Essas métricas contam como falha um
event: errordentro de uma resposta HTTP200. Respostas SSE começam com um200antes de o modelo ter dito qualquer coisa; o desfecho que importa chega dentro do stream. Um dashboard que olha apenas para códigos de status HTTP vai ler uma integração de modelo quebrada como 100% saudável. /readyzdevolvendo503é comportamento projetado; sozinho, não é um incidente. Oorbit-apicheca sua fonte e onocturne; onocturnecheca a alcançabilidade do provedor (em cache, não a cada requisição). Um503significa "ainda não roteie para cá", e o Kubernetes age sobre isso corretamente sem a sua intervenção. Alerte sobre503sustentado (minutos, não um intervalo de scrape) e deixe passar a primeira ocorrência.
A pressão de recursos no nível do contêiner (throttling de CPU, memória chegando perto do
limite) está fora do /metrics desses dois serviços; observe-a do jeito comum:
kubectl top pods -n sreorbit, ou docker stats no compose. Todo contêiner do chart tem
limite de CPU bem acima do que usa (1 para o web, 4 para o orbit-stack), para que um
loop descontrolado não tome a CPU dos vizinhos no node; reduza um deles só depois de medir,
porque throttling em um processo que serve requisições aparece como latência de p99. Todo
contêiner também tem limite de memória, porque OOM é a única resposta honesta a um
vazamento: um pod web ciclando por OOM é um sinal real.
Com o Adendo v0.5 vieram mais três sinais, e nenhum deles é uma métrica:
- A trilha de auditoria. Uma rajada de
auth.login_failedvinda de um mesmo endereço, ou deaccess.deniedvinda de um mesmo usuário, é alguém tentando adivinhar senhas ou sondando o sistema. Filtre por isso em/deck/admin/audit(outcome:denied,action:auth.login_failed), ou crie um alerta sobre as linhasauditdo log doorbit-api, que carregam os mesmos campos. Vejaaudit.md. - O armazenamento de traces. No listener de métricas do engine:
orbit_stack_spans_total{outcome}(umrejectedem alta significa que há remetentes mandando spans sem ids ou traces grandes demais),orbit_stack_trace_head_bytescomparado comORBIT_STACK_TRACE_HEAD_BYTES,orbit_stack_trace_cut_failures_total(um segmento que não conseguiu ser gravado; o head mantém os spans dele e tenta de novo),orbit_stack_trace_skipped_segmentsacima de zero eorbit_stack_trace_generator_dropped_total(conjuntos de labels de métricas de span que passaram do teto do gerador). Vejaapm.md. - Alertas derivados. A página Alertas é o
orbit-apiavaliando seis regras sobre o cluster que ele lê; cada regra, e o que checar quando ela dispara, está emalerts.md.
A tabela Componentes
O /deck/observability fecha a seção do motor de telemetria com uma linha por controlador
desta instalação (cada Deployment, StatefulSet e DaemonSet com o label
app.kubernetes.io/part-of: sreorbit, sem a loja de demonstração), lida de
GET /api/v1/clusters/{id}/components (telemetry.query e estate.read):
| Coluna | De onde vem |
|---|---|
| Componente, Versão | A imagem do primeiro container: a última parte do repositório e a tag (ou os 12 primeiros dígitos hexadecimais do digest). Quando os pods prontos rodam outra versão que não a pedida pelo template, as duas, como "rodando → pedida": um upgrade preso nos pods antigos. |
| Prontos | Réplicas prontas contra as desejadas; num DaemonSet, os pods prontos contra todos os nodes do cluster, então aparece o node que ele não cobre. Fica âmbar, com a palavra de status da página de workloads, quando falta réplica, quando um rollout não terminou ou a versão pedida não roda, e com zero réplicas, a menos que um switch de feature o tenha estacionado ("estacionado"). |
| Reinícios 24 h | increase(kube_pod_container_status_restarts_total[24h]) nos pods do componente, pelo nome. Fica vazio sem o kube-state-metrics. |
| Memória contra o request | O uso da página de workloads contra os requests dos pods. |
| Problemas 24 h | O que o componente perdeu, contado nos próprios pods (pelo endereço ou pelo node da série): os spans e registros de log descartados pelo orbit-collector, os eventos do kernel perdidos pelo orbit-probe e as amostras descartadas pelo orbit-agent; ao lado, os retries de exportação ou de remote write. Um 4xx ou 5xx do engine descarta o lote sem retry, então a perda é a conta que importa. Fica vazio quando o engine não tem essa série para os pods dele. |
| Disco | Só no orbit-stack: o que o engine guarda (blocos de métricas, write-ahead logs e spill, segmentos de traces e de logs, pela conta dele mesmo) contra o PersistentVolume do claim e, quando isso cresceu no último dia, quantos dias ainda cabem nesse ritmo. |
O agent raspa o /metrics do orbit-collector (a porta metrics do Service do collector, a
porta de health 13133) e o do orbit-probe (a porta metrics do pod da sonda, 9112) como
job="sreorbit", com component igual a otel-collector e orbit-probe. A tabela não abre
nada nem dispara nada: é onde olhar antes de recorrer ao kubectl.
Todo claim do cluster, não só os do SRE Orbit, é vigiado como o disco de um node: o agent lê
o /metrics do kubelet uma vez por minuto (o kubelet atualiza as estatísticas de volume a cada
minuto ou dois) e guarda duas séries por claim, kubelet_volume_stats_used_bytes e
_capacity_bytes. Quando um claim montado por um pod em execução sobe de forma constante rumo ao
limite, o Nocturne prevê quando ele enche (achado volume_full, do detector filesystem_full: a
última meia hora alcança duas horas à frente, as últimas seis horas, um dia, e o pico de cada duas
horas no último dia, quatro dias, como o KubePersistentVolumeFillingUp do kube-prometheus, de modo que
a serra de um banco de dados ainda gera previsão; fica a previsão mais próxima, crítica abaixo de 30
minutos), e a lista de workloads, o workload, o namespace e o node mostram isso como uma linha
recolhida. Um claim com 97% ou mais e sem previsão à frente (volume_filled, crítico) aparece só na
página do Nocturne: quanto resta e desde quando, com a precisão de 5 minutos da leitura do dia, ou que
está assim há mais de 24 horas. Um volume só ReadOnlyMany não recebe escritas e fica de fora. O persistent_volumes.used_bytes do
Orbit SQL traz a mesma leitura. Um volume hostPath (local-path, a classe padrão do k3s) não tem
tamanho próprio: o kubelet o mede como o disco inteiro do node, então ele não recebe previsão nem
used_bytes, e as linhas de disco do próprio node o cobrem.
O diretório de dados: faça backup
O orbit-api guarda usuários, papéis, sessões, dashboards salvos, reconhecimentos de
alertas, leads do formulário de contato, a trilha de auditoria e a linha do tempo de mudanças sob ORBIT_DATA_DIR
(identity.md → "Onde o estado fica"). Fora o engine, nenhuma outra parte
do produto guarda estado. Perder esse diretório é perder todas as contas, todos os
dashboards salvos e o histórico de auditoria: faça backup dele do mesmo jeito que você faz
backup de um banco de dados.
Uma cópia feita com o orbit-api rodando é consistente: todo documento é substituído por
um rename depois de um fsync, então um snapshot tem a versão antiga ou a nova, nunca um
arquivo pela metade; e toda linha de auditoria recebe fsync no momento em que é gravada, enquanto
quem lê ignora uma última linha que ainda não termina em quebra de linha. Não é preciso
congelar nada antes da cópia.
Kubernetes, com components.orbit-api.persistence.enabled. Tire um snapshot do claim
<release>-orbit-api-data com os snapshots do seu driver CSI, ou com a ferramenta que você
já usa para volumes (Velero, o serviço de backup da sua nuvem). Com o snapshot controller
instalado, kubectl get volumesnapshotclass mostra o nome da classe que entra no lugar de
YOUR_SNAPSHOT_CLASS:
apiVersion: snapshot.storage.k8s.io/v1
kind: VolumeSnapshot
metadata:
name: orbit-api-data-manual
namespace: sreorbit
spec:
volumeSnapshotClassName: YOUR_SNAPSHOT_CLASS
source:
persistentVolumeClaimName: sreorbit-orbit-api-dataA imagem do orbit-api não tem shell nem tar, então kubectl cp e kubectl exec não
conseguem copiar o diretório para fora: tire um snapshot do volume em vez disso.
Kubernetes sem persistência. O diretório é um emptyDir e não há nada de que fazer
backup: todo usuário, toda sessão e toda linha de auditoria vão embora junto com o pod.
Ligue a persistência antes que alguém passe a depender do console (o values-prod.yaml e
o values-eks.yaml já ligam).
Compose. O volume nomeado é sreorbit_orbit-api-data. Para fazer o backup:
docker run --rm -v sreorbit_orbit-api-data:/data:ro -v "$PWD":/backup busybox \ tar czf /backup/orbit-api-data.tgz -C /data .Restaure com o orbit-api parado (docker compose --project-name sreorbit --env-file .env -f deploy/compose/docker-compose.yml stop orbit-api) e depois suba-o de novo:
docker run --rm -v sreorbit_orbit-api-data:/data -v "$PWD":/backup busybox \ sh -c 'rm -rf /data/* && tar xzf /backup/orbit-api-data.tgz -C /data'Um diretório restaurado traz as sessões dele de volta. Quando ORBIT_SESSION_SECRET não
está definida, ele também traz o session.key, e qualquer pessoa com o backup em mãos
poderia assinar tokens de sessão para as sessões que estão nele: trate os backups como o
Secret de credenciais, ou defina ORBIT_SESSION_SECRET para que a chave nunca fique no
volume. Trocar esse segredo, ou apagar o session.key, desloga todo mundo, e esse é o
jeito rápido de encerrar todas as sessões de uma vez.
Retenção da auditoria
ORBIT_AUDIT_RETENTION (default 90d) define por quanto tempo cada dia da trilha é
mantido; os arquivos diários são apagados inteiros, na inicialização e no primeiro evento de
cada novo dia em UTC. Ajuste o valor ao que a sua janela de revisão ou de compliance pede
(365d para uma revisão anual) e dimensione o volume a partir da sua própria trilha: rode
du -sh no diretório audit depois de uma semana representativa e extrapole para o
período de retenção. O mesmo volume guarda todo o resto do diretório, que é pequeno perto
da trilha. Tudo o que precisa durar mais do que a retenção, ou sobreviver a um
administrador, deve ir para o seu pipeline de logs: todo evento também vira uma linha audit
no log do próprio orbit-api.
Rollout do orbit-api
O orbit-api roda uma única réplica em qualquer caminho de instalação (um armazenamento de
escritor único). Com a persistência ligada, o chart usa Recreate: o pod antigo para antes
de o novo montar o claim, então um rollout é uma interrupção curta na API do console, e as
sessões sobrevivem a ele. Os manifestos puros vêm com um emptyDir e um rolling update, e
ali um pod novo sobe com o diretório vazio; monte um claim antes de depender dele
(install/kubectl.md).
Como são os logs
slog em JSON no stdout de todos os componentes, com o nível controlado por
ORBIT_LOG_LEVEL / NOCTURNE_LOG_LEVEL (debug/info/warn/error). O CONTRACT.md
garante uma linha por requisição carregando método, path, status e duração. A grafia
exata das chaves é detalhe de implementação: confirme-a contra o seu build
(docker compose logs orbit-api ou kubectl logs). Esta página não a fixa, porque o
próprio CONTRACT.md também não fixa.
Conheça estas três linhas de log antes de encontrá-las; cada uma parece alarmante e é o sistema se comportando corretamente:
- Um
WARNnomeando o risco, em toda inicialização, quandoORBIT_AUTH_MODEouNOCTURNE_AUTH_MODEestá emdisabled. Esperado e correto eminstall/local-k3d.mde no loop de desenvolvimento padrão deinstall/docker-compose.md. Ele nunca deveria aparecer em um fluxo de logs de produção; se aparecer,ORBIT_DEMO_DATA/o modo de autenticação está mal configurado para aquele ambiente. shutdown incomplete, registrado quando o desligamento gracioso estoura, com código de saída0. Isso significa que uma requisição em andamento (normalmente um stream SSE donocturne) sobreviveu aoORBIT_SHUTDOWN_GRACE/NOCTURNE_SHUTDOWN_GRACE. Isso não é reportado como falha de inicialização ou de crash. Não acione ninguém por causa disso isoladamente; se for frequente, o seu período de graça é mais curto do que a duração real de p99 dos seus streams, então aumente-o (vejaconfiguration.md).- Uma linha por requisição, sempre, inclusive para
401s e429s. Um pico de linhas401vindas de uma única origem é alguém sondando credenciais (vejasecurity.md).
Falhas de probe: triagem rápida
| Probe | Falhar significa | Primeira coisa a checar |
|---|---|---|
Liveness (/healthz em todo componente) | O próprio processo travou. | O restart já está acontecendo (é para isso que serve o liveness). Veja os logs imediatamente anteriores ao restart em busca de um panic/OOM. |
Readiness (/readyz nos serviços de backend; /healthz no web) | Uma dependência não está respondendo ou (no web) o próprio servidor não está aceitando conexões. | Para o orbit-api: o nocturne está no ar? Para o nocturne: o provedor configurado está alcançável? Nenhuma das duas checagens é por requisição: dê um instante ao cache antes de presumir que travou. |
| Startup probe | Partida a frio lenta, ainda não é falha: o failureThreshold generoso dela existe para absorver isso. | Só vale investigar se ela acabar falhando de vez; cheque o status do pull da imagem e a montagem do ORBIT_KUBECONFIG se ORBIT_DEMO_DATA=false. |
Nenhuma probe chega a rodar: o orbit-api sai já na inicialização | Uma configuração que ele recusa, nomeada na última linha de log dele. | O Adendo v0.5 acrescenta cinco: ORBIT_DATA_DIR sem permissão de escrita, ORBIT_ADMIN_USER sem ORBIT_ADMIN_PASSWORD_VERIFIER (ou o contrário), um verificador que ele não consegue interpretar, um ORBIT_SESSION_SECRET com menos de 32 bytes e um session.key do tamanho errado. |
Três modos de falha de probe específicos e já diagnosticados têm entradas próprias, com
sintomas exatos, em troubleshooting.md. Olhe lá antes de supor
que encontrou um novo:
- O pod do
webem loop de restart porque alguém apontou a probe dele para/healthz. Só em imagens anteriores à mudança; as imagens atuais servem/healthzsozinhas (vejatroubleshooting.md). - Um stream SSE que chega todo de uma vez no fim, em vez de token a token.
- Um rollback de Helm que não cai sobre os bytes que você testou.
Para onde ir em seguida
- Os formatos exatos de métrica/rota/limite citados acima:
api.md. - Modos de falha nomeados, com sintoma → causa → correção:
troubleshooting.md. - Procedimentos de upgrade e rollback por caminho de instalação:
install/helm.md,install/kubectl.md,install/docker-compose.md.