Pular para o conteúdo

Recursos

Arquivo S3

Com archive.enabled, cada bloco de métricas que o orbit-stack sela e cada segmento de traces e de logs que ele grava vão para um bucket S3 seu, assim que chegam ao disco. A retenção local continua apagando os dados no próprio ritmo (15 dias de métricas e 7 de traces e logs por padrão); o bucket os guarda pelo tempo que as regras de ciclo de vida dele mandarem. Uma reidratação copia de volta uma janela de tempo, por exemplo um dia de dois meses atrás, e você a consulta no Deck por 1 a 180 dias. Depois ela é apagada de novo.

Como os dados chegam ao S3

O orbit-stack cria um hard link de cada bloco e segmento selado em <data>/archive/outbox/ no momento em que o grava. O link não copia nada nem pesa no caminho de ingestão, e o arquivo fica lá depois que a retenção ou a compactação apagam o original, até ser enviado. A cada 15 segundos o orbit-api lê a outbox, põe cada arquivo no bucket (multipart acima de 64 MiB) e o tira da outbox, vários blocos e segmentos de uma vez sob um limite de 128 MiB, os arquivos de um bloco em ordem. Um envio que falha continua na fila e é repetido; nada é confirmado antes de o S3 responder 200.

Os objetos são os próprios arquivos do motor, já comprimidos, com uma chave por arquivo:

text
<prefix>/<signal>/dt=YYYYMMDD/hour=HH/<oldest ms>-<newest ms>-<name>[/<block file>]

<signal> é metrics, traces ou logs. O dia e a hora são os do dado mais novo do arquivo. Um bloco de métricas são seis objetos, meta.json por último, e uma reidratação só lê um bloco quando o meta.json dele já está lá.

Partições

Os atributos de partição separam no bucket os dados de cada valor, e uma reidratação filtrada por um valor copia só a parte dele. Defina até dois labels por sinal:

text
helm upgrade sreorbit deploy/helm/sreorbit --reuse-values \
  --set 'archive.partitions.metrics={namespace}' --set 'archive.partitions.logs={service}'
  • Métricas. O orbit-stack divide cada bloco selado em um bloco por valor dos labels; uma série sem o label vai para o valor vazio. Ele copia os registros das séries e as colunas de timestamp como estão, sem decodificar nem comprimir de novo, quando o orbit-api lista a outbox de novo (um bloco por vez; até lá o bloco preparado são só hard links), e junta as partes, uma depois da outra, num objeto só, <block>.pack. Ao lado dele, <block>.pack.parts liga os valores dos labels de cada parte à faixa de bytes dos arquivos dela. Uma reidratação lê o mapa, busca só as partes que o filtro seleciona com GETs por faixa, e o orbit-stack grava cada pedaço direto nos arquivos de bloco da parte.
  • Logs. Um segmento continua um objeto só, com os streams na ordem dos labels, então os blocos de um serviço ficam juntos. Ao lado dele, <segment>.parts liga cada valor dos labels (service, namespace, pod, container, node) aos blocos que guardam os streams dele. Uma reidratação filtrada lê esse mapa, copia as seções do segmento e esses blocos com GETs por faixa e deixa o resto do arquivo como um buraco. Uma leitura restrita ao valor só lê blocos com os streams dele, que são os copiados.
  • Traces e spans não têm partição: um trace atravessa serviços, e o segmento guarda os traces na ordem de início para a busca do mais novo ao mais antigo. Uma reidratação filtrada copia os arquivos deles inteiros.

Um filtro poda quando cita um label de partição: {namespace="payments"}, =~, != e !~ nas métricas, e um termo service:api sem aspas nos logs. Qualquer outro filtro copia a janela inteira. O orbit-stack continua aplicando o filtro completo em toda leitura, então uma reidratação podada responde o mesmo que o armazenamento ao vivo responde para aquele filtro.

