Pular para o conteúdo

Referência

Engine Orbit Stack

orbit-stack é o quarto contêiner: um binário que recebe remote-write do Prometheus, guarda amostras em um write-ahead log e em um head na memória, sela o head em intervalos regulares em blocos colunares imutáveis comprimidos com zstd, funde blocos pequenos em blocos maiores em segundo plano e responde a PromQL. Desde o Adendo v0.5, ele também recebe traces do OpenTelemetry por OTLP/HTTP, guarda-os em segmentos próprios e deriva deles métricas de span ("Traces" abaixo). O orbit-api o lê por trás de GET /api/v1/query_range, dos dashboards e das rotas de APM; o painel ad hoc do Deck o alcança do mesmo jeito; os seus clusters fazem push para ele. Ele está especificado no Adendo v0.3 do CONTRACT.md e medido em benchmark.md.

O que ele armazena, e como

  • Uma requisição de escrita cai primeiro no WAL, depois no head. O WAL passa por fsync em um timer de um segundo, então uma queda de energia perde no máximo esse intervalo, como no Prometheus. Uma escrita que o log não consegue aceitar (disco cheio, erro de dispositivo) recusa a requisição que a encontrou, então o remetente a envia de novo, enquanto os registros já aceitos ficam pendentes para o próximo flush; o log é reaberto e cortado de volta até o seu último registro inteiro, de modo que um registro truncado nunca encerra o replay antes da hora. A falha não é permanente: assim que houver espaço de novo, a próxima escrita passa, sem restart.
  • O WAL grava os labels de uma série uma única vez por arquivo. O primeiro registro que traz uma série a define e lhe dá uma ref; todo registro seguinte a nomeia só por essa ref, do jeito que funcionam os registros de série do Prometheus. As amostras vêm coluna por coluna: as refs como deltas, a contagem de amostras de cada série, cada timestamp como delta em relação à amostra anterior e cada valor em XOR com o último valor que aquela série registrou, de modo que um valor que não se mexeu quase não custa nada. O registro é comprimido com zstd no nível mais rápido, com uma janela de 512 KiB. As refs pertencem a um arquivo e a um escritor: o primeiro registro de um escritor em um arquivo abre uma época, e um replay esquece todas as refs que conhece ao encontrar uma, então um processo que acrescenta registros a um log depois de um restart não precisa de nada do processo anterior, e um arquivo rotacionado é reprocessado sozinho. Uma requisição recusada porque o flush dela falhou tira da tabela as séries que definiu, então nenhum registro posterior pode nomear uma série cuja definição nunca chegou ao arquivo. Os labels são comparados de forma exata, e dois conjuntos de labels com o mesmo hash são duas séries. Registros gravados por um build mais antigo (snappy, conjuntos de labels completos em todo registro) continuam sendo reprocessados, inclusive em um arquivo que mistura os dois formatos, então um log existente é atualizado sem nenhuma etapa de migração.
  • No Linux, todo fsync do WAL é seguido de POSIX_FADV_DONTNEED sobre as páginas inteiras que ele sincronizou, de modo que só a página que ainda recebe dados fica no page cache; um arquivo rotacionado é descartado inteiro, e o mesmo vale para um arquivo depois do replay. Nada além de um replay lê o log, e as páginas dele eram a maior parte do que se cobrava do cgroup de um engine ocupado.
  • O head mantém um chunk aberto com codificação Gorilla por série (timestamps em delta de delta, valores em XOR) em um buffer fixo de 131 bytes que nunca cresce; com a sua contabilidade, o chunk aberto é uma alocação única de 160 bytes, e o registro da série que aponta para ele tem 64 bytes. O chunk é fechado quando restam menos de 20 bytes no buffer, o máximo de que uma amostra pode precisar: isso dá cerca de 12 amostras de um float ruidoso de precisão total, e até ORBIT_STACK_HEAD_CHUNK_SAMPLES (120) para uma constante, o que vier primeiro. A codificação de timestamps tem um código que a do Prometheus não tem: cinco bits que significam "o mesmo delta do penúltimo", que é o que custa um deslocamento de agenda do scraper seguido da sua correção, onde o esquema simples gasta dois códigos mais largos. O formato só existe no head (o spill é reconstruído a partir do WAL a cada inicialização e os blocos usam um codec próprio), então o código extra não tem custo de compatibilidade.
  • Um chunk fechado vai para o spill: arquivos de segmento compartilhados, só de acréscimo, sob chunks_head/ no diretório de dados, nos quais os chunks são empacotados um atrás do outro na ordem em que fecham, como os head chunks do Prometheus. Cada registro de chunk traz um crc32c, o comprimento do corpo, a contagem de amostras e um back-link para o chunk anterior da série, e depois o corpo: cerca de 11 bytes de cabeçalho por chunk. Um back-link só aponta para trás, então uma cadeia de chunks não pode entrar em loop, e uma série não guarda nada na memória além da ref do seu chunk mais novo. Assim o heap segura um chunk aberto por série e nenhum dos fechados da janela, e um head cheio não cresce com ORBIT_STACK_BLOCK_DURATION. Um segmento recebe até 128 MiB de chunks, e um novo começa quando ele enche; o arquivo cresce conforme os chunks são gravados, então o diretório de dados guarda exatamente os bytes escritos e nunca o teto. Os segmentos são escritos com pwrite e lidos com pread, um pread por chunk, nunca mapeados: uma página mapeada que uma leitura traz para a memória é cobrada do resident set do processo, então um selamento que lia o spill por um mapeamento subia o RSS no tamanho da janela. Toda leitura verifica o crc32c de um chunk antes de confiar no cabeçalho ou de decodificar o corpo: um chunk que falha nessa verificação faz a consulta falhar, com a série nomeada, em vez de sumir com aquela série dentro de um 200. Ao contrário das do WAL, as páginas do spill não são descartadas do page cache: o selamento lê todas elas em ordem de label, o que, a partir do disco, seria uma leitura aleatória por chunk.
  • O spill não é um registro de durabilidade. Toda amostra chega ao write-ahead log antes de chegar a um chunk, e um selamento apaga o log rotacionado só depois que o bloco dele caiu em disco, então o log sempre guarda pelo menos o que o spill guarda. Na inicialização o diretório de spill é, portanto, apagado por completo e o replay o escreve de novo: um segmento que um crash deixou pela metade não precisa de reparo, e nenhum segundo índice em disco pode discordar do log. Um log rotacionado que o engine não consegue ler é deixado onde está e nomeado no erro com que o Open falha; um log que termina no meio de um registro é reprocessado até aquele byte, registrado em WARN e contado em orbit_stack_wal_truncations_total. O selamento constrói o bloco a partir dos chunks do spill mais os abertos e devolve os segmentos assim que o bloco cai em disco, então uma janela já selada não deixa nada em disco além do bloco; uma consulta que estava a caminho daquele head ainda o lê: os arquivos só vão embora quando aquela consulta termina. Um selamento cujo bloco não consegue ser escrito mantém o head, então a janela continua consultável, e o próximo ciclo escreve o bloco de novo.
  • A cada ORBIT_STACK_BLOCK_DURATION (default 2 h) o head é selado: cada série é recodificada coluna por coluna (timestamps como varints de delta de delta; valores como deltas inteiros quando todo valor é inteiro ou decimal com até quatro casas, e XOR caso contrário), as colunas são concatenadas e o bloco é comprimido com zstd. O bloco cai em um diretório temporário e é renomeado para o lugar definitivo, de modo que um crash deixa um bloco inteiro ou nenhum, e o WAL rotacionado é reprocessado na próxima inicialização se o selamento não tiver terminado. Antes da renomeação, o meta.json do bloco nomeia os logs rotacionados a partir dos quais ele foi selado; um log que um bloco em disco nomeia é apagado na inicialização em vez de reprocessado, então um crash entre a chegada de um bloco e a remoção do seu log não sela mais a mesma janela duas vezes. Dois blocos com a mesma janela, as mesmas contagens de séries e de amostras e arquivos de índice e de chunks idênticos byte a byte são um bloco só: o Open mantém o que foi criado primeiro.
  • Blocos adjacentes são compactados em segundo plano, do jeito que o Prometheus organiza os seus blocos em níveis. O índice de um bloco repete os labels de todas as séries, então, com uma duração de bloco curta, os índices são a maior parte do disco e a maior parte do trabalho de uma consulta longa. A compactação monta blocos de três vezes a duração do bloco, depois três vezes isso, até um décimo da retenção (31 dias sem retenção); com os defaults, blocos de 2 h e 15 dias, isso dá 6 h e 18 h. Um grupo de blocos só é fundido quando o seu intervalo está fechado (a amostra mais antiga do head já passou do fim dele, então nenhum bloco que comece dentro dele ainda está por vir), no máximo 16 blocos por fusão e uma fusão por vez. O bloco fundido é escrito em um diretório temporário e relido por inteiro antes de qualquer uso: o checksum do índice, o checksum de cada frame, cada série contra a sua entrada no índice em ordem de tempo estrita e um hash de todo o fluxo escrito. Só então ele é renomeado para o lugar definitivo e trocado pelos seus pais em um único passo; os diretórios dos pais vão embora quando nenhuma consulta os segura mais. O bloco fundido nomeia os seus pais no próprio meta.json, então um crash entre a troca e a remoção deles é concluído pelo próximo Open. Blocos que se sobrepõem são fundidos com uma amostra por timestamp, e vence o bloco que vem primeiro na ordenação, como em uma consulta. Uma fusão que falha deixa os seus blocos como estavam, é contada em orbit_stack_compaction_failures_total e mantém aquele grupo fora de todo planejamento até o próximo restart.
  • Um bloco v3 faz checksum do índice e dos frames. O índice carrega um crc32c dos próprios bytes em um trailer de quatro bytes, verificado quando o bloco é aberto, e a tabela de frames um crc32c de cada frame, verificado antes de o frame ser descomprimido. Um byte alterado em qualquer um dos dois passa então a ser um erro que nomeia o bloco ou o frame, onde antes ele servia um valor de label errado ou um intervalo de série errado como fato, com um 200. Os checksums custam cinco bytes por frame de 4.096 séries e quatro por bloco. O meta.json não é coberto por eles; em vez disso, ele é conferido contra o índice, porque as consultas pulam um bloco pelo minT e pelo maxT dele e a retenção o apaga pelo maxT. O índice registra o primeiro e o último timestamp e a contagem de amostras de cada série, então, na abertura, um meta.json cujo intervalo, séries ou amostras discordem dele (ou que esteja ausente ou ilegível) é corrigido a partir do índice, escrito de novo e nomeado em uma linha de WARN. Um bloco v1 ou v2 ainda abre, é lido sem verificação e é contado em orbit_stack_unverified_blocks, que o Open também diz no log uma vez por bloco; o meta.json dele é conferido contra um índice que nenhum checksum cobre. Abrir um bloco lê o índice uma vez para conferi-lo e mantém os labels de cada série como referências de símbolo até que uma consulta selecione a série, então um diretório de blocos grandes não precisa caber na memória para o engine subir.
  • Um bloco que falha na verificação ao abrir (um checksum errado, uma versão de formato que este build não conhece) é pulado, o resto é servido, e o engine reporta o bloco pulado. A janela dele vem do nome do diretório, senão do meta.json, senão fica desconhecida e cobre todo o tempo. Uma resposta de query, query_range, series ou de leitura de labels com janela que alcance esse bloco carrega o campo warnings do Prometheus nomeando o bloco e o motivo, então uma janela faltando nunca responde como um 200 limpo. O /readyz continua 200, com "degraded": true e os blocos pulados em reason, e orbit_stack_skipped_blocks os conta. O diretório fica para o operador; a retenção o apaga quando a janela dele passa da retenção. Um bloco de janela desconhecida gera aviso em toda consulta e nunca chega à retenção, então precisa ser removido à mão.
  • Blocos selados por um build anterior à correção do delta de delta podem carregar timestamps deslocados: aquele encoder gravava um delta de delta de exatamente +64, +256 ou +2.048 ms em uma largura que o leitor estende como negativa, então todo timestamp seguinte daquele chunk se movia, e o selamento gravava os timestamps movidos no bloco. Nada no bloco registra o valor original, então um bloco assim não tem conserto; ele sai com a retenção.
  • Uma amostra que o bloco recém-selado já guarda é recusada, e não aceita para nunca mais ser devolvida. O selamento leva o último timestamp de cada série para o head que o substitui, por hash de label, e o consulta uma vez quando uma série é criada ali; uma amostra naquele timestamp ou antes dele conta como out_of_order, do jeito que o Prometheus recusa uma duplicata. O mapa é liberado uma janela depois.
  • A retenção (ORBIT_STACK_RETENTION, default 15 d) apaga blocos inteiros cuja amostra mais nova seja mais antiga que a janela. Um bloco fundido é apagado pela sua amostra mais nova, então um dado pode sobreviver à retenção por até um décimo dela, que também é a regra do Prometheus. Um bloco sai do índice na hora e o diretório dele vai embora quando a última consulta que poderia nomeá-lo termina.
  • Uma consulta lê as séries correspondentes de cada bloco que se sobrepõe à janela, mais o head, mesclando as amostras em ordem de tempo. Os matchers são resolvidos por um índice invertido por bloco, então uma consulta nunca percorre as séries que não quer; os índices e os frames dos blocos são carregados em paralelo, e as séries que ela quer são decodificadas em todos os núcleos, direto nas amostras que o querier devolve. Os passos de uma consulta de intervalo também são avaliados em todos os núcleos: a janela de cada seletor é carregada uma vez antes do primeiro passo e nada escreve nela depois, então os passos são independentes.
  • As colunas de um bloco são guardadas como frames zstd independentes de 4.096 séries cada, e uma consulta descomprime apenas os frames em que os seus matchers caem. As séries são escritas em ordem de label, então um seletor sobre um nome de métrica toca uma sequência de frames em vez do bloco inteiro. Os frames decodificados ficam em um cache de processo limitado por ORBIT_STACK_BLOCK_CACHE_BYTES (um quarto do limite de memória, ou 256 MiB quando não há limite), descartando primeiro os menos usados recentemente, e os frames de um bloco são liberados quando nada o toca por cinco minutos. O formato de bloco é versionado: este build escreve v3 e ainda lê um bloco v1 ou v2, abrindo o v1 como o frame único que ele é.

