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:
- Com "Manter todo trace com erro" ligado, um trace com qualquer span com falha é mantido.
- 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.
- 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.
- 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
{
"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 peloorbit-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
idde um filtro tem letras minúsculas, dígitos e hífens, único por sinal; onametem 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.
| Sinal | Chaves |
|---|---|
| Traces | name, kind, status, durationMs, attr.<span attribute>, resource.<resource attribute> |
| Logs | severity, 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:
| Filtro | O que ele pega |
|---|---|
| Health checks | attr.url.path ou attr.http.route correspondendo a (^|/)(health(z|check|-check)?|ready(z|ness)?|live(z|ness)?|ping)/?$, como dois filtros |
| Probes do Kubernetes | attr.user_agent.original contendo kube-probe |
| Scrapes do Prometheus | attr.url.path igual a /metrics |
| Arquivos estáticos | spans de servidor cujo attr.url.path termina numa extensão de script, folha de estilo, imagem ou fonte |
| Leituras bloqueantes do Redis | attr.db.system igual a redis e um nome de span como BLPOP, BRPOP ou XREAD |
| Descartar DEBUG e TRACE | severity no máximo DEBUG |
| Manter 1% de INFO | severity igual a INFO, mantido a 1% |
| Linhas de health check | um body que corresponde a GET ou HEAD nos caminhos usuais de health check |
| Linhas do kube-probe | um 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"):
| Rota | Resposta |
|---|---|
GET /api/v1/ingestion/rules | As regras |
PUT /api/v1/ingestion/rules | As 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|24h | O que chegou e o que foi armazenado, por serviço e por filtro, o armazenamento e a estimativa mensal |
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/rulesDados 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.