Atributo de lookup. trace_id é o atributo de alta cardinalidade que um filtro de logs pode procurar. O mapa de cada segmento de log leva o bloom de trace ids de cada bloco, montado quando o orbit-stack corta o segmento, com ou sem partições. Uma reidratação ou uma Busca no arquivo com um termo trace_id:<32 hex digits> copia só os blocos cujo bloom pode ter esse id, então achar as linhas de um trace de um mês atrás lê alguns blocos por segmento em vez do dia.

Escolha labels com dezenas ou centenas de valores: cada valor acrescenta uma parte ao pacote e uma entrada ao mapa dele, dois objetos por selagem, seja qual for a contagem. Até o orbit-api enviá-lo, o pacote é uma cópia no volume do orbit-stack, mais ou menos do tamanho do bloco. Uma mudança nos labels vale para o que o orbit-stack selar dali em diante; os objetos antigos mantêm o layout deles (versões anteriores gravavam um bloco de seis objetos por valor em .../hour=HH/<label>=<value>/), e uma reidratação lê os dois.

Configuração no EKS

  1. Crie o bucket: privado, com Block Public Access ligado, criptografia padrão ligada e uma regra de ciclo de vida que aborta uploads multipart incompletos depois de um dia. Acrescente sua própria transição ou expiração.
  2. Dê o bucket à role do orbit-api. O EKS liga uma role por ServiceAccount, então a política vai na role que o orbit-api já tem (ou numa nova):
text
CLUSTER=my-eks NAMESPACE=sreorbit RELEASE=sreorbit ARCHIVE_BUCKET=my-archive \
  deploy/aws/setup-pod-identity.sh

A política permite s3:ListBucket no bucket e s3:PutObject, s3:GetObject e s3:AbortMultipartUpload nos objetos dele, mais nada. 3. Abra a saída do orbit-api para o S3 e informe o bucket, no chart ou no Deck:

text
helm upgrade sreorbit deploy/helm/sreorbit --reuse-values \
  --set archive.enabled=true --set archive.bucket=my-archive

Com archive.enabled=true e sem archive.bucket, nada é arquivado até um admin adicionar um arquivo em Admin > Arquivo (abaixo).

Arquivos no Deck

Admin > Arquivo (settings.manage) mostra Configurar o arquivo até existir um arquivo, e depois a lista Arquivos. Cada arquivo tem um nome, um bucket, prefixo e região, uma classe de armazenamento, uma criptografia (o padrão do bucket, SSE-S3, ou SSE-KMS com o ARN, id ou alias da chave), um limite de leitura por reidratação em GB, os sinais que ele leva (métricas, traces e spans, logs) e um filtro de inclusão. Adicionar arquivo, Editar, as setas, Desligar e Excluir mudam a lista; o painel Partições define os labels de partição que dividem os arquivos de todos.

O orbit-api envia cada arquivo da fila ao primeiro arquivo da lista, de cima para baixo, que está ligado, leva o sinal dele e cujo filtro casa com ele. O filtro são seletores sobre os labels de partição, como {namespace=~"prod-.*", app!="debug"}; um label que o dado não tem conta como vazio, e um filtro vazio leva tudo. Um bloco de métricas vai partição por partição: um bloco cujas partições casam com arquivos diferentes vira um pack menor para cada arquivo, cada um com o seu mapa. Um segmento de logs é cortado pelos valores de partição antes de ir: um segmento menor por valor, com o seu mapa, sob <label>=<value>/ no bucket, então {service="checkout"} leva os streams do checkout de um segmento que tem cinquenta serviços. Ao salvar, cada label que um filtro cita entra nas partições dos sinais que o arquivo leva; para logs, um filtro pode citar service, namespace, pod, container ou node, e cada sinal tem no máximo dois labels. Traces vão inteiros, segmento a segmento: um arquivo com filtro leva só métricas e logs. Dois arquivos não podem dividir o mesmo bucket e prefixo, nem ficar um dentro do outro. O que nenhum arquivo leva sai da fila sem ser arquivado e conta como ignorado na linha do sinal. Deixe um arquivo sem filtro no fim para pegar o resto.