Um marcador de staleness (o padrão de bits NaN 0x7ff0000000000002 que o Prometheus escreve quando um alvo desaparece) é guardado byte a byte e respeitado na saída: um seletor de intervalo o descarta da janela dele, e um seletor instantâneo que encontra um como a amostra mais nova no timestamp ou antes dele não devolve nada, em vez de buscar mais para trás. Assim, um rate() não devolve NaN a cada restart de pod.

Amostras fora de ordem (um timestamp igual ou anterior ao último daquela série), amostras sem nome de métrica, amostras que criariam uma série além de ORBIT_STACK_MAX_SERIES ou de ORBIT_STACK_MAX_INDEX_BYTES (over_limit), e amostras de uma série nova com mais labels que ORBIT_STACK_MAX_LABELS_PER_SERIES, um nome de label maior que ORBIT_STACK_MAX_LABEL_NAME_LEN ou um valor maior que ORBIT_STACK_MAX_LABEL_VALUE_LEN bytes (label_limit) são descartadas, contadas em orbit_stack_samples_total{outcome} e reportadas em um cabeçalho de resposta X-Orbit-Stack-Dropped (out_of_order=0 invalid=0 over_limit=0 label_limit=3). A requisição ainda assim tem sucesso: uma nova tentativa encontraria o mesmo descarte. O engine confere os labels uma vez, quando cria a série: baixar um limite mantém as séries que o head já tem, e o head não guarda nenhuma string de uma série que recusou. O orbit-agent aplica os mesmos três limites a cada série que coleta (ORBIT_AGENT_LABEL_LIMIT, padrão 64, contando os labels do alvo; ORBIT_AGENT_LABEL_NAME_LENGTH_LIMIT, 256; ORBIT_AGENT_LABEL_VALUE_LENGTH_LIMIT, 4096; 0 para nenhum), descarta a série que passa de um deles antes de enviá-la e conta as amostras dela em orbit_agent_samples_dropped_total{reason="label_limit"} a cada coleta.

