Pular para o conteúdo

Recursos

Explorador de logs

O engine armazena as linhas de log dos contêineres que o agente de node envia, conforme as regras de ingestão (ingestion.md), e o Deck as pesquisa em /deck/logs. Para lê-las é preciso a permissão logs.read, que os papéis embutidos viewer, editor e admin têm (veja identity.md). As rotas e os formatos estão no Adendo v0.21 do CONTRACT.md.

Como as linhas chegam

A coleta fica desligada até o chart ligá-la com telemetry.logs.enabled (padrão false); telemetry.logs.excludeNamespaces deixa namespaces inteiros de fora. Com ela ligada:

  • O orbit-node, o DaemonSet, acompanha /var/log/pods/<ns>_<pod>_<uid>/<container>/*.log no formato do CRI e junta as linhas parciais. Ele guarda as posições de leitura num emptyDir, então um reinício do contêiner não repete nem pula nenhuma linha. Um pod novo começa o log de cada contêiner na primeira linha escrita nos últimos 120 s (telemetry.logs.lookbackSeconds no chart; 0 começa no fim) e só fica pronto depois de posicionar todos os arquivos. Num rollout, o pod do node para, lendo cada arquivo até o fim ao parar, e só então o novo sobe: o que o node escreveu nesse intervalo chega uma vez e o restante desses 120 s chega duas vezes, com os timestamps originais. O mesmo vale para um pod apagado ou despejado fora de um rollout. Um node que escreve 100 linhas por segundo reenvia no máximo 12.000 linhas a cada pod novo, então tudo o que conta linhas (contagem de erros, volume) conta essas em dobro. Continua de fora: o que o node escreveu mais de 120 s antes da primeira passada do pod novo, quando ficou esse tempo todo sem pod; as linhas mais antigas de um contêiner que escreveu mais de 16 MiB nesses 120 s; uma rotação já comprimida quando o pod sobe, o que exige duas rotações do mesmo contêiner em 120 s; e um log cujas linhas não trazem o timestamp do CRI.
  • Ele lê o nível do JSON (level, severity, lvl, log.level, level_name, como palavra ou como o número do pino, do OTLP ou do Monolog), do logfmt (level=), dos prefixos do klog e de um token inicial INFO, WARN, ERROR, DEBUG, TRACE ou FATAL. Lê os IDs de trace e de span do JSON (trace_id, traceId, trace.id, span_id, spanId) ou de um traceparent do W3C.
  • Ele envia lotes OTLP/HTTP ao orbit-collector, que acrescenta os mesmos atributos do Kubernetes que acrescenta aos spans e exporta para o engine. Quando o collector está fora do ar, o agente descarta primeiro as linhas mais antigas e conta os descartes; nunca trava o node.

O orbit-node também lê arquivos de log que as aplicações escrevem no node; veja "Arquivos de log das aplicações" abaixo.

O serviço de uma linha é o service.name do recurso; na falta dele, o Deployment, o StatefulSet ou o DaemonSet dono do pod; na falta desses, o nome do contêiner.

Uma linha que chega sem nível recebe o que o próprio texto indica, que o engine lê no primeiro KiB: um prefixo klog, o status de uma linha de acesso HTTP (5xx ERROR, 4xx WARN, o resto INFO), level=, lvl= ou um "level" em JSON (também os números do pino), um nível entre colchetes ([WARN]), um nível seguido de dois-pontos no início da linha (o fail: do .NET) ou em maiúsculas (ERROR: depois do UTC [pid] do Postgres) ou depois de failed, a marca do Valkey e do Redis depois do horário (* INFO, # WARN, . e - DEBUG), ou uma palavra de nível em maiúsculas (o ] INFO [ do Kafka). Uma linha que continua a anterior do mesmo contêiner, recuada ou o STATEMENT: e o DETAIL: do Postgres, recebe o nível daquela linha. O histograma, as facetas, os termos severity:, os padrões e a análise contam esse nível, e a lista desenha o ponto dele como um anel. As regras de ingestão não: uma regra sobre o nível age sobre o nível que a própria linha traz, então uma linha sem nenhum continua guardada como antes. As linhas armazenadas antes de o engine começar a ler os níveis têm o nível lido do texto quando você as consulta, do mesmo jeito, então as barras, as facetas e os padrões de uma janela que passa por esse momento usam uma só fonte de nível. Uma linha cujo texto não indica nenhum aparece como "Sem nível".

O engine recusa um registro maior que 1 MiB, e todos os registros de um recurso cujos atributos codificados passam de 64 KiB, e os conta no sucesso parcial do OTLP; o resto da requisição é guardado.

Arquivos de log das aplicações

Algumas aplicações registram o log num arquivo, não na saída padrão. O caso para o qual isto foi feito é o Laravel: o Monolog escreve storage/logs/laravel.log, ou laravel-YYYY-MM-DD.log com o canal diário, e põe o stack trace de cada erro nas linhas seguintes. Dentro de um pod PHP, esse diretório é /var/www/storage/logs.

O arquivo chega ao node quando o pod monta esse diretório de um hostPath. Este pod guarda /var/www/storage/logs em /var/log/application/checkout-api no seu node:

yaml
spec:
  containers:
    - name: app
      volumeMounts:
        - name: app-logs
          mountPath: /var/www/storage/logs
  volumes:
    - name: app-logs
      hostPath:
        path: /var/log/application/checkout-api
        type: DirectoryOrCreate

O chart aponta o orbit-node para o lado do node dessa montagem, um diretório por serviço:

yaml
telemetry:
  logs:
    enabled: true
    files:
      - path: /var/log/application/{service}/laravel*.log

laravel*.log pega tanto laravel.log quanto o arquivo diário laravel-2026-10-28.log.

  • O caminho é um glob no node: * e ? correspondem dentro de um só diretório. {service} corresponde como * e vira o service.name da linha, então checkout-api acima é o serviço. {namespace} define k8s.namespace.name do mesmo jeito. As chaves service e namespace definem nomes fixos no lugar deles; uma fonte usa a chave ou o marcador, não os dois. Linhas sem nenhum dos dois ficam sem serviço.
  • O que é montado. O diretório antes do primeiro curinga (/var/log/application acima) é montado somente leitura no orbit-node, e nada mais. Ele não pode ser / nem um diretório do sistema (/etc, /proc, /sys, /dev, /run, /home, /root, /usr, /var/lib/kubelet, os diretórios dos runtimes de contêiner, /var/log/pods), nem ficar dentro de um, nem conter um: /var/log/*.log é recusado porque /var/log contém /var/log/pods. O chart recusa esse caminho ao renderizar, e o orbit-node o recusa de novo ao iniciar. Dê aos logs da aplicação um diretório só deles.
  • Entradas. Uma linha que corresponde a multilineStart abre uma entrada. O padrão corresponde ao cabeçalho do Laravel e do Monolog, [2026-10-28 15:00:00] production.ERROR: ou [2026-10-28T15:00:00.123456+00:00] app.INFO:. Qualquer outra linha ([stacktrace], um frame #0 /var/www/..., uma linha em branco, [previous exception]) se junta à entrada acima dela, até 256 KiB. A última entrada sai quando passa um segundo sem linha nova. Uma linha antes do primeiro cabeçalho vale sozinha. multilineStart: "^" faz de cada linha uma entrada.
  • Nível, horário e trace. O cabeçalho dá o nível: DEBUG; INFO e NOTICE como INFO; WARNING como WARN; ERROR; CRITICAL, ALERT e EMERGENCY como FATAL. Ele também dá o horário, e um horário sem fuso, o padrão do Laravel, é lido como UTC: uma aplicação cujo app.timezone não é UTC deve escrever o fuso. Uma linha sem cabeçalho fica com o horário em que foi lida. Os IDs de trace e de span vêm de um "trace_id" e de um "span_id" na linha, ou de um traceparent.
  • Atributos. service.name, k8s.namespace.name quando conhecido, k8s.node.name, log.file.path (o caminho no node) e log.source (file). Consulte-os como service:checkout-api ou @log.file.path:/var/log/application/checkout-api/*.
  • A leitura funciona como nos logs de contêiner, exceto que um pod novo começa no fim de cada arquivo: as posições no mesmo emptyDir, um arquivo que aparece depois (o diário de amanhã) desde o início, um rename (o padrão do logrotate) ou um copytruncate lidos até o fim, um reinício de onde parou, uma rotação comprimida em .gz enquanto o orbit-node estava parado lida de onde estava. exclude é um glob sobre o caminho inteiro cujos arquivos nunca são lidos; o * dele atravessa diretórios (exclude: "*.gz"). Links simbólicos não são seguidos, e nem um arquivo que não seja regular (um FIFO que uma aplicação põe no lugar é aberto sem esperar e ignorado) nem um nome com um caractere de controle são lidos. As linhas que todos os arquivos deixam incompletas ocupam juntas no máximo 16 MiB; além disso, a linha e a entrada incompletas de um arquivo saem como estão. O orbit-node lê como uid 65534 com o grupo 0, então um arquivo que só o dono lê fica de fora, e o log do próprio orbit-node avisa uma vez.
  • O controle de ingestão vale para essas linhas como para qualquer outra: uma exclusão sobre service:checkout-api com severity:<=INFO as descarta aqui também.

O que fica de fora:

  • Duplicatas. Uma aplicação que registra no arquivo e na saída padrão ou de erro, como o canal stack do Laravel com stderr nele, chega duas vezes: uma pelo log do contêiner e outra pelo arquivo. Fique com um dos dois.
  • Qual pod escreveu uma linha. Réplicas num mesmo node que compartilham o hostPath escrevem um só arquivo, lido uma vez. As linhas dele trazem o serviço, o namespace e o node, nunca o pod nem o contêiner, então os "Logs armazenados" de um pod as deixam de fora e "Linhas ao redor" mostra as linhas do arquivo.
  • Logs que nunca chegam ao node. Um pod cujo /var/www/storage/logs é um emptyDir, ou nenhum volume, guarda o arquivo dentro do pod, fora do alcance do orbit-node. Monte o diretório de um hostPath como acima, ou mande o log para o stderr (LOG_CHANNEL=stderr, ou stderr acrescentado ao canal stack) para que o log do contêiner o carregue. O orbit-node nunca monta /var/lib/kubelet/pods nem os diretórios do runtime para olhar dentro dos pods: eles guardam os Secrets de todos os pods.

A linguagem de consulta

Os termos são separados por espaços, e uma linha precisa atender a todos eles. Uma consulta vazia corresponde a tudo.

TermoCorresponde a
service:checkout-apiUma chave com exatamente esse valor, sem diferenciar maiúsculas
service:cart,checkoutUma vírgula entre valores aceita qualquer um deles (entre aspas, "a,b" é um valor só)
-namespace:kube-systemUm sinal de menos na frente inverte qualquer termo
pod:checkout-web-*Um asterisco corresponde a qualquer sequência de caracteres
severity:>=WARNOs níveis na ordem TRACE, DEBUG, INFO, WARN, ERROR, FATAL; >= e <= comparam
@log.iostream:stderrUm atributo da linha
@route:"GET /api/cart"Uma chave sem ponto também lê a chave da própria mensagem JSON, quando a linha não tem esse atributo
@status:503O status HTTP da linha: um atributo, o status ou status_code da mensagem JSON, ou o código de uma linha de acesso
shape:"http request"Uma linha cujo padrão é exatamente este (o mais e o menos de um padrão o escrevem)
timeoutUma palavra em qualquer ponto da mensagem, sem diferenciar maiúsculas
"connection refused"Uma frase em qualquer ponto da mensagem, sem diferenciar maiúsculas
/timeout after \d+ms/Uma expressão regular sobre a mensagem

As chaves são service, namespace, pod, container, node, severity, trace_id, span_id e shape. Uma chave que a linha não tem nunca corresponde, então trace_id:<id> só encontra linhas que têm um ID, e -trace_id:<id> mantém toda linha sem ele. Uma expressão regular roda no motor de regex do engine, que não tem look-around nem retrorreferências; (?i) no início ignora maiúsculas, e ela pode ter no máximo 1.024 caracteres. A página confere a sintaxe antes de enviar a consulta e mostra o erro onde você digitou; uma consulta que o engine ainda assim recusar volta como 400 com o motivo dado pelo próprio engine.

O engine pula os blocos em que um termo não pode bater. Uma palavra vai pelas letras, e um ID de letras e dígitos por um filtro dos IDs de cada bloco, então um ID que nenhuma linha tem responde sem ler as mensagens. Uma busca por um ID longo pula quase todo bloco sem ele; um com menos de 10 caracteres muitas vezes não tem o que consultar e lê as mensagens. Os valores mais frequentes de um atributo vêm das contagens de cada bloco, a não ser que a chave não esteja entre as 16 primeiras do bloco, ela tenha mais de 256 valores nele, mais de um a cada 4 registros ou cerca de mil contagens por stream e severidade, um limite de bucket atravesse o bloco ou a consulta julgue as próprias linhas. Segmentos gravados antes desses índices respondem igual, lendo mais.

Enquanto você digita, a barra sugere chaves e os valores que a janela contém. Enter roda a consulta do jeito que você digitou. Tab aceita a primeira sugestão; as setas escolhem outra para Enter ou Tab.

Como ler a página

  • A janela é o intervalo de tempo da barra superior, como em toda página do Deck. A consulta e a janela ficam no endereço (?q= e ?range=), então uma visão é um link que abre do jeito que estava.
  • O histograma empilha as linhas de cada intervalo por nível, com os erros no topo. Arraste sobre ele para aproximar um trecho, ou clique numa coluna para aproximar aquele intervalo; pelo teclado, as setas andam entre as colunas e Enter aproxima. O afastar da barra superior desfaz.
  • Abaixo do histograma, uma linha conta as linhas ERROR e FATAL da janela; um clique mostra só elas. Quando elas subiram, para 3 vezes a taxa anterior ou mais, e ficaram lá (a média delas a partir daquele intervalo se mantém nesse nível, em pelo menos 20 linhas), ela diz desde quando, o primeiro intervalo que se mantém (e os intervalos mais recentes ainda correm ao dobro da taxa), e um clique abre as linhas de erro a partir desse momento. A taxa anterior é a média interquartil dos intervalos anteriores, então um pico no começo da janela não esconde uma subida depois, e um pico que volta ao normal não conta como subida. Um surto que já passou (5 vezes a taxa no auge, pelo menos 20 linhas) aparece como "um surto de N erros às HH:MM, de volta à taxa anterior desde HH:MM", e um clique abre as linhas dele. Duas leituras do engine, junto com as da própria página, acrescentam os 3 serviços que mais as escreveram e a forma mais frequente delas, cada um com um clique para as suas linhas.
  • As facetas, como as do Datadog: serviço, nível (o pior primeiro), namespace, workload (deployment, statefulset ou daemonset), pod, contêiner, nó, tag da imagem, versão e status HTTP, as quatro últimas só quando alguma linha da janela as traz. O status vem de um atributo, da chave de status de uma mensagem JSON ou do código de uma linha de acesso, com 4xx e 5xx em cor; o engine lê todas as mensagens para isso, então ele aparece um instante depois da primeira tela. Cada uma conta pela consulta sem os seus próprios termos, então todos os valores continuam listados enquanto um está marcado. O clique num valor o marca e o junta aos já marcados (service:cart,checkout, qualquer um deles), ou o desmarca; "Só", ao lado, deixa apenas aquele valor, o sinal de menos o exclui, e "Todos", ao lado do nome de uma faceta filtrada, tira os termos dela da consulta. Uma faceta com mais de 10 valores tem uma caixa que os filtra, entre os 50 com mais linhas.
  • As linhas vêm das mais recentes para as mais antigas, 200 por vez, e "Carregar mais" continua de onde a página anterior parou. Só as linhas visíveis ficam na página, então milhares de linhas rolam tão rápido quanto algumas dezenas. Cada linha traz a cor do seu nível na borda esquerda, e uma linha ERROR ou FATAL ganha um tom vermelho. Uma linha se abre no lugar com os seus campos, a mensagem inteira (formatada quando é JSON, cada número como a mensagem o escreveu) e os atributos; quando eles ficariam abaixo da lista, a linha sobe para o topo dela. A linha aberta dá o seu horário completo, até o milissegundo, e há quanto tempo foi escrita, e avisa quando o engine leu o nível dela do texto. Cada campo e cada atributo simples tem um sinal de mais, que acrescenta key:value (ou @name:value) à consulta, e um de menos, que o exclui, e ao lado o ícone de gráfico conta as linhas por ele ao longo do tempo (veja a análise abaixo). Uma mensagem também lista os seus próprios campos, sem regra de parsing para configurar: as folhas de um objeto JSON como nomes com pontos (também depois de um prefixo, como um horário e um nível), ou os pares de uma linha logfmt (dois ou mais). O mais numa string JSON, como order_id, acrescenta a frase "\"<id>\"", o ID como uma string JSON inteira, então um ID de requisição dentro da mensagem filtra como um atributo e o engine pula todo bloco que não o contém. Uma string que um encoder JSON pode escapar (acentos, barras, aspas, <) acrescenta uma regex que a encontra como quer que a mensagem a guarde, como n\u00e3o para não. O mais num número ou num booleano acrescenta uma regex exatamente do que a mensagem escreveu sob essa chave (/"status"\s*:\s*502\s*[,}\]]/, e 12.0 continua 12.0), e o de um par logfmt uma regex do par inteiro (took=1 não encontra took=12); uma regex lê todas as mensagens da janela. Arrays aparecem sem o mais. Os códigos de cor de um terminal nunca aparecem: saem da lista, da linha aberta e das linhas ao redor, e ficam em "Copiar como JSON"; o mais num par colorido ainda encontra a linha, pois o engine lê a mensagem como foi guardada. "Trace deste log" fica no canto superior direito da linha aberta, onde a página do trace tem "Logs deste trace", para quem tem apm.read e numa linha com ID de trace; ele abre o trace no span da linha. Uma linha sem ID de trace diz isso e oferece os traces do pod dela nos 15 minutos antes e depois (numa linha de arquivo, que não tem pod, os do serviço). Uma linha lida de um arquivo diz que não tem pod. "Linhas ao redor" fica logo abaixo dele, e as linhas que ele lê aparecem logo depois da mensagem. Abaixo dos campos: "Linhas deste trace", "Copiar como JSON" e "Copiar link" (os cinco minutos até a linha sob a consulta, com a linha aberta, a lista terminando nela e as colunas e a quebra da página; um link cuja linha saiu da janela avisa, e uma janela para a qual você muda depois mostra as próprias linhas mais recentes), e depois o painel Relacionados: o pod, o node, o workload e o serviço da linha, com os seus logs, traces, eventos e alertas nos 15 minutos antes e depois.
  • "Linhas ao redor" mostra até 25 linhas antes e 25 depois da linha aberta, do mesmo pod e contêiner (do mesmo arquivo no mesmo node, ou do mesmo serviço, quando a linha não tem pod), das mais antigas para as mais recentes, rolada até a linha aberta, que fica marcada. Ele lê os 15 minutos antes e o minuto depois da linha e, quando mais de 1.000 linhas enchem esse minuto, só o segundo seguinte, para aparecerem as linhas logo depois dela.
  • "Padrões", ao lado de "Linhas", agrupa pela forma as linhas da consulta: números, ids, endereços e os valores de key=value viram *, e uma mensagem JSON conta pelo seu msg ou message com as chaves que dizem por que ela falhou ao lado, quando falhou (status 4xx ou 5xx, ou uma classe de erro): o status HTTP, o método, a rota (senão o caminho, com um segmento que tem dígito como *) e a classe do erro, então um 503 é uma linha separada, mostrada como http request status=503 route=GET /api/v1/archive/rehydrations, e as requisições que não falharam dividem a mensagem pura, qualquer que seja a rota. As linhas FATAL, ERROR e WARN vêm primeiro. Uma linha de acesso e um par status= também guardam o status HTTP. As 1.000 linhas mais recentes respondem primeiro; depois, uma leitura do engine conta todas as linhas da janela, uma linha por padrão, nível e serviço, como o Datadog os separa, para as 50 com mais linhas, com a tendência de cada uma na janela (uma leitura que fica sem tempo diz isso, e um engine sem essa leitura mantém a amostra, em que cada padrão mostra o pior nível e o serviço que mais o escreveu). Cada linha mostra a contagem, a fatia e a tendência (na cor do nível, de WARN para cima), o nível e o serviço, os seus * marcados, e se abre nas suas 20 linhas mais recentes da janela, cada uma com horário e nível, lidas pelos mesmos termos do mais, com os valores que cada * guardava nelas, dos mais frequentes para os menos. O mais mostra só as linhas dela: o nível, o serviço e shape:"<pattern>", que o engine confere com o padrão de cada linha, chaves incluídas, depois de pular os blocos sem a palavra mais longa do padrão. O menos deixa o padrão de fora com -shape:"<pattern>" e continua nos padrões, para o ruído sair um padrão por vez, e ok * nunca leva broken pipe junto, nem uma mensagem pura as suas requisições que falharam. A atualização automática da página espera enquanto os padrões estão na tela, e atualizar pela barra superior os conta de novo.
  • "Série temporal", "Ranking", "Tabela" e "Pizza", ao lado de "Padrões", contam ou medem todas as linhas que a consulta encontra na janela. "Mostrar" escolhe a medida: a contagem de linhas, a contagem única de um campo, a média, o mínimo, o máximo, a soma, o p50, p90, p95 ou p99 de um número que as linhas mais recentes trazem (um atributo, ou uma chave da própria mensagem JSON, como duration_ms), ou a taxa de erros (linhas ERROR e FATAL sobre todas). Uma medida ordena os valores do maior para o menor, aparece na sua unidade (ms ou s, KB ou MB, porcentagem) e fica no endereço (?m=p95:@duration_ms) e nas visões salvas; a tabela ganha a coluna dela e uma linha com todas as linhas, e até mais duas medidas como colunas, lidas com a primeira para toda linha ter um valor. A parcela só aparece ao lado de uma contagem ou de uma soma. A divisão é por um campo: o serviço (o padrão), o nível, namespace, pod, contêiner, node, padrão da mensagem ou qualquer atributo das linhas mais recentes, os seus 5, 8, 10, 25 ou 50 maiores valores (a pizza, 5 ou 8, uma cor para cada) e o resto como um só. É uma leitura do engine, GET /api/v1/logs/aggregate, a mesma de um painel de logs de dashboard. A série temporal empilha os valores por intervalo (arraste sobre ela para aproximar), o ranking e a pizza dão a fatia de cada valor, e a tabela acrescenta a tendência de cada valor na janela. Um mais ou um valor acrescenta o seu termo à consulta, e um menos o exclui. A visão, o campo e o limite ficam no endereço (?tab=, ?by=, ?top=) e nas visões salvas. Um índice reidratado não responde agregações, então mostra só linhas e padrões.
  • Acima das linhas, "Quebrar linhas" mostra até três linhas de cada mensagem, e "Colunas" escolhe o que fica entre o nível e a mensagem, até seis: os campos e qualquer atributo das linhas mais recentes (ou o ícone de coluna ao lado de um atributo de uma linha aberta). As colunas estreitam juntas para deixar à mensagem o seu espaço. As duas ficam no endereço (?wrap=1, ?cols=) e nas visões salvas.
  • Uma barra de consulta vazia oferece as suas cinco últimas buscas neste navegador, e / em qualquer ponto da página volta para a barra.
  • "Visões salvas", abaixo da barra de consulta, traz as visões da sua equipe para esta página: veja "Visões salvas" abaixo.
  • A lista é uma só parada no teclado: as setas (ou j e k), Page Up, Page Down, Home e End andam, Enter abre e fecha uma linha, Escape fecha. Com uma linha aberta, as setas abrem a linha anterior ou a próxima no lugar dela.
  • "Ao vivo" lê o que chegou a cada 2 s, e o histograma e as facetas a cada 16 s; uma aba oculta não lê nada. Ele espera enquanto você lê: com a lista rolada para longe da linha mais recente, uma linha aberta ou um texto selecionado, as linhas novas aguardam e são contadas, e "Retomar", ou voltar à linha mais recente, as traz. Linhas de nodes diferentes chegam fora de ordem, então cada leitura volta 15 s antes da linha mais recente. Uma linha mais atrasada que isso aparece depois de recarregar a página, assim como uma com mais de 5 minutos de atraso. Uma leitura retorna no máximo 500 linhas: quando chegam mais, a lista diz isso e mostra as mais novas de cada leitura, o resto desses 2 s aparece depois de recarregar, e uma consulta mais estreita mostra todas as linhas. Ao vivo, o cabeçalho dá as linhas por segundo do último intervalo completo do histograma.

Outras cinco páginas levam até aqui. O "Logs deste trace" da visão de trace abre trace_id:<id> sobre o trace e 15 minutos antes e depois; quando nenhuma linha da janela traz o id, a página diz isso, e um clique mantém a janela e troca o id pelo serviço. As "Principais mensagens de erro" de um serviço agrupam pela forma as 500 linhas de erro mais novas da janela (pelos pods do workload quando nenhuma linha cita o serviço), e uma linha abre aquela linha, com a consulta e a janela mantidas, e o trace dela ao lado. A lista de logs de um dashboard abre a linha dela: os cinco minutos até ela, com a consulta do painel, e a linha aberta (o line= do endereço a identifica). A aba de logs de um workload tem "Logs armazenados" ao lado do acompanhamento ao vivo, para namespace:<ns> pod:<workload>-* ou para o pod escolhido ali, com o que a busca tem; uma linha ao vivo que escreve um id de trace leva àquele trace. A página de um pod tem "Logs armazenados" para namespace:<ns> pod:<name>.

Facetas personalizadas

Qualquer atributo de uma linha de log ou de um span pode virar faceta para a equipe inteira. Abra a linha (ou um span no trace) e use o ícone de faceta ao lado do atributo: "Adicionar user_id como faceta". A partir daí o motor conta os valores do atributo conforme as linhas e os spans chegam, e o link "Agrupar gráfico" leva você ao explorador com o gráfico agrupado por ele. Adicionar ou remover uma faceta exige a permissão dashboards.write e a de leitura do sinal (logs.read ou apm.read), e a trilha de auditoria registra quem fez (facets.add, facets.remove).

  • O painel lateral mostra as facetas em "Facetas personalizadas", até 10 por explorador, cada uma com os valores mais frequentes e as contagens. Um valor adiciona @key:value à consulta (key:value na página de traces), o sinal de menos o exclui, o ícone de gráfico agrupa o gráfico pela faceta e o X a remove para todos. (other) e um valor cortado em 128 bytes mostram a contagem, mas não filtram.
  • "Gerenciar", ao lado do título, lista todas as facetas daquele explorador (no máximo 50), com quem criou e quando. Ali você escolhe até 10 para o seu painel, agrupa o gráfico por qualquer uma ou remove uma para a equipe. A sua escolha fica num cookie deste navegador, como o Datadog guarda as facetas ocultas por usuário; sem ela, o painel mostra as 10 primeiras criadas.
  • As contagens cobrem a janela inteira. Com uma consulta só de níveis (logs) ou de status (traces), o painel lê as séries da faceta. Com qualquer outro termo, uma leitura do motor conta todas as facetas do seu painel com a consulta inteira: cada linha que a consulta encontra, ou cada trace que casa, uma vez por trace que carrega o valor. Essa leitura cobre também os dados de antes da faceta. Quando uma leitura encontra mais de 4.096 valores distintos de um atributo (um id de usuário, por exemplo), o painel avisa que as contagens são limites inferiores.
  • O agrupamento desenha os valores com mais linhas ou spans na janela, no máximo 10, por passo do gráfico; na página de traces ele também mostra a latência média ou a p95. A p95 lê o heatmap de latência de cada valor em qualquer consulta, uma leitura por valor, e desenha a p95 das linhas de duração por coluna, como o histogram_quantile as lê nas páginas de APM: todos os traces do valor, e um filtro de duração não a restringe. Com uma consulta só de níveis ou de status, ele lê as séries da faceta. Com qualquer outro termo, a página de logs pede ao motor os 10 valores com mais linhas que casam na janela e as linhas de cada um por passo, numa só leitura. A de traces busca uma vez por valor: cada um recebe o total exato, distribuído no tempo conforme uma amostra uniforme de até 500 traces. Ela desenha primeiro os 10 valores mais frequentes dos traces amostrados e depois os 10 da leitura do motor feita para o painel, quando essa leitura chega e aponta outros valores.
  • Com um termo assim, o painel mostra na hora as contagens das linhas carregadas (ou dos traces amostrados) e as troca pelas do motor quando a leitura dele chega. Na página de logs essa leitura começa depois da do gráfico, para as duas não disputarem os núcleos do motor.
  • As séries usadas com uma consulta só de níveis ou de status começam quando a faceta é criada. Nada de antes entra ali, e o painel diz desde quando. A busca por @key:value continua lendo todas as linhas armazenadas, inclusive as antigas.
  • Cada faceta separa os seus primeiros 500 valores; os seguintes entram em (other) até o motor reiniciar. Um valor com mais de 128 bytes é cortado aí.
  • O motor guarda a lista em <data dir>/facets.json e grava as contagens nas séries orbit_facet_logs{facet,value,severity}, orbit_facet_spans{facet,value,status_code} e orbit_facet_span_seconds{facet,value,status_code}. Cada amostra traz o que chegou desde a anterior, então sum_over_time dá a contagem exata de qualquer janela.

Visões salvas

Uma visão salva é um nome, uma descrição opcional e o estado da página: a consulta, o intervalo de tempo, "Linhas" ou "Padrões", e as colunas e a quebra de linhas (na página de Traces: a consulta, o intervalo, traces raiz ou todos os spans, e as raízes em segundo plano). Um intervalo móvel, como os últimos 7 dias, continua móvel: a visão abre nos 7 dias que terminam quando você clica. O cluster continua sendo o seu.

  • Toda visão é da equipe. Quem lê a página a vê, com quem a criou e quem a editou por último. O dono, ou quem tem dashboards.write, renomeia, atualiza ou apaga; o resto da equipe salva uma cópia.
  • "Visões salvas (N)" abre a lista, com as favoritas primeiro. Um clique no nome abre a lista já filtrada. A estrela põe a visão ao lado da barra de consulta só para você.
  • O alfinete torna a visão a sua padrão naquela página: abrir Logs (ou Traces) sem consulta própria abre essa visão, em qualquer navegador em que você entrar. "Abrir sem visão" abre a página como ela vem. Uma página sem padrão não espera pela lista.
  • Com uma visão na tela, a barra mostra o nome dela e diz "alterada" quando você muda a consulta, o intervalo ou o agrupamento. "Atualizar visão" grava a mudança nela; "Salvar como nova" mantém as duas.
  • As visões que este navegador guardava antes da lista compartilhada aparecem uma vez em "Importar N visões salvas neste navegador"; a importação as grava como suas e apaga a cópia do navegador.
  • Se o orbit-api não responder a lista em 2 segundos, a barra avisa que as visões não carregaram; recarregue a página para tentar de novo.

As visões ficam no diretório de dados do orbit-api (views/<id>.json), então sobrevivem a um reinício, e cada gravação e exclusão entra na trilha de auditoria (view.save, view.delete, access.denied) com o nome e a página da visão, nunca a consulta. Com dados de demonstração elas ficam na memória, e as visões de um visitante da demo ficam com a sessão dele durante um dia, no máximo.

RotaQuemResposta
GET /api/v1/views?page=logs|traceslogs.read ou apm.read, conforme a página{views: [{id, page, name, description, query, owner, editor, createdAt, updatedAt, favorite, default, writable}]}, favoritas primeiro
POST /api/v1/viewsa permissão de leitura da página{page, name, description, query}; 201 com a visão
PUT /api/v1/views/{id}o dono ou dashboards.writeo mesmo corpo, a mesma página; 200
DELETE /api/v1/views/{id}o dono ou dashboards.write204
PUT /api/v1/views/{id}/prefsa permissão de leitura da página{favorite, default}, um ou os dois, só seus; 200

name tem de 1 a 120 caracteres, description no máximo 500, e query é o trecho de consulta da URL, de no máximo 8 KiB e sem caracteres de controle. Uma conta guarda no máximo 500 visões.

Pela API

Com a SESSION de um usuário que tenha logs.read (identity.md → "Entrar pelo shell"):

RotaResposta
GET /api/v1/logs/query?start&end&q&limit&cursor{records, next, truncated}, das mais recentes para as mais antigas; limit de 1 a 1.000, padrão 200
GET /api/v1/logs/histogram?start&end&q&buckets{step, buckets: [{t, counts}]}; buckets de 1 a 240, padrão 60
GET /api/v1/logs/facets?start&end&q&fields&limit{facets: {service: [{value, count}]}}; limit de 1 a 100, padrão 20. Até 10 key (nomes de atributo) acrescentam custom: {key: {values: [{value, count}], capped}}: os valores mais frequentes de cada chave com a consulta inteira, primeiro o atributo da própria linha, depois o do recurso

GET /api/v1/logs/aggregate?start&end&q&by&top&buckets&timeout conta o que os painéis de logs dos dashboards desenham (dashboards.md → "Painéis de logs"): as linhas que q pega na janela, no total e em buckets passos iguais (de 0 a 240; 0 é a janela inteira como um só), divididas por by (service, namespace, pod, container, node, severity, message ou @name) nos seus top valores (de 1 a 50, padrão 10). A resposta é {start, end, step, buckets, total, totals, groups: [{value, count, counts}], other, missing, distinct, capped, partial, ingest}; dividida por message, cada grupo acrescenta worst (o pior nível), service (o serviço que mais escreveu as linhas dele) e services (quantos o escreveram). other conta as linhas com outro valor e missing as sem o campo, cada um como {count, counts}; counts e totals só vêm com buckets. partial diz que o prazo ou o orçamento de varredura interrompeu a leitura (3 s e 4 GiB para uma hora ou menos, 6 s e 8 GiB até um dia, 10 s e 16 GiB além disso; timeout, de 100 a 10.000 ms, encurta o prazo). capped diz que uma thread de varredura encontrou mais de 1.024 valores da divisão. ingest é {seen, kept, since, levels, service}: as linhas que chegaram na janela e as armazenadas, pelos contadores do engine, restritas aos níveis da consulta, senão ao único serviço dela, senão a todas as linhas, a partir de since, o primeiro minuto contado, nunca antes de o engine iniciar. Uma linha que o receptor recusou por um campo malformado não entra em nenhuma das contagens: o controle de ingestão nunca a viu, e orbit_stack_log_records_rejected_total a conta. Um serviço além dos 500 de um minuto não tem contagem própria nesse minuto, então service fica de fora e as contagens são de todas as linhas; o nome de um serviço guarda seus primeiros 128 bytes nesses contadores e em /api/v1/logs/stats.

start e end são epoch em milissegundos. Para a próxima página, envie a mesma consulta com cursor igual a next, que é null na última página. Um registro traz ts (RFC 3339 com nanossegundos), tsNs, severity e severityNumber, severityInferred (verdadeiro quando o engine leu o nível do corpo), body, service, namespace, pod, container, node, traceId, spanId e attrs, e omite os campos que não tem.

bash
curl -fsS -G -H "Authorization: Bearer $ORBIT_AUTH_TOKEN" -H "X-Orbit-Session: $SESSION" \  --data-urlencode 'q=severity:>=WARN -namespace:kube-system' \  --data-urlencode "start=$(( ($(date +%s) - 3600) * 1000 ))" \  --data-urlencode "end=$(( $(date +%s) * 1000 ))" \  localhost:8080/api/v1/logs/query

Dados de demonstração

Com NEXT_PUBLIC_DEMO_MODE ligado, a página lê as linhas do próprio parque de demonstração: todos os workloads de orbit-prod-use1, nos formatos que esses programas escrevem (JSON do zap, Spring Boot, PostgreSQL, Elasticsearch, logfmt), armazenadas conforme as regras de ingestão salvas da demonstração, com o incidente das 14:26 no caminho de pagamentos e o promo-engine em crash loop. São inventadas, iguais a cada leitura, e o modo ao vivo continua depois do relógio fixo da demonstração.