Logs que uma regra de ingestão descarta ou amostra também chegam ao arquivo, como o Datadog arquiva todo log ingerido, indexado ou não. O orbit-stack os grava num store que nenhuma página lê, em <data>/logs/dropped/, e apaga cada segmento dele assim que o arquivo o põe na fila. Uma reidratação os traz de volta com o resto, então a janela mostra o que chegou, não só o que as regras guardaram. Métricas e spans que as regras descartam não são arquivados.

Salvar e testar grava um objeto de 25 bytes, <prefix>/.orbit-write-test, com a classe e a criptografia escolhidas, lista <prefix>/ e apaga o objeto (uma role sem s3:DeleteObject o deixa lá; o teste seguinte o sobrescreve). O orbit-api testa cada arquivo novo e cada um cujo bucket, prefixo, região, classe ou criptografia mudou. Se o S3 recusar a gravação ou a listagem, nada muda: o formulário e o painel mostram a resposta do S3, por exemplo archive cold: ... s3 PUT 403 AccessDenied, até um salvamento passar. Um salvamento que passa:

  • substitui o destino archive.* do chart dali em diante, reinícios incluídos (o orbit-api guarda a lista no diretório de dados, archive/archives.json). Um destino que o Deck salvou antes de os arquivos virarem lista (archive/config.json) vira o primeiro, com o nome default;
  • guarda cada lugar que um arquivo deixa, quando você o move para outro bucket, prefixo ou região ou o exclui, como origem só de leitura chamada <archive>-<YYYYMMDDHHMM> (UTC). Nada novo vai para lá; uma reidratação continua lendo. O Deck pergunta antes de mover ou excluir;
  • no primeiro salvamento, sem arquivo antes, liga métricas, traces e logs.

O próximo ciclo de envio, em até 15 segundos, segue a nova lista. Os contadores de envio (enviado, na fila, último envio, mais novo no S3, última falha) ficam por sinal e por arquivo, salvos a cada ciclo que move um arquivo ou falha, então um reinício do orbit-api os mantém. Um arquivo cujo último envio falhou aparece como Falhando, com a resposta do S3 embaixo da lista.

ValorPadrãoO que faz
archive.bucketvazioO bucket. Vazio: um admin o define em Admin > Arquivo.
archive.signals[metrics, traces, logs]O que vai para o bucket até Admin > Arquivo mudar. traces leva os spans junto; um sinal fora da lista fica só no local.
archive.prefixsreorbitO começo de toda chave.
archive.regionvazioA região do bucket; vazio é o AWS_REGION do pod, senão us-east-1.
archive.storageClassSTANDARDSTANDARD, STANDARD_IA, ONEZONE_IA, GLACIER_IR ou INTELLIGENT_TIERING.
archive.encryptionvazioVazio mantém o padrão do bucket; AES256 força SSE-S3; aws:kms força SSE-KMS com archive.kmsKeyId.
archive.kmsKeyIdvazioO ARN da chave KMS, com aws:kms. A role então precisa de kms:GenerateDataKey e kms:Decrypt nela.
archive.maxScanGB100O máximo que uma reidratação pode ler do bucket.
archive.retentionDays[1, 3, 7, 15, 30, 45, 60, 90, 180]Os períodos de retenção que uma reidratação pode escolher.
archive.maxLogs0O limite padrão de linhas de log de uma reidratação; 0 é sem limite, e cada reidratação pode definir o seu.
archive.partitions.metrics[]Até dois labels de métrica pelos quais cada bloco é dividido.
archive.partitions.logs[]Até dois entre service, namespace, pod, container e node pelos quais cada segmento de log é mapeado.
archive.restrictions{}Consultas de restrição sobre os dados reidratados, pela id do papel (metrics, logs, traces).