Endpoints

RotaO que faz
POST /api/v1/writeRemote-write 1.0 (protobuf, em snappy ou gzip). Responde 204 com Accept-Encoding: snappy, gzip: o orbit-agent passa a enviar gzip quando uma resposta diz isso, de 40% a 70% menos bytes que snappy, e mantém snappy com um engine que não diz. Um corpo gzip descomprime até ORBIT_STACK_MAX_BODY_BYTES no máximo (413 além disso). Remote-write 2.0 é recusado com 415 até ser implementado. Os metadados de métrica que um remetente anexa ficam na memória, o mais recente por família de métricas, para /api/v1/metadata.
GET|POST /api/v1/query_range?query=&start=&end=&step= → matriz do Prometheus. start/end em RFC 3339 ou segundos Unix, step como duração ou segundos, no máximo 11.000 pontos por série.
GET|POST /api/v1/query?query=&time= → vetor ou escalar do Prometheus, ou uma matriz para um seletor de intervalo. As duas rotas guardam na memória (64 MiB) a resposta de uma janela que terminou há 15 minutos ou mais, até que uma escrita traga uma amostra com mais de 15 minutos ou que um bloco seja selado, mesclado ou apagado; nocache=1 calcula a resposta de novo. A query_range também guarda, com as mesmas regras e outros 32 MiB, os passos já fechados de cada leitura por expressão e step: uma janela posterior na mesma grade, deslocada de um step ou ainda aberta no fim, calcula só os passos que faltam, como o cache de rollup do VictoriaMetrics. O que um selamento ou uma escrita atrasada deixou para trás é devolvido em até 10 segundos, sem precisar de leitura. O Deck termina intervalos de 7 dias ou mais num múltiplo do step, para que quem o usa compartilhe esses passos.
GET|POST /api/v1/series?match[]=&start=&end=&limit= → os conjuntos de labels com alguma amostra na janela.
GET|POST /api/v1/labels, GET /api/v1/label/{name}/values?match[]=&start=&end=&limit= → nomes e valores de labels nos blocos e no head.
GET /api/v1/metadata?metric=&limit= → os metadados que os remetentes de remote-write anexaram.
GET /api/v1/rulesNenhum grupo: o engine não avalia regras. O Grafana pergunta a cada carga de dashboard.
GET|POST /api/v1/query_exemplarsSempre vazio: exemplars não são guardados. A expressão e a janela ainda são validadas.
GET|POST /api/v1/format_query?query= → a forma canônica do parser, com toda operação binária entre parênteses.
GET /api/v1/status/buildinfoO formato do Prometheus, com a versão e o commit deste engine.
GET /api/v1/status/tsdbSéries, amostras e bytes no head e nos blocos, séries criadas e removidas, as dez métricas com mais séries no head (seriesCountByMetricName), as dez labels com mais valores no head (labelValueCountByLabelName), descartes, selamentos, blocos pulados e compactações.
POST /-/flushSela o head agora; também grava as métricas de span acumuladas até ali e corta o head de traces em um segmento.
POST /v1/tracesTraces OTLP/HTTP, em protobuf ou JSON, em gzip, zstd ou sem compressão, respondidos nos formatos do OTLP. Veja "Traces".
GET /api/v1/traces/{traceId}, GET /api/v1/tracesUm trace por id (com start e end, em ms desde o epoch, lê só os segmentos a até uma hora deles, e depois todos se esses não tiverem nada dele); uma busca por serviço, operação, status, duração e atributos. Os formatos e o envelope de erro do contrato, não os do Prometheus.
GET /api/v1/apm/services, GET /api/v1/apm/services/{service}/operations, GET /api/v1/apm/servicemapTaxa, erros e latência por serviço e por operação, e o mapa de serviços, calculados a partir das métricas de span.
GET /api/v1/apm/heatmapA duração dos spans ao longo do tempo para o heatmap de latência: todos os spans pelas métricas de span, ou os traces armazenados que uma busca encontraria sob um filtro de atributo.
GET /healthz, GET /readyz, GET /-/healthy, GET /-/readyProbes, isentas de autenticação.
GET /api/v1/versionCarimbo do build, como em todo outro serviço de backend.
GET /metricsEm ORBIT_STACK_METRICS_ADDR, listener próprio, nunca roteado por um ingress. Em gzip quando o scraper envia Accept-Encoding: gzip.

