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:
<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:
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.partsliga 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>.partsliga 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
- 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.
- 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):
CLUSTER=my-eks NAMESPACE=sreorbit RELEASE=sreorbit ARCHIVE_BUCKET=my-archive \
deploy/aws/setup-pod-identity.shA 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:
helm upgrade sreorbit deploy/helm/sreorbit --reuse-values \
--set archive.enabled=true --set archive.bucket=my-archiveCom 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 nomedefault; - 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.
| Valor | Padrão | O que faz |
|---|---|---|
archive.bucket | vazio | O 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.prefix | sreorbit | O começo de toda chave. |
archive.region | vazio | A região do bucket; vazio é o AWS_REGION do pod, senão us-east-1. |
archive.storageClass | STANDARD | STANDARD, STANDARD_IA, ONEZONE_IA, GLACIER_IR ou INTELLIGENT_TIERING. |
archive.encryption | vazio | Vazio mantém o padrão do bucket; AES256 força SSE-S3; aws:kms força SSE-KMS com archive.kmsKeyId. |
archive.kmsKeyId | vazio | O ARN da chave KMS, com aws:kms. A role então precisa de kms:GenerateDataKey e kms:Decrypt nela. |
archive.maxScanGB | 100 | O 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.maxLogs | 0 | O 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 dearchive.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:
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.
archive:
restrictions:
viewer:
metrics: '{namespace="payments"}'
logs: "namespace:payments"
traces: checkoutUm 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/archivemostra o backlog, e o/metricsdo orbit-api exportaorbit_archive_backlog_bytes,orbit_archive_last_shipped_timestamp_secondseorbit_archive_last_error_timestamp_secondspara 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
| Rota | Permissão | O que faz |
|---|---|---|
GET /api/v1/archive | settings.manage | A 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/config | settings.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/signals | settings.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/estimate | settings.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/rehydrations | settings.manage ou logs.read | Todas as reidratações com estado, progresso, expiração, limite de logs e linhas guardadas. |
POST /api/v1/archive/rehydrations | settings.manage | Inicia 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.manage | Cancela 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>/restore | settings.manage | Desfaz a exclusão dentro desse dia. |
POST /api/v1/archive/search | settings.manage | Busca 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 sinal | Uma 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. |