Com IRSA, ponha eks.amazonaws.com/role-arn em components.orbit-api.serviceAccount.annotations no lugar da associação do passo 2.

Reidratação

Quando o intervalo de uma página do Deck começa antes do que o orbit-stack guarda (ORBIT_STACK_RETENTION para métricas, ORBIT_STACK_TRACE_RETENTION para traces, ORBIT_STACK_LOGS_RETENTION para logs; o chart os copia para o web como ORBIT_RETENTION_METRICS, ORBIT_RETENTION_TRACES e ORBIT_RETENTION_LOGS), uma nota acima da página diz a partir de quando ela tem dados. Para um administrador, a nota leva a Admin > Reidratações com a janela que falta e o sinal já preenchidos.

No Deck, Admin > Arquivo tem uma linha por sinal (métricas, logs, traces, spans): o arquivo ligado ou desligado (ou falhando, com o último erro), os arquivos que o levam, em ordem, e os labels pelos quais ele é dividido, o que vai (tudo o que ele guarda; os spans vão dentro dos segmentos de traces), o último envio, a idade do dado mais novo no bucket, o que foi enviado e o que está na fila, e Desligar ou Ligar (auditado como archive.signals.update; vale depois de reinícios, e o que está na fila quando você desliga um sinal ainda é enviado). A página lê tudo isso de novo a cada 15 s. Abaixo ficam as partições e as origens só de leitura. O Trazer de volta de cada linha abre Admin > Reidratações com aquele sinal escolhido, onde você cria uma:

  • o arquivo a ler, quando há mais de um: um arquivo ou uma origem só de leitura pelo nome, ou todos eles (o padrão), cada lugar lido uma vez;
  • uma janela (fromMs, toMs) e os sinais a trazer de volta (métricas, traces, logs ou os três);
  • um filtro opcional por sinal: matchers de label para métricas ({namespace="payments"}), uma consulta de logs (service:api severity:>=WARN), um serviço e uma operação de trace;
  • um nome (uma letra minúscula, depois letras minúsculas, dígitos e -) e uma retenção de archive.retentionDays (15 dias por padrão);
  • se quiser, um limite de linhas de log: o job guarda as linhas mais antigas até ele, um segmento inteiro por vez, e informa quantas guardou;
  • se quiser, canais de alerta de Alertas > Notificações para avisar quando o job terminar: Slack, Microsoft Teams ou Google Chat recebem o nome, o estado, a janela, o tamanho lido, o número de arquivos e um link.

Estimar lista os objetos que a janela toca e soma o tamanho deles antes de qualquer execução, ao lado do espaço que o volume do orbit-stack tem para reidratações: o espaço livre menos uma reserva de um décimo do volume, no mínimo 1 GiB, que fica para o armazenamento ao vivo. Uma janela acima de archive.maxScanGB é recusada com 413, e uma acima do espaço com 507; estreite a janela ou apague uma reidratação. O orbit-stack confere o espaço de novo a cada pedaço que grava, então nem dois jobs iniciados juntos enchem o volume.

Um job passa por pending, running (com os arquivos e bytes copiados até ali) e depois active, ou failed com o motivo. Um job que falha não deixa arquivo no volume do orbit-stack. Todos os jobs, quantos estiverem rodando, dividem uma única fila de cópia de 64 MiB: cada arquivo ocupa o próprio tamanho, até 16 MiB, então quatro arquivos grandes ou até 64 pequenos (os de uma partição) são copiados de uma vez, e o orbit-api guarda no máximo 128 MiB de dados de reidratação ao mesmo tempo.

Apagar num job em execução o cancela: as cópias em andamento terminam o pedaço atual, e o job abre com os arquivos que copiou inteiros, active, com uma nota dizendo quantos de quantos. Num job ativo, Apagar interrompe as leituras e guarda os dados por um dia: Restaurar traz o job de volta como estava até lá, e depois disso os dados somem. Jobs encerrados continuam listados por um ano, mesmo com o orbit-api reiniciando, e um nome pode ser usado de novo quando o job dele termina. A trilha de auditoria registra um evento quando um job é criado, apagado, restaurado e quando termina, com o estado, o tamanho lido, os arquivos e as linhas de log, e um quando o envio começa a falhar (archive.shipping.failed, com o erro) e quando volta.