As rotas de telemetria respondem nos formatos do Prometheus ({"status":"success","data":...} e {"status":"error","errorType":"bad_data","error":"..."}), de modo que Grafana, promtool e qualquer agente tratam o engine como um Prometheus. Uma resposta pode trazer a lista warnings do Prometheus: uma janela que alcança um bloco pulado na abertura, ou results truncated due to limit quando um limit cortou a resposta. Sem match[], as rotas de labels respondem a partir do índice do head e dos blocos que se sobrepõem a start/end, como no Prometheus. Com match[], uma janela as restringe às séries selecionadas com alguma amostra nela. As probes, a rota de versão, o 404 e o 429 respondem nos formatos do CONTRACT.md, como todo outro serviço.

As leituras são medidas por IP de cliente: toda rota de leitura acima, mas não as escritas, o /-/flush, o status/tsdb, o status/buildinfo, a rota de versão nem as probes. ORBIT_STACK_QUERY_RPM (3.000 por minuto) é a taxa sustentada e ORBIT_STACK_QUERY_BURST (300) o que um endereço pode mandar de uma vez; passando disso, o engine responde 429 com um cabeçalho Retry-After. Todo mundo atrás de um mesmo Grafana ou de um mesmo orbit-api divide o endereço dele, então dimensione os dois pelo dashboard mais pesado vezes os seus espectadores; definir qualquer um dos dois como 0 desliga o limitador. O endereço é o do par da conexão, a menos que ele esteja em ORBIT_STACK_TRUSTED_PROXIES.

PromQL

A linguagem do Prometheus 3 para amostras float: seletores com =, !=, =~ e !~ (nomes de métrica podem começar com :), seletores de intervalo, offset e subconsultas; aritmética, comparação (com ou sem bool), atan2 e os operadores de conjunto and, or e unless, com on/ignoring e group_left/group_right; as agregações sum, avg, min, max, count, group, stddev, stdvar, topk, bottomk, quantile e count_values com by e without; e as funções rate, irate, increase, delta, idelta, resets, changes, deriv, predict_linear, todas as *_over_time (sum, avg, min, max, count, last, stddev, stdvar, present, absent, quantile), as funções matemáticas e trigonométricas por elemento, round, clamp, clamp_min, clamp_max, timestamp, time, vector, scalar, absent, sort, sort_desc, label_replace, label_join, histogram_quantile sobre buckets clássicos e as funções de data. As palavras-chave são lidas em qualquer caixa. Um matcher de regex é ancorado e compilado como ^(?s:re)$, exatamente como o Prometheus o compila, então . também casa com uma quebra de linha. Uma regex compila para no máximo 4 MiB (uma alternância de 500 valores cabe, \w{180} não), e uma consulta leva no máximo 32 delas, somando os matchers e as chamadas de label_replace; uma leitura de labels ou de séries as conta em todos os seus match[]. Além de qualquer um dos dois, a consulta é recusada como inválida. rate e increase extrapolam exatamente como no Prometheus 3.x, com detecção de reset de counter.

