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.
ClickStack e HyperDX
O Loom sempre emite OpenTelemetry; as fontes do HyperDX, os painéis e a etapa de exclusão precisam ser configurados.
O Loom emite um span por operação, além de logs e métricas. Os spans carregam loom.operation,
loom.org, loom.namespace, loom.agent, loom.request_id e loom.user_id /
enduser.id quando presentes. Por padrão, o Loom os insere diretamente nas
tabelas default.otel_* do seu próprio serviço ClickHouse, no schema do coletor, de modo que o
HyperDX os lê sem nenhum coletor para executar. Com LOOM_CLICKSTACK_DATABASE definido, as
tabelas ficam nesse banco de dados em vez de default, aqui e em todas as consultas abaixo. O layout das colunas está em
schemas/otel/clickstack_otel_tables.sql; se o ClickStack mudar o schema, esse arquivo
deve acompanhar a mudança.
Os spans de chamadas de modelo carregam os atributos GenAI do OpenTelemetry (telemetria) nas chaves que a visualização de LLM do HyperDX lê para o provedor, a operação, o uso de tokens, a parcela de cache de prompt e o custo.
Escolha o caminho de exportação
LOOM_OTEL_EXPORTER |
Comportamento |
|---|---|
ch |
insere em default.otel_traces, otel_logs, otel_metrics_sum, otel_metrics_histogram e otel_metrics_gauge no mesmo serviço |
otlp |
envia para LOOM_OTEL_EXPORTER_OTLP_ENDPOINT (cabeçalhos em LOOM_OTEL_EXPORTER_OTLP_HEADERS), para um collector ou outro backend |
| vazio (padrão) | otlp quando um endpoint está definido; caso contrário, ch |
No modo ch, o Loom primeiro verifica se default.otel_traces existe; sem ela, o
exportador se desativa após uma linha de log. Para criar as tabelas:
clickhouse-client --multiquery < schemas/otel/clickstack_otel_tables.sql
GET /v1/health?include=otel mostra o exportador resolvido. As demais configurações de OTel
(intervalo de exportação, temporalidade, heartbeat do gauge, nome do serviço) estão em
telemetria.
Aponte o HyperDX para as tabelas
As linhas já estão no serviço, então pule as etapas do coletor e da chave de ingestão.
Crie três sources do HyperDX: traces sobre otel_traces, logs sobre otel_logs,
métricas sobre otel_metrics_*. O deploy/clickstack_sources.sh as cria pela API do
HyperDX e configura a correlação entre elas (o ClickStack hospedado autentica com o cookie
de sessão do seu console, HDX_COOKIE).
O arquivo deploy/hyperdx_dashboards.md traz o
mapeamento de campos de cada source.
Painéis e alertas
deploy/hyperdx_dashboards.md é o livro de receitas:
- Loom — Memory Health: tendência da qualidade de recuperação (
loom.search.top_similarity), chamadas e erros por operação e transporte, estado do sistema, gasto e tokens, latência por plano de recuperação, resultados de escrita e painéis de requisições (taxa, latência, erros, requisições mais lentas, tráfego por tenant, logs de um trace). - Loom — Code Plane: atraso do índice, atraso da camada e os demais gauges
loom.code.*. A definição em JSON está emdeploy/dashboards/code_plane.json. - A ordem de bootstrap e as buscas salvas.
Duas armadilhas ao escrever seus próprios tiles:
- Os contadores são cumulativos. A menos que
LOOM_OTEL_METRICS_DELTA_TEMPORALITY=true, a linha de um contador é o seu total acumulado; uma taxa precisa da diferença entre pontos consecutivos, não de uma soma. Altere a configuração e os painéis ao mesmo tempo. - Um resultado vazio é lido como 0 no HyperDX. Uma proteção de amostra mínima em um alerta deve retornar um valor dentro da faixa saudável, e não nenhuma linha, ou o alerta dispara no silêncio.
Os nomes das métricas e os limites sugeridos estão no catálogo de métricas.
Apagamento
Requer LOOM_CLICKSTACK_DATABASE. O ClickStack não tem uma API de administração para excluir dados de usuários,
então o backend (ClickStackBackend em server/erasure/app/backends.py) executa instruções
DELETE FROM leves nas tabelas OTel desse banco de dados:
| Tabela | Coluna de atributos pesquisada |
|---|---|
otel_logs |
LogAttributes |
otel_traces |
SpanAttributes |
otel_metrics_gauge, _sum, _histogram, _exponential_histogram, _summary |
Attributes |
hyperdx_sessions |
ResourceAttributes |
- Um escopo de usuário corresponde a qualquer uma das chaves em
LOOM_CLICKSTACK_USER_ID_KEYS(padrãouser_id,user.id,enduser.id,loom.user_id,langfuse.user.id), combinadas com OR, já que os SDKs divergem quanto ao nome da chave. O span de requisição do Loom carregaenduser.id; seus spans de chamada de modelo carregamloom.user_idelangfuse.user.id, e, com o Langfuse configurado, o mesmo vale para todos os outros spans que a requisição abre depois que o chamador é resolvido. Cada um deles também carregaloom.org, portanto a proteção de org abaixo se aplica. - Um escopo de namespace corresponde a
loom.namespaceouservice.namespace. O exportador do Loom defineservice.namespacecomo a constanteloome carrega o tenant emloom.namespace;service.namespacecobre outros emissores que gravam no mesmo ClickStack, e seu valorloomnunca é correspondido. - Proteção de org. Uma linha marcada com o
loom.orgde outra org nunca é apagada. Uma linha correspondida porloom.namespacedeve carregar oloom.orgda org que está apagando. As métricas de op e de domínio do Loom (contadores e histogramas) carregamloom.namespacee nenhuma org, então um apagamento de namespace as deixa: elas não guardam conteúdo de memória, mas o rótuloloom.namespacedelas é o nome do namespace, que, no caso de um namespace pessoal, é derivado do e-mail do usuário. Elas permanecem até que o TTL da própria tabela do coletor, se houver, as remova. Uma linha sem a tagloom.orgcorrespondida por uma chave de usuário ou porservice.namespace(outro emissor) é apagada, pois pode conter o titular dos dados.
Um delete leve grava apenas a máscara de existência da linha, então as linhas somem de toda leitura
imediatamente e os bytes saem no próximo merge; ALTER TABLE … DELETE reescreveria todas as
partes afetadas. O predicado varre qualquer tabela sem um bloom filter nos valores do map de atributos
(as tabelas de métricas não têm um); loom doctor as nomeia.
A etapa conta as linhas antes de excluir e informa essa contagem. Uma tabela ou banco de dados ausente
conta como nada a apagar; qualquer outra falha faz a etapa falhar de forma fechada, e o
worker erasure_recovery tenta novamente.
Verifique quais chaves de ID de usuário seus dados realmente carregam antes de confiar nos padrões:
SELECT DISTINCT arrayJoin(mapKeys(LogAttributes))
FROM default.otel_logs WHERE TimestampTime > now() - INTERVAL 1 DAY
Veja retenção e apagamento para a saga da qual esta etapa faz parte.
Configurações
| Configuração | Padrão | Efeito |
|---|---|---|
LOOM_OTEL_EXPORTER |
"" |
ch, otlp ou automático |
LOOM_OTEL_EXPORTER_OTLP_ENDPOINT |
"" |
URL base do coletor |
LOOM_OTEL_EXPORTER_OTLP_HEADERS |
"" |
cabeçalhos K=V separados por vírgula |
LOOM_OTEL_ENABLED |
true |
chave geral |
LOOM_CLICKSTACK_DATABASE |
"" |
o banco de dados das tabelas OTel; habilita a exclusão |
LOOM_CLICKSTACK_USER_ID_KEYS |
user_id,user.id,enduser.id,loom.user_id,langfuse.user.id |
chaves de atributo que uma exclusão por usuário correlaciona |
Relacionados
- Telemetria: o que é emitido e o catálogo completo de métricas.
- Monitoramento.
- Langfuse: os mesmos spans como traces de chamadas de modelo.