As páginas sem tradução abrem em inglês e são identificadas como inglês.
Esta página é uma tradução automática da página em inglês, que prevalece. Machine-translated from the English page, which is authoritative.
Exportando o uso para um data warehouse
loom export-analytics grava um dia UTC de uso e um snapshot dos namespaces em um bucket S3 como arquivos Parquet, um arquivo por entidade por dia, para que um data warehouse os carregue. O chart do Helm o executa uma vez por dia como um CronJob (analyticsExport em values.yaml). Para consultar as memórias de um tenant, com o conteúdo delas, e o seu ledger de requisições no próprio local, use a superfície SQL.
loom export-analytics --bucket analytics-landing --prefix loom \
--role-arn arn:aws:iam::123456789012:role/loom-analytics-writer \
--expected-bucket-owner 123456789012
Ele precisa de LOOM_ANALYTICS_EXPORT_NAME_KEY, o segredo sob o qual os nomes são gerados como hash (veja nomes com hash).
--day YYYY-MM-DD exporta outro dia; o padrão é ontem (UTC). Um dia que ainda não terminou é recusado.
Arquivos
<prefix>/<entity>/<yyyy>/<mm>/<dd>/<entity>-<yyyy>-<mm>-<dd>.parquet entity: usage, namespaces
Cada upload leva If-None-Match: *, então um objeto nunca é substituído. Uma segunda execução de um
dia mantém os arquivos da primeira execução e imprime already there, kept para cada um; uma execução que falhou ou
foi repetida pode ser tentada de novo como está. Para exportar um dia novamente, apague antes os objetos dele.
| Entidade | Uma linha por | Colunas |
|---|---|---|
usage |
org, namespace, agent, operation, kind, transport, traffic_class do dia, a partir de loom.agent_events |
day, ops, errors, server_errors, slow, input_tokens, output_tokens, embedding_tokens, llm_calls, cost_usd, bytes_written, latency_p50_ms, latency_p95_ms, latency_p99_ms, users, sessions, snapshot_at |
namespaces |
org, namespace registrado em loom.namespaces ou que contém uma linha de memória ativa |
registered, kind, visibility, active, created_on, live_memories, last_memory_on, day, snapshot_at |
kind em usage é request para uma requisição, worker para uma passagem do worker, verdict para uma
verificação de consistência adiada de memory.ask e settle para uma resolução de conflito adiada. Toda
rota /v1/me/* é uma única operation, me: o ledger nomeia essas linhas conforme o caminho da requisição,
que pode conter qualquer string enviada por um chamador. users e sessions são contagens distintas
dentro da linha, que deixam de fora o - de uma chamada que não informou nenhum; uma soma entre linhas conta um
usuário uma vez por linha. slow e os quantis de latência são os do rollup de SLI: contam as
requisições ok que esse rollup lê (uma operação com uma classe de SLO), e slow conta as que passaram do
orçamento de latência (um orçamento de 0 torna todas lentas); uma linha sem nenhuma tem latências de 0.
Uma rota /v1/me/*, um julgamento adiado ou uma passagem do worker não conta em nenhum dos dois. O
arquivo namespaces é o estado em snapshot_at, seja qual for o --day: um backfill de um
dia antigo recebe o uso daquele dia e os namespaces de hoje. Um namespace não registrado tem
registered = false e colunas de registro NULL. created_on e last_memory_on são dias,
não horários: um horário exato ao lado de um namespace pessoal com hash poderia ser associado à pessoa
que se cadastrou ou escreveu naquele momento. As linhas são ordenadas pelos nomes com hash, nunca pelos próprios
nomes.
O que nunca sai do Loom
As colunas formam uma lista de permissões (server/insights/store/analytics_export.py; o teste de integração fixa a lista exata de colunas de cada entidade). Um arquivo no bucket fica fora do apagamento, então a exportação não contém conteúdo de memória nem identificador armazenado de pessoas: nenhuma chave ou valor de memória, nenhum args, nenhum user_id, session_id, subject, owner_email ou id de requisição. Usuários e sessões saem apenas como contagens.
Nomes com hash
Os nomes de org, namespace e agente podem identificar uma pessoa: um namespace pessoal recebe o nome do e-mail do seu proprietário, o autocadastro monta o namespace e o nome de um agente a partir do nome de usuário do sistema operacional e do host, e um cliente MCP dá nome ao seu agente. Por isso, org, namespace e agent sempre saem como o hexadecimal em minúsculas do SipHash-2-4-128 de referência do nome, sob uma chave secreta.
Cada nome recebe o hash isoladamente, então uma mesma string tem um único hash onde quer que apareça: um nome de namespace gera o mesmo hash em todas as orgs, e uma org, um namespace e um agente com o mesmo nome compartilham o hash. O data warehouse consegue relacionar essas linhas sem a chave, por exemplo o mesmo namespace pessoal em duas orgs.
- A chave é uma string aleatória de 32 ou mais caracteres em
LOOM_ANALYTICS_EXPORT_NAME_KEY; a exportação se recusa a rodar com uma chave mais curta ou vazia, ou com espaço em branco no início ou no fim (um Secret criado com--from-filemantém a quebra de linha do arquivo, e isso faria todo hash depender dela). -
A chave de 16 bytes do SipHash são os primeiros 16 bytes do SHA-256 dessa string (UTF-8). O hash é o
sipHash128ReferenceKeyeddo ClickHouse, que qualquer biblioteca de SipHash-2-4-128 reproduz a partir desses 16 bytes, de modo que um sistema que possui a chave pode aplicar o hash aos seus próprios ids para fazer o join. O ClickHouse recebe a chave como duas palavras, cada metade de 8 bytes lida em little-endian. Aplique o hash ao id como a mesma string que o Loom armazena (toStringde um UUID ou de um número): o SipHash de uma coluna tipada calcula o hash da forma binária, que nunca coincide.WITH SHA256({key:String}) AS d SELECT lower(hex(sipHash128ReferenceKeyed( (reinterpretAsUInt64(substring(d, 1, 8)), reinterpretAsUInt64(substring(d, 9, 8))), toString(tenant_id)))) AS hashed_tenant_id FROM tenants
- Um hash é um pseudônimo, não um valor anônimo: quem possui a chave pode recalculá-lo a partir de um nome que conheça. Apagar um namespace no Loom não remove as linhas dele que já estão no bucket.
- Um hash permanece estável enquanto a chave não muda. Uma nova chave altera todos os hashes, e um dia já exportado mantém seus arquivos antigos: exclua-os antes de exportá-lo novamente com a nova chave.
- Uma consulta que usa a chave a registra, seja a chave passada como parâmetro ou escrita como literal: o ClickHouse substitui os valores passados no texto da consulta em
system.query_loge os grava nos logs de debug e de trace. No data warehouse, restrinja quem pode ler esses logs no servidor que executa o join, ou aplique o hash aos ids fora do ClickHouse com qualquer biblioteca de SipHash-2-4-128. Do lado do Loom, as palavras da chave da exportação vão parar nos mesmos logs do ClickHouse do Loom, cujos leitores já podem ler os nomes.
Credenciais
O comando usa as credenciais padrão da AWS do seu processo e as verifica uma vez antes de
qualquer trabalho no ClickHouse: com --role-arn, assumindo a role; sem ele, perguntando ao STS
a quem elas pertencem (GetCallerIdentity). Credenciais ausentes ou expiradas, ou uma role que não pode
ser assumida, falham nesse ponto, e não depois da leitura; a falta da permissão s3:PutObject, um bucket incorreto
ou um proprietário do bucket diferente de --expected-bucket-owner falha no primeiro upload. Com
--role-arn, o comando assume a role novamente antes de cada upload e grava com as credenciais dela.
Assumir uma role de escrita é adequado para um bucket em outra conta: a conta do bucket concede
s3:PutObject à role de escrita, e a role de escrita confia apenas na identidade da própria exportação.
A exportação não precisa de nenhuma permissão de leitura, listagem ou exclusão no bucket; um bucket
criptografado com uma chave KMS gerenciada pelo cliente também precisa de kms:GenerateDataKey nessa chave para
a role de escrita, caso contrário todo upload é recusado. --expected-bucket-owner faz o S3 recusar a
gravação quando outra conta é proprietária do bucket.
Passe --region (a do bucket, analyticsExport.region no chart), a menos que o processo
já tenha uma definida por AWS_DEFAULT_REGION ou pelo arquivo de configuração da AWS; o boto3 não lê
AWS_REGION neste caso.
No Kubernetes
analyticsExport:
enabled: true
bucket: analytics-landing
prefix: loom
roleArn: arn:aws:iam::123456789012:role/loom-analytics-writer
expectedBucketOwner: "123456789012"
nameKeySecret:
name: loom-analytics-export-key # key LOOM_ANALYTICS_EXPORT_NAME_KEY
serviceAccount:
annotations:
eks.amazonaws.com/role-arn: arn:aws:iam::210987654321:role/loom-analytics-export
kubectl create secret generic loom-analytics-export-key \
--from-literal=LOOM_ANALYTICS_EXPORT_NAME_KEY="$(openssl rand -hex 32)"
Somente o pod da exportação lê esse Secret. O chart se recusa a renderizar sem
nameKeySecret.name e recusa tudo o que entregaria a chave a todos os pods web e workers:
LOOM_ANALYTICS_EXPORT_NAME_KEY em env, extraEnv ou secrets.extra,
analytics_export_name_key em settingsFile (um ConfigMap que todos os pods montam) e um
nameKeySecret.name que seja o Secret da release (secrets.existingSecret ou o do próprio
chart) ou um Secret de envFrom. Ele não consegue ver o conteúdo desses Secrets: mantenha a chave fora
deles.
O chart cria uma ServiceAccount <fullname>-analytics-export e um CronJob com o mesmo
nome, em que <fullname> é o nome completo do chart: fullnameOverride quando definido; caso contrário, o nome
da release quando ele contém o nome do chart (nameOverride, senão loom); caso contrário,
<release>-<chart name>, cortado nos primeiros 35 caracteres para que o nome fique dentro de 52
(kubectl get sa mostra o nome). O job roda às 00:30 UTC (schedule), uma execução por vez,
com até 3 novas tentativas e um prazo de três horas somando todas as tentativas; cada instrução pode rodar
20 minutos, e o cliente do ClickHouse pode repetir uma delas, então um dia lento pode ter menos de quatro
tentativas. Uma recusa (exit 2) faz o Job falhar imediatamente, sem novas tentativas. O pod dele não herda nada
de podLabels, podAnnotations ou affinity dos pods web.
Os pods web e workers mantêm a própria ServiceAccount, então o role que pode assumir o
role de escrita fica vinculado somente ao pod da exportação. Com IRSA, a relação de confiança desse role cita
system:serviceaccount:<namespace>:<fullname>-analytics-export. Com roleArn definido, a
única permissão dele é sts:AssumeRole em roleArn; com roleArn vazio, ele mesmo escreve e
precisa de s3:PutObject no bucket (e kms:GenerateDataKey em uma chave KMS gerenciada
pelo cliente). Com EKS Pod Identity, vincule o role à ServiceAccount e deixe annotations
vazio.
O job lê o ClickHouse com o Secret, as configurações, o extraEnv e os
extraVolumes da release, como fazem os pods web, e não grava nada nele. Uma execução com falha aparece como um
Job com falha; configure um alerta para quando a última execução bem-sucedida do CronJob tiver mais de um dia.
Um dia cuja execução falha em todas as tentativas, ou que perde a janela de início
(startingDeadlineSeconds, uma hora), não é exportado depois por conta própria: a próxima execução
exporta apenas o dia anterior a ela. Exporte-o com um Job criado a partir do CronJob, para que rode
com a ServiceAccount e os flags da exportação, adicionando --day ao comando dele:
kubectl create job --from=cronjob/<fullname>-analytics-export analytics-export-backfill \
--dry-run=client -o yaml > backfill.yaml
# add `- --day=YYYY-MM-DD` to the container's command in backfill.yaml, then:
kubectl apply -f backfill.yaml
O arquivo de uso é o daquele dia; o arquivo de namespaces é o snapshot do momento da execução.