Lendo dados reidratados no Deck

O explorador de logs, o explorador de traces do APM (com a visão de trace) e o Explore têm um seletor Índice ao lado das ações da página: Ao vivo, ou uma das reidratações ativas que guardam aquele sinal. Uma reidratação escolhida mostra Do arquivo: ao lado do seletor, e na visão de trace, com link para Admin > Reidratações. Com uma reidratação escolhida, a página lê os armazenamentos daquele job na janela dele, com todos os filtros, facetas, histogramas e gráficos que tem nos dados ao vivo; o modo ao vivo fica desligado. Admin > Reidratações liga cada job ativo às três páginas. Baixar CSV salva o que a página lista, ao vivo ou reidratado: as linhas de log carregadas (5.000 no máximo), os traces listados, ou os pontos de uma consulta do Explore, pelo inspetor dela.

Uma reidratação ativa responde à própria API de leitura do motor em /api/v1/archive/rehydrations/<name>/q/: PromQL (api/v1/query, api/v1/query_range, api/v1/series, labels), api/v1/logs com histograma e facetas, api/v1/traces, um trace por id e as rotas de APM. Toda leitura fica restrita à janela e ao filtro do job, então uma reidratação filtrada nunca mostra o que o filtro deixou de fora. As leituras pedem a permissão do próprio sinal (telemetry.query, logs.read, apm.read); criar, apagar e ver o estado do arquivo pedem settings.manage. Toda criação e exclusão entra na trilha de auditoria.

Um filtro num label de partição restringe o que o job copia, e a estimativa mostra o tamanho lido ao lado do tamanho da janela (windowBytes). Qualquer outro filtro vale na leitura: o job copia os arquivos da janela inteiros, e você estreita a janela para ler menos.

Busca no arquivo

Admin > Rehydrations > Busca no arquivo faz uma leitura sobre a janela e os filtros do formulário, direto do bucket, e não deixa reidratação nenhuma. O orbit-api copia os arquivos de que a leitura precisa (as partições que os filtros citam, quando citam) para um armazenamento temporário no orbit-stack, responde a leitura pela consulta de restrição do seu papel e apaga o armazenamento. O limite de leitura e o espaço do volume valem como numa reidratação. Use para achar algo pontual: um trace id, um usuário, os erros de um namespace de um mês atrás.

Consultas de restrição

archive.restrictions dá a um papel uma consulta de restrição sobre os dados reidratados: label matchers para métricas, termos de consulta de logs e o único serviço cujos traces ele lê, pela id do papel.

text
archive:
  restrictions:
    viewer:
      metrics: '{namespace="payments"}'
      logs: "namespace:payments"
      traces: checkout

Um membro de viewer lê toda reidratação com esses termos somados ao filtro do job, nas páginas do Deck e na API: os seletores PromQL ganham os matchers, as leituras de log ganham os termos. Buscas de traces e leituras de spans ficam no serviço, e um trace abre só com os spans desse serviço. A lista de serviços e o mapa de serviços mostrariam todos os serviços, então o papel recebe 403 neles, e um job filtrado para outro serviço também responde 403. Papéis sem entrada leem só o filtro do job.