As respostas são conferidas contra resultados gravados do Prometheus 3.14.0 (services/rust/orbit-stack/testdata/oracle_prometheus.json, dados de teste que os testes do engine em Rust leem) e contra o conjunto de consultas do prometheus/compliance. Na execução de conformidade de 2026-09-23 contra o Prometheus v3.14.0, todas as consultas desse conjunto passaram e nenhuma foi dada como sem suporte; a saída dessa execução não está versionada em bench/runs/, então a contagem dela não é impressa aqui.

Fora da linguagem como implementada: o modificador @, histogramas nativos, funções experimentais (limitk, double_exponential_smoothing, mad_over_time e afins) e uma string como resultado de consulta. Cada um é recusado com um erro que o nomeia. O engine nunca responde uma expressão sem suporte com um número errado.

Configuração

VariávelDefaultSignificado
ORBIT_STACK_ADDR:8082Listener da API.
ORBIT_STACK_METRICS_ADDR:9090Listener de métricas; nunca a porta da API, nunca roteado.
ORBIT_STACK_LOG_LEVELinfodebug info warn error.
ORBIT_STACK_LOG_PROBESfalseRegistra em info as requisições das probes e de /metrics; senão, elas só aparecem em debug.
ORBIT_STACK_DATA_DIR/dataOs blocos, o WAL e o spill. Um volume nomeado no compose, um PersistentVolumeClaim no Kubernetes.
ORBIT_STACK_RETENTION15dBlocos cuja amostra mais nova seja mais antiga que isso são apagados. Dias ou uma duração Go. Também limita o maior nível de compactação a um décimo dela.
ORBIT_STACK_BLOCK_DURATION2hJanela do head selada em um bloco, e o menor nível de compactação. Mínimo 1m. Janelas mais curtas significam menos RAM por série e mais blocos para a compactação fundir.
ORBIT_STACK_COMPRESSIONbetterNível de zstd para os blocos selados e fundidos: fast, default, better, best.
ORBIT_STACK_BLOCK_CACHE_BYTESum quarto do memory.max do cgroup, senão 256 MiBFrames e índices de bloco descomprimidos que as consultas podem segurar. Uma contagem simples de bytes ou uma unidade binária (512MiB).
ORBIT_STACK_HEAD_CHUNK_SAMPLES120Amostras depois das quais o chunk aberto de uma série é fechado e gravado no spill. O buffer fixo do chunk o fecha antes para qualquer série que não seja quase constante, então só um valor menor muda muita coisa: menor troca mais registros no spill por uma leitura menor a cada chunk. Mínimo 2.
ORBIT_STACK_MAX_SERIES0Teto de séries vivas; 0 significa nenhum. Passando dele, novas séries são descartadas e contadas.
ORBIT_STACK_MAX_LABELS_PER_SERIES64Labels que uma série nova pode ter, __name__ entre eles; 0 significa sem limite. Passando dele, a série é descartada e contada como label_limit.
ORBIT_STACK_MAX_LABEL_NAME_LEN256Bytes de um nome de label de uma série nova, conferido do mesmo jeito.
ORBIT_STACK_MAX_LABEL_VALUE_LEN4096Bytes de um valor de label de uma série nova, o nome da métrica incluído, conferido do mesmo jeito.
ORBIT_STACK_MAX_INDEX_BYTEStrês oitavos do memory.max do cgroup, no mínimo 64 MiB; nenhum sem limite de cgroupBytes que o índice do head pode ocupar (2GiB ou bytes; 0 para nenhum). O engine cobra 128 bytes por série, 16 por label de uma série, 160 por par nome=valor distinto, 512 por nome de label distinto e 80 por string de label distinta mais o seu tamanho, custos medidos com o overhead do alocador. Até uma escrita terminar, cada label das séries que ela cria conta como um par novo e um nome novo, então uma escrita grande perto do teto descarta algumas séries novas antes da hora. Passando dele, novas séries são descartadas e contadas como over_limit até um seal remover as séries que pararam. Ele limita a memória do head mesmo com ORBIT_STACK_MAX_SERIES em 0: uma série cujos 63 labels trazem cada um um valor que nenhuma outra série tem custa cerca de 11 KiB; uma no formato do Kubernetes, algumas centenas de bytes. orbit_stack_head_index_bytes mostra o valor atual.
ORBIT_STACK_QUERY_TIMEOUT30sOrçamento por consulta.
ORBIT_STACK_QUERY_MAX_SAMPLES50000000Pontos que uma consulta pode manter (os pontos da resposta, as amostras de um seletor de intervalo numa consulta instantânea, ou as amostras de uma série na janela) antes de ser recusada. Um rate de 30 dias lê cada amostra uma vez e guarda 121 pontos por série, então o tamanho da janela sozinho nunca a recusa; o timeout limita a leitura. Os resumos de APM não seguem o teto: somam increase() uma série por vez, e o timeout os limita.
ORBIT_STACK_QUERY_TURNS0Leituras PromQL que rodam ao mesmo tempo; as outras esperam a vez. 0 é metade dos núcleos que o engine vê, no mínimo 2. Uma leitura que alcança 2 horas para trás ou menos (a janela, o maior intervalo e os 5 minutos de lookback) usa uma das quatro vezes leves por núcleo, e assim uma página de 1 hora e as leituras de alerta nunca esperam atrás de leituras de 30 dias.
ORBIT_STACK_QUERY_MAX_BYTESum terço da memória do cgroupMemória que todas as leituras PromQL podem manter juntas (1GiB, 512MiB ou bytes; 0 para nenhum teto, o padrão sem limite de cgroup). Cada leitura conta as séries que casaram antes de reuni-las, depois as linhas e os pontos que guarda, até escrever a resposta. Uma leitura que passa do teto falha com 422 e devolve a parte dela. Dezesseis leituras de um milhão de séries cada levavam o engine além de um limite de 3 GiB; com teto de 1 GiB, o pico ficou em 1,5 GB e duas delas foram até o fim. orbit_stack_query_held_bytes mostra o que as leituras em curso mantêm.
ORBIT_STACK_QUERY_RPM3000Leituras sustentadas por minuto por IP de cliente; 0 desliga o limitador de leituras.
ORBIT_STACK_QUERY_BURST300Leituras que um IP de cliente pode mandar de uma vez; 0 desliga o limitador de leituras.
ORBIT_STACK_MAX_BODY_BYTES67108864Teto da requisição de remote-write (64 MiB). Todos os remote writes em andamento seguram juntos no máximo um quarto da memória do cgroup, de 64 MiB a 1 GiB (1 GiB sem limite), como chegaram e descomprimidos; um write além disso recebe 503 com Retry-After: 1, e o remetente o reenvia. Um corpo snappy que diz descomprimir para mais de 64/3 do próprio tamanho é recusado com 400 antes de qualquer alocação, e um cujas séries, labels e amostras ocupariam mais de quatro vezes o tamanho descomprimido (uma vazia tem dois bytes), com 400 durante a leitura.
ORBIT_STACK_MEMORY_LIMITnão definidaLida só pelo engine em Go (tag go-oracle), que limitava a ela o seu heap com coleta de lixo. O engine em Rust não tem coletor a orçar e a ignora; veja Memória.
ORBIT_STACK_AUTH_MODEstaticstatic ou disabled (apenas demonstrações locais; registra um WARN a cada inicialização).
ORBIT_STACK_AUTH_TOKENvazioObrigatório quando o modo é static, com pelo menos 32 bytes. Os agentes e o orbit-api o apresentam. Ele lê, escreve e altera configurações.
ORBIT_STACK_INGEST_TOKENvazioSegundo bearer opcional, com pelo menos 32 bytes e diferente de ORBIT_STACK_AUTH_TOKEN. Ele só pode fazer POST em /api/v1/write, /v1/traces e /v1/logs; qualquer outra rota responde 401. Entregue este às aplicações e aos Collectors fora do release. O Helm o define a partir de secrets.orbitStackIngestToken, e aí o coletor de traces e a loja demo do chart enviam com ele em vez do token principal.
ORBIT_STACK_TRUSTED_PROXIESvazioCIDRs em cujo X-Forwarded-For o limitador de leituras por IP acredita.
ORBIT_STACK_SHUTDOWN_GRACE30sOrçamento de drain. O WAL é sincronizado; nada é selado sob prazo.
ORBIT_STACK_TRACE_RETENTION7dSegmentos de trace cujo span mais novo seja mais antigo que isso são apagados inteiros. Dias ou uma duração Go.
ORBIT_STACK_TRACE_HEAD_BYTES64MiBSpans mantidos em memória antes de o head ser cortado em um segmento; o cache de leitura de traces recebe metade disso, e os bytes de requisições OTLP retidos em andamento (no mínimo 32 MiB), o mesmo orçamento. No mínimo 1MiB.
ORBIT_STACK_TRACE_MAX_BYTES5MiBUm trace no head, o default de max_bytes_per_trace do Tempo; os spans que passam disso são recusados um a um (partial success do OTLP). De 64 KiB até a metade de ORBIT_STACK_TRACE_HEAD_BYTES.
ORBIT_STACK_TRACE_GRAPH_PENDING100000Spans à espera do outro lado de uma aresta do service graph, de 1.000 a 10.000.000. Acima disso, um span fica sem par: a aresta conta a menos, a traces_service_graph_dropped_spans_total o conta e o mapa de serviços responde partial: true.

