Pular para o conteúdo

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étricaTipoO que ela diz
*_provider_requests_total{tier,outcome}counterVolume 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_secondshistogram, com buckets até 300sQuanto 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 andamentogaugeRequisiçõ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: error dentro de uma resposta HTTP 200. Respostas SSE começam com um 200 antes 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.
  • /readyz devolvendo 503 é comportamento projetado; sozinho, não é um incidente. O orbit-api checa sua fonte e o nocturne; o nocturne checa a alcançabilidade do provedor (em cache, não a cada requisição). Um 503 significa "ainda não roteie para cá", e o Kubernetes age sobre isso corretamente sem a sua intervenção. Alerte sobre 503 sustentado (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_failed vinda de um mesmo endereço, ou de access.denied vinda 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 linhas audit do log do orbit-api, que carregam os mesmos campos. Veja audit.md.
  • O armazenamento de traces. No listener de métricas do engine: orbit_stack_spans_total{outcome} (um rejected em alta significa que há remetentes mandando spans sem ids ou traces grandes demais), orbit_stack_trace_head_bytes comparado com ORBIT_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_segments acima de zero e orbit_stack_trace_generator_dropped_total (conjuntos de labels de métricas de span que passaram do teto do gerador). Veja apm.md.
  • Alertas derivados. A página Alertas é o orbit-api avaliando seis regras sobre o cluster que ele lê; cada regra, e o que checar quando ela dispara, está em alerts.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):

ColunaDe onde vem
Componente, VersãoA 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.
ProntosRé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 hincrease(kube_pod_container_status_restarts_total[24h]) nos pods do componente, pelo nome. Fica vazio sem o kube-state-metrics.
Memória contra o requestO uso da página de workloads contra os requests dos pods.
Problemas 24 hO 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.
DiscoSó 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:

yaml
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-data

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

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

bash
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 WARN nomeando o risco, em toda inicialização, quando ORBIT_AUTH_MODE ou NOCTURNE_AUTH_MODE está em disabled. Esperado e correto em install/local-k3d.md e no loop de desenvolvimento padrão de install/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ída 0. Isso significa que uma requisição em andamento (normalmente um stream SSE do nocturne) sobreviveu ao ORBIT_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 (veja configuration.md).
  • Uma linha por requisição, sempre, inclusive para 401s e 429s. Um pico de linhas 401 vindas de uma única origem é alguém sondando credenciais (veja security.md).

Falhas de probe: triagem rápida

ProbeFalhar significaPrimeira 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 probePartida 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çãoUma 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:

  1. O pod do web em loop de restart porque alguém apontou a probe dele para /healthz. Só em imagens anteriores à mudança; as imagens atuais servem /healthz sozinhas (veja troubleshooting.md).
  2. Um stream SSE que chega todo de uma vez no fim, em vez de token a token.
  3. 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.