Limites

  • A janela de uma reidratação tem no máximo 31 dias, e no máximo oito reidratações ficam abertas ao mesmo tempo. Juntas, elas usam o cache de um armazenamento ao vivo.
  • O limite de linhas de log conta segmentos inteiros, então um job guarda até o limite, não exatamente o limite.
  • Uma reidratação lista no máximo 200.000 objetos por sinal.
  • Glacier Flexible Retrieval e Deep Archive exigem restauração antes; mova esses objetos de volta para uma classe da tabela antes de reidratá-los.
  • O orbit-stack guarda a outbox no próprio volume até o orbit-api enviá-la: enquanto o bucket está inacessível, a outbox cresce com o que o motor sela. GET /api/v1/archive mostra o backlog, e o /metrics do orbit-api exporta orbit_archive_backlog_bytes, orbit_archive_last_shipped_timestamp_seconds e orbit_archive_last_error_timestamp_seconds para alertar.
  • Os arquivos estão nos formatos de bloco e segmento do próprio orbit-stack. Leia-os de volta com o orbit-stack.

API

RotaPermissãoO que faz
GET /api/v1/archivesettings.manageA configuração (config, null antes de existir um arquivo: archives em ordem, retired as origens só de leitura, retentionDays, maxLogs; configError quando os valores do chart são inválidos; setIn, deck ou chart; refused, o último salvamento recusado), os contadores de envio, byArchive (os contadores de cada arquivo pelo nome) e signals: por sinal, on, as partitions, o próprio shipping (com newestMs e skippedFiles) e archives, os nomes dos arquivos que o levam, em ordem.
PUT /api/v1/archive/configsettings.manage{archives: [{name, bucket, prefix, region, storageClass, encryption, kmsKeyId, maxScanGB, filter, signals, enabled}], partitions: {metrics, logs}}: a lista inteira, em ordem, acima dos valores do chart, depois de uma gravação de teste em cada arquivo novo ou alterado. No máximo 32 arquivos, um nome cada. 400 com a resposta do S3 quando um bucket a recusa, ou quando um valor não é aceito pelo S3; 502 quando o orbit-stack recusa as partições. Auditado como archive.config.update, recusas incluídas.
PUT /api/v1/archive/signalssettings.manage{"metrics": true, "traces": false, "logs": true}: o que o orbit-stack enfileira daqui em diante, mantido depois de reinícios; um sinal fora do corpo mantém o estado. Auditado.
POST /api/v1/archive/estimatesettings.manage{fromMs, toMs, signals, metrics, logs, archive} (archive: um arquivo ou origem só de leitura pelo nome; sem ele, lê todos): os objetos e bytes que a janela lê depois das partições que os filtros deixam de fora (scanBytes, e windowBytes antes disso), por arquivo (byArchive), se a parte de algum arquivo passa do limite dele (overLimit; maxScanBytes soma os limites) e o espaço do orbit-stack (freeBytes, overFree).
GET /api/v1/archive/rehydrationssettings.manage ou logs.readTodas as reidratações com estado, progresso, expiração, limite de logs e linhas guardadas.
POST /api/v1/archive/rehydrationssettings.manageInicia uma: {name, fromMs, toMs, signals, metrics, logs, service, operation, retentionDays, maxLogs, notify, archive}. 202, 413 acima do limite de leitura ou 507 acima do espaço do volume, os dois com a estimativa.
DELETE /api/v1/archive/rehydrations/<name>settings.manageCancela um job em execução, que abre com os arquivos que copiou inteiros; num ativo, interrompe as leituras e guarda os dados por um dia (purgeMs).
POST /api/v1/archive/rehydrations/<name>/restoresettings.manageDesfaz a exclusão dentro desse dia.
POST /api/v1/archive/searchsettings.manageBusca no arquivo: {fromMs, toMs, signals, metrics, logs, service, operation, read, params}, com read um caminho de leitura do motor (/api/v1/logs, /api/v1/query, ...). Responde com o status da leitura e {scanBytes, windowBytes, files, secsToCopy, secs, answer}; 413 acima do limite de leitura ou do espaço.
GET /api/v1/archive/rehydrations/<name>/q/<read>a do sinalUma leitura dos dados reidratados, restrita à janela e ao filtro. Um segmento de caminho que seja . ou .. codificado (%2e%2e) é recusado com 400 em toda rota.