O orbit-api alcança o engine com ORBIT_STACK_URL e ORBIT_STACK_TOKEN.

Memória

O head guarda todas as séries da janela de bloco atual, mas só o chunk aberto de cada série viva está no heap: os chunks que ela fechou estão nos segmentos do spill, em disco. No heap, uma série viva custa o seu registro de 64 bytes, o seu chunk aberto (uma alocação única de 160 bytes que nunca cresce), alguns bytes de referências de símbolo para os seus labels, a sua parte do índice invertido e a sua entrada na tabela de séries do WAL. Nem a duração do bloco nem o intervalo de scrape mudam isso; eles mudam apenas quanto vai para os segmentos do spill e com que frequência um chunk é gravado. Uma série que para de enviar mantém os seus labels e as suas entradas no índice no head até o selamento da janela em que parou: o selamento grava as amostras dela no bloco e a remove. Uma série em silêncio há menos de 15 minutos nesse selamento fica uma janela a mais. Com pods indo e vindo, o head guarda as séries vivas mais as que pararam desde o último selamento.

A única medição do processo inteiro com 200.000 séries em um relatório de bench/runs/ está em benchmark.md: 511 MiB residentes com um head cheio de 200.000 séries, e 77 MiB assim que esse head é selado. Esse relatório mediu o engine em Go (tag go-oracle) antes de o head, o spill e o WAL ganharem o layout atual; o soak do prometheus-benchmark na mesma página mediu um build posterior que ainda é anterior a eles. Até que um relatório em bench/runs/ meça este build, dimensione o contêiner usando os 511 MiB como teto e combine com ORBIT_STACK_MAX_SERIES: um teto descarta e conta o que não consegue segurar, o que é um desfecho melhor do que o pod ser morto por OOM com o head que já tem. Os values do chart fazem as duas coisas.

O selamento lê os chunks do spill do head e os abertos, faz as colunas passarem pelo zstd série por série e devolve o pico do selamento ao sistema operacional (malloc_trim), de modo que o processo não fica parado nesse pico até a próxima janela. Na inicialização, o processo fixa o limiar de mmap da glibc em 64 KiB: todo buffer a partir desse tamanho ganha um mapeamento próprio, devolvido ao sistema operacional no momento em que é liberado, em vez de fragmentar as arenas do alocador além do que um trim consegue devolver. Não há coletor de lixo a ajustar: GOGC, GOMEMLIMIT e ORBIT_STACK_MEMORY_LIMIT eram do engine em Go (tag go-oracle), e o engine em Rust os ignora. Três coisas limitam a memória dele: o head descrito acima, o ORBIT_STACK_BLOCK_CACHE_BYTES para as páginas de bloco que as consultas seguram e o ORBIT_STACK_MAX_SERIES.

