El esquema predeterminado de ClickStack almacena los atributos de recurso, scope, log y span en columnas Map(LowCardinality(String), String). ClickHouse también admite un tipo fuertemente tipado JSON, y ClickStack ofrece soporte beta para usarlo en lugar de Map.
Para las cargas de trabajo típicas de observabilidad, recomendamos mantener el esquema predeterminado basado en Map. El tipo JSON está disponible para los usuarios que quieran evaluarlo en cargas de trabajo con un conjunto pequeño y estable de claves de atributos, pero no es el esquema recomendado para un uso general.
Por qué Map es la opción predeterminada recomendada
Map(LowCardinality(String), String) almacena claves y valores en una sola estructura. La desventaja histórica de Map era que leer una sola clave obligaba a leer toda la columna Map. Eso ya no es así: ClickHouse ahora admite bucketed map serialization, que divide el map en buckets para que las queries solo lean los buckets que necesitan. En combinación con text indexes en las claves y valores del map, que es como está configurado el esquema predeterminado de ClickStack, esto hace que Map sea selectivo y rápido en lectura sin añadir ninguna penalización de ingesta por nuevas claves.
En la práctica, esto significa:
- Costo de ingesta estable a medida que crecen las claves. Añadir una nueva clave de atributo no cambia el layout de columnas en disco ni crea nuevos archivos de columna. El costo de ingesta está limitado por el volumen de datos, no por la cardinalidad de las claves.
- Sin explosión de metadatos. La cantidad de archivos de columna en disco no sigue la cantidad de claves de atributo únicas.
- Lookups selectivos mediante índices. Los text indexes en las claves y los valores del map permiten lookups puntuales sin escanear cada fila.
- Comportamiento predecible con alto throughput. Map maneja conjuntos de atributos variables y sin esquema, comunes en tracing y logs, sin sobrecarga por clave.
El tipo JSON adopta un enfoque diferente: en el momento de la inserción, ClickHouse crea dinámicamente una subcolumna dedicada y con tipado fuerte para cada ruta que detecta. En el momento de la lectura, esto resulta atractivo, ya que solo se leen las subcolumnas solicitadas, los tipos se conservan y no hace falta convertir tipos en tiempo de consulta.
La contrapartida aparece en el momento de la ingesta. Crear y gestionar muchas subcolumnas dinámicas introduce sobrecarga en el momento de la escritura y complejidad en los metadatos. En las cargas de trabajo de observabilidad, que habitualmente tienen conjuntos de atributos muy grandes o muy dinámicos y un alto rendimiento de ingesta, esa sobrecarga es significativa. El límite max_dynamic_paths puede limitar el impacto volcando las rutas adicionales en una columna compartida, pero acceder a la columna compartida es más lento que acceder a subcolumnas dedicadas, lo que erosiona la ventaja en tiempo de lectura que motivó el uso de JSON en primer lugar.
Dado que la serialización en buckets de Map elimina la mayor parte de la sobrecarga histórica en tiempo de lectura de Map, la ventaja en tiempo de lectura de JSON ya no compensa su coste en tiempo de ingesta para las cargas de trabajo de observabilidad típicas.
Cuándo todavía conviene considerar JSON
- El conjunto de claves de tus atributos es pequeño y estable, es decir, no ves miles de claves únicas y rara vez aparecen claves nuevas.
- El throughput de ingesta es moderado en relación con la cardinalidad de los atributos.
- Quieres acceso con tipado fuerte a los atributos sin conversiones de tipo en tiempo de consulta (los números siguen siendo números y los valores booleanos siguen siendo booleanos).
- Estás dispuesto a usar una funcionalidad beta en ClickStack y aceptas que la integración puede cambiar.
Si no se cumplen todas esas condiciones, sigue usando el esquema predeterminado basado en Map.
Funcionalidad beta, no está lista para producciónLa compatibilidad con el tipo JSON en ClickStack es una funcionalidad beta. Aunque el propio tipo JSON está listo para producción en ClickHouse 25.3+, su integración en ClickStack sigue en desarrollo activo y puede tener limitaciones, cambiar en el futuro o contener errores.
2.0.4.
Habilitar la compatibilidad con JSON
Map, configure las siguientes variables de entorno.
| Variable | Configurar en | Propósito |
|---|
OTEL_AGENT_FEATURE_GATE_ARG='--feature-gates=clickhouse.json' | OTel collector | Crea esquemas en ClickHouse con el tipo JSON. |
BETA_CH_OTEL_JSON_SCHEMA_ENABLED=true | HyperDX (UI de ClickStack) | Habilita la capa de aplicación para consultar esquemas de tipo JSON. Solo en ClickStack Open Source. |
OTEL_AGENT_FEATURE_GATE_ARG='--feature-gates=clickhouse.json' en el collector. Por ejemplo:
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 abierto
OTEL_AGENT_FEATURE_GATE_ARG='--feature-gates=clickhouse.json' en cualquier implementación que incluya el collector, y BETA_CH_OTEL_JSON_SCHEMA_ENABLED=true en la capa de aplicación de HyperDX para que pueda consultar los esquemas de tipo JSON.
Por ejemplo:
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
Migrar de un esquema basado en Map a JSON
Compatibilidad con versiones anterioresEl tipo JSON no es retrocompatible con los esquemas existentes basados en Map. Al habilitar esta función, se crean tablas nuevas con el tipo JSON y es necesario migrar los datos manualmente. Cambia el nombre de las tablas existentes y actualiza las fuentes de datos
Cambia el nombre de las tablas existentes y actualiza las fuentes de datos en HyperDX.Por ejemplo:RENAME TABLE otel_logs TO otel_logs_map;
RENAME TABLE otel_metrics TO otel_metrics_map;
Despliega el OTel collector
Despliega el OTel collector con OTEL_AGENT_FEATURE_GATE_ARG configurado.Reinicia el contenedor de HyperDX con compatibilidad para esquemas JSON
export BETA_CH_OTEL_JSON_SCHEMA_ENABLED=true
Crea nuevas fuentes de datos
Crea nuevas fuentes de datos en HyperDX que apunten a las tablas JSON.Migrar los datos existentes (opcional)
INSERT INTO otel_logs SELECT * FROM otel_logs_map;
INSERT INTO otel_metrics SELECT * FROM otel_metrics_map;
Recomendado solo para conjuntos de datos de menos de ~10 mil millones de filas. Los datos almacenados anteriormente con el tipo Map no conservaban la precisión de los tipos (todos los valores eran cadenas). Como resultado, estos datos antiguos aparecerán como cadenas en el nuevo esquema hasta que expiren por antigüedad, por lo que habrá que hacer algunas conversiones de tipo en el frontend. El tipo de los datos nuevos sí se conservará con el tipo JSON.
