O esquema padrão do ClickStack armazena atributos de recurso, escopo, log e span como colunas Map(LowCardinality(String), String). O ClickHouse também oferece suporte ao tipo JSON, com tipagem forte, e o ClickStack oferece suporte beta para usá-lo no lugar de Map.
Para cargas de trabalho típicas de observabilidade, recomendamos manter o esquema padrão baseado em Map. O tipo JSON está disponível para usuários que desejam avaliá-lo em cargas de trabalho com um conjunto pequeno e estável de chaves de atributo, mas não é o esquema recomendado para uso geral.
Por que Map é o padrão recomendado
Map(LowCardinality(String), String) armazena chaves e valores em uma única estrutura. A desvantagem histórica de Map era que ler uma única chave exigia ler toda a coluna de map. Isso não é mais verdade: o ClickHouse agora oferece suporte à serialização de map em buckets, que divide o map em buckets para que as consultas leiam apenas os buckets de que precisam. Em combinação com índices de texto nas chaves e nos valores do map — que é como o esquema padrão do ClickStack é configurado — isso torna Map seletivo e rápido na leitura, sem nenhum custo adicional de ingestão para novas chaves.
Na prática, isso significa:
- Custo de ingestão estável à medida que o número de chaves cresce. Adicionar uma nova chave de atributo não altera o layout da coluna em disco nem cria novos arquivos de coluna. O custo de ingestão é limitado pelo volume de dados, não pela cardinalidade das chaves.
- Sem explosão de metadados. O número de arquivos de coluna em disco não acompanha o número de chaves de atributo únicas.
- Lookups seletivos via índices. Índices de texto nas chaves e nos valores do map permitem lookups pontuais sem varrer todas as linhas.
- Comportamento previsível em alta vazão. Map lida com conjuntos de atributos variáveis e sem esquema definido, comuns em tracing e logs, sem sobrecarga por chave.
Por que não usar JSON por padrão
JSON adota uma abordagem diferente: na inserção, o ClickHouse cria dinamicamente uma subcoluna dedicada e fortemente tipada para cada path encontrado. Na leitura, isso é atraente, pois apenas as subcolunas solicitadas são lidas, os tipos são preservados e não é necessário fazer conversão de tipo durante a consulta.
A contrapartida aparece na ingestão. Criar e gerenciar muitas subcolunas dinâmicas introduz sobrecarga de escrita e complexidade nos metadados. Em workloads de observabilidade, que rotineiramente têm conjuntos de atributos muito grandes ou altamente dinâmicos e alta taxa de ingestão, essa sobrecarga é significativa. O limite max_dynamic_paths pode reduzir o impacto ao despejar paths extras em uma coluna compartilhada, mas acessar a coluna compartilhada é mais lento do que acessar subcolunas dedicadas, o que enfraquece a vantagem de leitura que motivou o uso de JSON em primeiro lugar.
Como a serialização de map em buckets elimina a maior parte da sobrecarga histórica de leitura de Map, a vantagem de JSON na leitura já não compensa seu custo de ingestão em workloads típicos de observabilidade.
Quando ainda vale a pena considerar JSON
- O conjunto de chaves dos seus atributos é pequeno e estável, ou seja, você não vê milhares de chaves exclusivas, e novas chaves aparecem raramente.
- A vazão de ingestão é modesta em relação à cardinalidade dos atributos.
- Você quer acesso fortemente tipado aos atributos, sem conversões em tempo de consulta (números continuam sendo números, booleanos continuam sendo booleanos).
- Você está disposto a operar uma funcionalidade beta no ClickStack e aceita que a integração pode mudar.
Se nem todas essas condições forem atendidas, mantenha o esquema padrão baseado em Map.
Recurso beta, não pronto para produçãoO suporte ao tipo JSON no ClickStack é um recurso beta. Embora o próprio tipo JSON esteja pronto para produção no ClickHouse 25.3+, sua integração ao ClickStack ainda está em desenvolvimento ativo e pode ter limitações, mudar no futuro ou conter bugs.
2.0.4.
Habilitando o suporte a JSON
Map, defina as seguintes variáveis de ambiente.
| Variável | Definido em | Finalidade |
|---|
OTEL_AGENT_FEATURE_GATE_ARG='--feature-gates=clickhouse.json' | OTel collector | Cria esquemas no ClickHouse usando o tipo JSON. |
BETA_CH_OTEL_JSON_SCHEMA_ENABLED=true | HyperDX (UI do ClickStack) | Habilita a camada de aplicação a consultar esquemas do tipo JSON. Somente no ClickStack open source. |
OTEL_AGENT_FEATURE_GATE_ARG='--feature-gates=clickhouse.json' no coletor. Por exemplo:
docker run -e OTEL_AGENT_FEATURE_GATE_ARG='--feature-gates=clickhouse.json' -e CLICKHOUSE_ENDPOINT=${CLICKHOUSE_ENDPOINT} -e CLICKHOUSE_USER=default -e CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD} -p 8080:8080 -p 4317:4317 -p 4318:4318 clickhouse/clickstack-otel-collector:latest
ClickStack de código aberto
OTEL_AGENT_FEATURE_GATE_ARG='--feature-gates=clickhouse.json' em qualquer implantação que inclua o coletor e BETA_CH_OTEL_JSON_SCHEMA_ENABLED=true na camada da aplicação HyperDX para que ela possa consultar os esquemas do tipo JSON.
Por exemplo:
docker run -e OTEL_AGENT_FEATURE_GATE_ARG='--feature-gates=clickhouse.json' -e OPAMP_SERVER_URL=${OPAMP_SERVER_URL} -e CLICKHOUSE_ENDPOINT=${CLICKHOUSE_ENDPOINT} -e CLICKHOUSE_USER=default -e CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD} -p 8080:8080 -p 4317:4317 -p 4318:4318 clickhouse/clickstack-otel-collector:latest
Migrando de um esquema baseado em Map para JSON
Compatibilidade retroativaO tipo JSON não é compatível com versões anteriores de esquemas baseados em map. Ativar esse recurso cria novas tabelas usando o tipo JSON e exige migração manual dos dados. Interrompa o OTel collector
Renomeie as tabelas existentes e atualize as fontes de dados
Renomeie as tabelas existentes e atualize as fontes de dados no HyperDX.Por exemplo:RENAME TABLE otel_logs TO otel_logs_map;
RENAME TABLE otel_metrics TO otel_metrics_map;
Implante o collector
Implante o collector com OTEL_AGENT_FEATURE_GATE_ARG definido.export BETA_CH_OTEL_JSON_SCHEMA_ENABLED=true
Crie novas fontes de dados
Crie novas fontes de dados no HyperDX apontando para as tabelas JSON.Migração de dados existentes (opcional)
INSERT INTO otel_logs SELECT * FROM otel_logs_map;
INSERT INTO otel_metrics SELECT * FROM otel_metrics_map;
Recomendado apenas para conjuntos de dados menores que ~10 bilhões de linhas. Os dados armazenados anteriormente com o tipo map não preservavam a precisão dos tipos (todos os valores eram strings). Como resultado, esses dados antigos aparecerão como strings no novo esquema até expirarem, exigindo algumas conversões de tipo no frontend. Os tipos dos novos dados serão preservados com o tipo JSON.