Leituras longas também guardam o que poupa trabalho à próxima, cada coisa com um teto fixo e mantida até o bloco sair: os pontos de busca das colunas Gorilla (64 MiB) e os fins de cada trecho e os índices de tempo das colunas inteiras (64 MiB). Uma taxa de 30 dias então só desempacota os trechos nas bordas das janelas.

Um restart reprocessa o write-ahead log para dentro do head antes de servir. O replay decodifica registro por registro em buffers reaproveitados e, se o que ele reprocessou abrange mais de uma duração de bloco (um pod que ficou fora do ar enquanto o log crescia), o head é selado antes de a primeira requisição ser servida, e o intervalo e o selamento são registrados em log. Nem o replay nem um loop de restart conseguem segurar horas de amostras em memória.

Traces

O apm.md cobre o que enviar e o que o engine deriva; esta seção cobre como o engine guarda os spans.

  • O log. Os spans de uma requisição são comprimidos com zstd e anexados ao write-ahead log de traces, cada registro enquadrado com o seu tamanho e um crc32c e carimbado com a hora de chegada, e a requisição só é respondida quando o registro já está no arquivo de log: um processo derrubado depois de responder não perde nada do que confirmou. O log passa por fsync a cada segundo, então uma queda de energia perde no máximo esse segundo. Uma cauda truncada depois de um crash é reprocessada até o ponto do corte, registrada em log e contada em orbit_stack_trace_wal_truncations_total.
  • O head. Os spans aceitos ficam agrupados por trace na memória, até ORBIT_STACK_TRACE_HEAD_BYTES, que conta spans, resumos, conjuntos de ids de span e cada recurso distinto. Um trace que passa de ORBIT_STACK_TRACE_MAX_BYTES tem os spans seguintes recusados um a um (o partial success do OTLP), e um span que o trace já tem, o retry de um exporter, é guardado uma vez só. Enquanto um segmento está sendo gravado, um head no dobro do seu limite responde 503 com Retry-After, e os remetentes tentam de novo.
  • Segmentos. O head é cortado quando atinge o seu limite ou completa 15 minutos, e vira um segmento imutável da versão 2 do formato: traces inteiros como frames zstd em ordem de início; chunks de resumos de 512 traces, cada um com um zone map (limites de início e de duração, máscaras de serviço e de operação, flags de erro) e um filtro de atributos de 512 bits por trace; uma tabela de ids ordenada que é lida no lugar e um bloom filter; e checksum em cada seção. Um segmento mantém em memória só os seus diretórios, os seus símbolos e o seu bloom filter. Ele nomeia os logs que absorveu, então um log encontrado ao lado dele na inicialização é apagado em vez de ser reprocessado uma segunda vez.
  • Só a versão 2 do formato. Um segmento que este build não consegue ler, incluindo um segmento da versão 1 gravado pela primeira release de traces, é recusado pelo nome na inicialização: a linha de log trace segment skipped diz o arquivo e o motivo, e ele é contado em orbit_stack_trace_skipped_segments. Ele não é servido nem apagado, porque pode ser a única cópia dos seus traces, e a retenção não chega a ele: apague-o à mão quando esses traces não importarem mais. O write-ahead log de qualquer uma das duas versões é reprocessado no head normalmente.
  • Retenção. Um segmento é apagado inteiro quando o seu último span chegou há mais tempo que ORBIT_STACK_TRACE_RETENTION: vale a hora de chegada, não o relógio dos próprios spans, então um span carimbado com uma data anos no futuro não consegue segurar um segmento para sempre.
  • Leituras. Um trace por id consulta o head, depois o bloom filter e a tabela de ids de cada segmento, junta as partes de um trace que chegaram dos dois lados de um corte e envia a resposta em streaming, sem montá-la inteira; um span enviado duas vezes volta uma vez só, e os spans vêm ordenados pelo início. Uma busca lê primeiro os chunks de resumos mais novos, em todos os segmentos, pula cada chunk cujo zone map descarta a consulta e para assim que chunks mais antigos não podem mais mudar a resposta; um trace dividido por um corte é julgado inteiro. Uma busca por valor de atributo também pula cada chunk cujo filtro de atributos (um filtro de bloom dos atributos distintos que os spans dele carregam, gravado com o segmento) descarta o valor, então um request id raro ou ausente lê poucos chunks ou nenhum. Frames, resumos e recursos passam por um cache de leitura limitado à metade do limite do head. Outros 16 MiB, à parte para que uma varredura não os esvazie, guardam, por segmento e filtro, o que uma varredura do segmento inteiro encontrou: o número de correspondências, a parte dele nas mais novas e nas amostradas que a leitura guardou (o dobro do limite na janela inteira, então uma semana de um filtro amplo ocupa algumas centenas de KB) e até 256 valores de cada chave de faceta personalizada. Assim, o mesmo filtro sobre uma semana lê um segmento uma vez, em qualquer janela que o contenha inteiro, enquanto essa resposta fica nesses 16 MiB; uma janela muito mais estreita ou um limite muito maior lê de novo os segmentos de que precisa, uma vez. Uma lista passa direto pelos chunks que não têm nenhuma das mais novas. Uma contagem interrompida no orçamento já leu segmentos inteiros espalhados pela janela, o que deixa menos trabalho para a leitura seguinte.
  • Métricas de span. Todo span aceito também alimenta o gerador que grava traces_spanmetrics_*, traces_service_graph_* e traces_target_info no head de métricas a cada 15 segundos; as rotas de APM são PromQL sobre essas séries. Os nomes, os labels e as regras delas estão no apm.md.

Tudo fica em ORBIT_STACK_DATA_DIR/traces, ao lado dos blocos de métricas, então o mesmo volume e os mesmos backups cobrem os dois. O GET /api/v1/status/tsdb reporta o armazenamento de traces sob traces.

Apontando um agente para ele

Prometheus, em modo agente ou não:

yaml
remote_write:
  - url: http://orbit-stack:8082/api/v1/write
    authorization:
      credentials: <the ORBIT_STACK_AUTH_TOKEN>

