Pular para o conteúdo

Recursos

Controle de ingestão

O que o engine armazena dos spans e das linhas de log que chegam até ele, e portanto o que os exploradores de traces e de logs conseguem encontrar. As métricas de span, o grafo de serviços e os contadores de volume de logs contam tudo o que chega, digam o que disserem as regras, então os gráficos RED, o mapa de serviços e os alertas construídos sobre eles nunca mudam; as regras decidem só o que é armazenado, pesquisável e retido. As regras padrão mantêm tudo. A página é /deck/admin/ingestion, e mudar as regras exige a permissão settings.manage, que só o papel embutido admin tem (veja identity.md). As rotas e os formatos estão no Adendo v0.21 do CONTRACT.md.

O que as regras decidem

Um trace é mantido ou descartado por inteiro, igual em todos os spans: a decisão usa o hash do ID do trace, então um trace mantido a 10% também é mantido a 25%, e uma taxa menor mantém um subconjunto do que uma taxa maior mantém. Para cada trace, nesta ordem:

  1. Com "Manter todo trace com erro" ligado, um trace com qualquer span com falha é mantido.
  2. Com "Manter traces lentos" ligado, um trace cujo span raiz (ou, até a raiz chegar, o span mais longo) dura pelo menos o limite é mantido.
  3. Os filtros de exclusão rodam de cima para baixo contra o span raiz do trace (o span mais antigo, até a raiz chegar): o primeiro filtro ligado que se aplica decide, e o trace inteiro é mantido na taxa desse filtro.
  4. Todo o resto é mantido na taxa do seu serviço, ou na taxa padrão quando o serviço não tem uma própria. O serviço é o do span raiz (o do primeiro span, até a raiz chegar).

Uma linha de log é decidida sozinha: o primeiro filtro de logs ligado que se aplica a mantém na taxa dele, e uma linha à qual nenhum filtro se aplica é mantida na taxa padrão de logs. Uma linha que traz um ID de trace é amostrada por esse ID, então segue o seu trace.

O engine aplica uma mudança salva na hora, sem reiniciar, e guarda as regras no seu volume.

O documento de regras

json
{
  "version": 7,
  "updatedAt": "2026-09-28T03:10:00Z",
  "updatedBy": "ana@example.com",
  "traces": {
    "defaultRate": 0.25,
    "keepErrors": true,
    "keepSlowerThanMs": 2000,
    "services": [{ "service": "payments-api", "rate": 1.0 }],
    "exclusions": [
      {
        "id": "health-checks",
        "name": "Health checks",
        "enabled": true,
        "service": "*",
        "conditions": [{ "key": "attr.url.path", "op": "regex", "value": "(^|/)(health(z|check|-check)?|ready(z|ness)?|live(z|ness)?|ping)/?$" }],
        "keepRate": 0.0
      }
    ]
  },
  "logs": {
    "defaultRate": 1.0,
    "exclusions": [
      {
        "id": "debug-trace",
        "name": "Drop DEBUG and TRACE",
        "enabled": true,
        "service": "*",
        "conditions": [{ "key": "severity", "op": "lte", "value": "DEBUG" }],
        "keepRate": 0.0
      }
    ]
  }
}
  • version é do engine: começa em 1 e cresce um a cada salvamento aceito. updatedBy é o e-mail do usuário logado que salvou, preenchido pelo orbit-api.
  • Uma taxa é um número de 0 a 1 (a página mostra porcentagens). keepSlowerThanMs é 0 para desligado, senão de 1 a 3.600.000.
  • No máximo 500 taxas por serviço, cada serviço citado uma vez, e no máximo 50 filtros por sinal. O id de um filtro tem letras minúsculas, dígitos e hífens, único por sinal; o name tem até 80 caracteres; service é o nome exato de um serviço ou *; o filtro tem de 1 a 10 condições, e todas precisam valer.

Uma condição é uma chave, um operador e um valor. Uma chave que o item não tem nunca corresponde, e isso inclui neq.

SinalChaves
Tracesname, kind, status, durationMs, attr.<span attribute>, resource.<resource attribute>
Logsseverity, body, service, namespace, pod, container, node, attr.<attribute>

Os operadores são eq, neq, contains, regex, in (o valor é uma lista separada por vírgulas), gte e lte. gte e lte comparam números, e níveis para severity, na ordem TRACE, DEBUG, INFO, WARN, ERROR, FATAL. O nível de uma linha é o número de severidade dela ou, sem ele, o texto de severidade lido como o explorador de logs o lê (notice como INFO, err como ERROR, critical como FATAL). Um regex roda no motor de regex do engine: sem look-around, sem retrorreferências, com no máximo 1.024 caracteres.

Como usar a página

A faixa de destaques lê os últimos 5 minutos, a última hora ou o último dia: spans e linhas de log armazenados por segundo contra o que chegou, o armazenamento que um mês disso ocupa e a parcela economizada em relação a manter tudo.