vmagent: -remoteWrite.url=http://orbit-stack:8082/api/v1/write -remoteWrite.bearerToken=<token>. O exporter prometheusremotewrite do coletor OpenTelemetry funciona do mesmo jeito. Dentro do cluster o endereço é o Service orbit-stack na porta 8082; de um laptop contra a stack do compose é http://127.0.0.1:8082, publicado apenas no loopback.

O que observar

orbit_stack_head_series, orbit_stack_head_series_created_total, orbit_stack_head_series_removed_total, orbit_stack_head_bytes (os chunks abertos, no heap), orbit_stack_head_spill_bytes (os fechados, nos segmentos do spill), orbit_stack_wal_bytes, orbit_stack_wal_truncations_total, orbit_stack_seal_failures_total, orbit_stack_spill_errors_total, orbit_stack_unverified_blocks, orbit_stack_skipped_blocks, orbit_stack_blocks, orbit_stack_block_bytes (disco), orbit_stack_compactions_total, orbit_stack_compaction_failures_total, orbit_stack_query_cache_resets_total (escritas atrasadas e mudanças de bloco que descartaram as respostas PromQL guardadas), orbit_stack_samples_total{outcome} (accepted, out_of_order, invalid, over_limit, label_limit), orbit_stack_head_index_bytes, orbit_stack_query_duration_seconds e orbit_stack_seal_duration_seconds, todos no listener de métricas. Uma contagem crescente de out_of_order significa que dois remetentes escrevem a mesma série, ou que um remetente reenvia o que já mandou. Uma contagem crescente de over_limit significa que o ORBIT_STACK_MAX_SERIES ou o ORBIT_STACK_MAX_INDEX_BYTES está descartando séries novas, como configurado. Uma contagem crescente de label_limit significa que as séries novas de um remetente trazem mais labels, ou labels maiores, do que os limites permitem; o GET /api/v1/status/tsdb também informa droppedLabelLimit e indexBytes. A taxa de orbit_stack_head_series_created_total contra orbit_stack_head_series é o churn; o GET /api/v1/status/tsdb lista as dez métricas com mais séries no head, onde uma explosão de cardinalidade aparece primeiro, e as dez labels com mais valores, a label que a carrega. A aba Métricas do Controle de ingestão mostra as duas listas, pelo orbit-api (veja o ingestion.md).

Para traces: orbit_stack_spans_total{outcome} (accepted, rejected), orbit_stack_trace_head_bytes, orbit_stack_trace_head_spans, orbit_stack_trace_segments, orbit_stack_trace_segment_bytes, orbit_stack_trace_wal_bytes, orbit_stack_trace_cache_bytes, orbit_stack_trace_skipped_segments, orbit_stack_trace_cuts_total, orbit_stack_trace_cut_failures_total, orbit_stack_trace_wal_truncations_total e orbit_stack_trace_generator_dropped_total. Alerte sobre falhas de corte e segmentos pulados do mesmo jeito que você alerta sobre falhas de selamento e blocos pulados.

Um selamento que continua falhando e um bloco pulado na abertura são reportados no corpo do /readyz ({"status":"ready","degraded":true,"reason":"..."}) e não no status dele, que continua 200. A janela segue consultável e respaldada pelo log dela, ou responde com um aviso; responder 503 tiraria o engine do Service dele e pararia o ingest, o que perde mais do que uma janela atrasada para o disco. Alerte sobre orbit_stack_seal_failures_total (que conta tanto um write-ahead log que não quis rotacionar quanto um bloco que não pôde ser escrito), sobre orbit_stack_skipped_blocks acima de zero e sobre o campo degraded, não sobre readiness.

Tetos desta release

Node único, sem replicação, sem camada em object store, sem downsampling, apenas remote-write 1.0, sem avaliação de regras nem exemplars, e o PromQL acima. Para traces: apenas OTLP/HTTP, sem gRPC, sem amostragem, sem guardar os span links nem o instrumentation scope, e o gerador com um teto de conjuntos de labels. Cada um é um comentário ponytail: no código-fonte nomeando o caminho de evolução.

Três deles têm preço medido, todos contra o VictoriaMetrics e não contra o Prometheus: um sum by (...) (rate(...)) sobre 20.000 séries responde em 24 ms contra os 16 dele, um head cheio de 200.000 séries é 511 MiB residentes contra os 312 dele, e, no soak do prometheus-benchmark, o diretório de dados guardava de 24 a 27 bytes por amostra enquanto os dados estavam no head, contra os 2,5 a 2,7 dele. Os três estão em benchmark.md com os números ao lado das linhas em que ele perde. O terceiro foi medido no WAL e no spill que esta release substituiu; nenhum relatório em bench/runs/ mede os novos ainda.

Traces contra o Grafana Tempo. Com os mesmos traces, o engine lê um trace por id mais rápido, aceita spans mais rápido e ocupa menos memória, e o resumo de serviços e o mapa de serviços dele são mais rápidos com 50.000 traces. A busca só é mais rápida para valores comuns nos dados recentes: um valor raro ou ausente faz com que ela leia todos os resumos da janela, e com 3,4 M de spans isso é mais lento que o Tempo. O resumo de serviços e o mapa de serviços lidos logo depois de um flush são mais lentos que os do Tempo. Os números, a tabela de derrotas e as execuções retiradas estão no benchmark.md → "Traces contra o Grafana Tempo", a única página que os imprime.

O avaliador computa rate, increase, delta e irate sobre um seletor de intervalo, sozinhos ou sob um único sum, avg, min, max ou count, série a série: uma passada por série preenche todos os passos da consulta de intervalo, e o grupo a que uma série pertence é resolvido uma vez, em vez de a cada passo. Qualquer outra coisa cai no avaliador geral, e os dois são mantidos na mesma resposta, amostra por amostra, pelos testes.

orbit_stack_head_bytes são apenas os chunks abertos, a parte do head que está no heap; orbit_stack_head_spill_bytes é o que os chunks fechados dele guardam nos segmentos do spill.