A aba Traces define a taxa padrão, as duas regras de manter, uma taxa por serviço ao lado do que cada serviço envia e armazena (uma caixa vazia significa a padrão) e os filtros de traces. A aba Logs define a taxa padrão de logs e os filtros de logs, lista o que cada serviço envia e armazena e mostra a retenção, que cabe ao engine definir e aqui é somente leitura. Cada aba oferece os seus filtros comuns com um clique:

FiltroO que ele pega
Health checksattr.url.path ou attr.http.route correspondendo a (^|/)(health(z|check|-check)?|ready(z|ness)?|live(z|ness)?|ping)/?$, como dois filtros
Probes do Kubernetesattr.user_agent.original contendo kube-probe
Scrapes do Prometheusattr.url.path igual a /metrics
Arquivos estáticosspans de servidor cujo attr.url.path termina numa extensão de script, folha de estilo, imagem ou fonte
Leituras bloqueantes do Redisattr.db.system igual a redis e um nome de span como BLPOP, BRPOP ou XREAD
Descartar DEBUG e TRACEseverity no máximo DEBUG
Manter 1% de INFOseverity igual a INFO, mantido a 1%
Linhas de health checkum body que corresponde a GET ou HEAD nos caminhos usuais de health check
Linhas do kube-probeum body que contém kube-probe

"Adicionar filtro" abre o construtor: um nome, o serviço a que se aplica, a parcela do que se aplica que ele mantém e as suas condições. Um filtro é ligado e desligado no lugar, e a sua ordem muda ao arrastá-lo ou com as suas setas; o primeiro que se aplica vence, então a ordem importa. Um filtro salvo mostra o que descartou na janela das estatísticas.

Prever impacto pede ao engine que reproduza a última hora de dados armazenados sob o rascunho, por serviço e por filtro. Ela só consegue mostrar o que esses dados perderiam: um item descartado antes de ser armazenado não está lá para ser contado, então uma taxa maior não mostra ganho nenhum.

Revisar e salvar mostra o rascunho como uma lista de alterações. O salvamento envia If-Match com a versão que a página leu; se outra pessoa salvou nesse meio-tempo, o engine recusa com 412, e a página carrega a versão dessa pessoa e avisa que o rascunho não foi salvo. Um salvamento aceito fica registrado na trilha de auditoria como ingestion.rules.update com um resumo de uma linha da mudança, e a página tem um link para esses eventos.

A aba Métricas

As regras cobrem spans e linhas de log; a aba Métricas mostra onde estão as séries de métricas, só para leitura, a partir do head do engine agora: as séries ativas, as séries criadas na última hora (increase(orbit_stack_head_series_created_total[1h]), o churn), as dez métricas com mais séries com a fatia de cada uma no total e as dez labels com mais valores. Uma métrica que sobe na primeira lista, ou uma label como pod ou id no topo da segunda, é onde uma explosão de cardinalidade começa. Ela lê o GET /api/v1/status/tsdb e o GET /api/v1/query pelo orbit-api (telemetry.query); sem essa permissão, ou com dados de demonstração, a aba não aparece. Regras que descartam séries de métricas ainda não fazem parte desta página.

Pela API

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

RotaResposta
GET /api/v1/ingestion/rulesAs regras
PUT /api/v1/ingestion/rulesAs regras armazenadas; 412 quando o If-Match cita uma versão antiga, 400 com o campo quando um valor é recusado
POST /api/v1/ingestion/preview{window, traces: {spans, keptSpans, byService, byRule}, logs: {records, keptRecords, byRule}} para um rascunho
GET /api/v1/ingestion/stats?window=5m|1h|24hO que chegou e o que foi armazenado, por serviço e por filtro, o armazenamento e a estimativa mensal
bash
curl -fsS -H "Authorization: Bearer $ORBIT_AUTH_TOKEN" -H "X-Orbit-Session: $SESSION" \  localhost:8080/api/v1/ingestion/rules > rules.json# edit rules.json, then save it against the version readcurl -fsS -X PUT -H "Authorization: Bearer $ORBIT_AUTH_TOKEN" -H "X-Orbit-Session: $SESSION" \  -H "Content-Type: application/json" -H "If-Match: $(jq .version rules.json)" \  --data @rules.json localhost:8080/api/v1/ingestion/rules

Dados de demonstração

Com NEXT_PUBLIC_DEMO_MODE ligado, a página mostra as regras do parque de demonstração (versão 7) e o seu tráfego: todos os serviços de orbit-prod-use1, as suas probes, scrapes e arquivos estáticos, e as suas linhas de log. A prévia é calculada na própria página a partir desse tráfego, do mesmo jeito que o engine a reproduziria, e um salvamento fica na aba do navegador: nada é enviado e nada é aplicado.