Opciones de configuración

Las siguientes opciones de configuración están disponibles para cada componente de ClickStack:

Configuración para distribuciones de código abierto

Docker

Si usas Todo en uno, Solo HyperDX o Modo local, solo tienes que pasar la configuración deseada mediante una variable de entorno; por ejemplo:

docker run  -e HYPERDX_LOG_LEVEL='debug' -p 8080:8080 -p 4317:4317 -p 4318:4318 clickhouse/clickstack-all-in-one:latest

Docker Compose

Si utiliza la guía de implementación de Docker Compose, puede usar el archivo .env para modificar la configuración. Como alternativa, sobrescriba explícitamente la configuración en el archivo docker-compose.yaml; por ejemplo: Ejemplo:

services:
  app:
    environment:
      HYPERDX_API_KEY: ${HYPERDX_API_KEY}
      HYPERDX_LOG_LEVEL: ${HYPERDX_LOG_LEVEL}
      # ... otras configuraciones

Helm

Personalización de los valores (opcional)

Puede personalizar la configuración con los indicadores --set, por ejemplo.

helm install my-hyperdx hyperdx/hdx-oss-v2 \
  --set replicaCount=2 \
  --set resources.limits.cpu=500m \
  --set resources.limits.memory=512Mi \
  --set resources.requests.cpu=250m \
  --set resources.requests.memory=256Mi \
  --set ingress.enabled=true \
  --set ingress.annotations."kubernetes\.io/ingress\.class"=nginx \
  --set ingress.hosts[0].host=hyperdx.example.com \
  --set ingress.hosts[0].paths[0].path=/ \
  --set ingress.hosts[0].paths[0].pathType=ImplementationSpecific \
  --set env[0].name=CLICKHOUSE_USER \
  --set env[0].value=abc

Como alternativa, edita el values.yaml. Para obtener los valores predeterminados:

helm show values hyperdx/hdx-oss-v2 > values.yaml

Configuración de ejemplo:

replicaCount: 2
resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 250m
    memory: 256Mi
ingress:
  enabled: true
  annotations:
    kubernetes.io/ingress.class: nginx
  hosts:
    - host: hyperdx.example.com
      paths:
        - path: /
          pathType: ImplementationSpecific
  env:
    - name: CLICKHOUSE_USER
      value: abc

Aplicación ClickStack UI (HyperDX)

Configuración de los orígenes de datos

La UI de ClickStack requiere que el usuario defina un origen para cada uno de los tipos o pilares de datos de observabilidad:

Logs
Traces
Metrics
Sessions

Esta configuración puede realizarse dentro de la aplicación desde Team Settings -> Sources, como se muestra a continuación para los logs: Cada uno de estos orígenes requiere que se especifique al menos una tabla al crearlo, así como un conjunto de columnas que permitan a HyperDX consultar los datos. Si se utiliza el esquema predeterminado de OpenTelemetry (OTel) incluido con ClickStack, estas columnas pueden inferirse automáticamente para cada uno de los orígenes. Si se modifica el esquema o se usa un esquema personalizado, los usuarios deben especificar y actualizar estas asignaciones.

El esquema predeterminado de ClickHouse incluido con ClickStack es el esquema creado por el exporter de ClickHouse para el OTel collector. Estos nombres de columnas se corresponden con la especificación oficial de OTel documentada aquí.

La siguiente configuración está disponible para cada origen:

Logs

Configuración	Descripción	Obligatorio	Inferido en el esquema predeterminado	Valor inferido
`Name`	Nombre de la fuente.	Sí	No	–
`Server Connection`	Nombre de la conexión al servidor.	Sí	No	`Default`
`Database`	Nombre de la base de datos de ClickHouse.	Sí	Sí	`default`
`Table`	Nombre de la tabla de destino. Asígnalo a `otel_logs` si se usa el esquema predeterminado.	Sí	No
`Timestamp Column`	Columna de fecha y hora o expresión que forme parte de tu clave primaria.	Sí	Sí	`TimestampTime`
`Default Select`	Columnas que se muestran en los resultados de búsqueda predeterminados.	Sí	Sí	`Timestamp`, `ServiceName`, `SeverityText`, `Body`
`Service Name Expression`	Expresión o columna para el nombre del servicio.	Sí	Sí	`ServiceName`
`Log Level Expression`	Expresión o columna para el nivel del log.	Sí	Sí	`SeverityText`
`Body Expression`	Expresión o columna para el mensaje del log.	Sí	Sí	`Body`
`Log Attributes Expression`	Expresión o columna para los atributos personalizados del log.	Sí	Sí	`LogAttributes`
`Resource Attributes Expression`	Expresión o columna para atributos a nivel de recurso.	Sí	Sí	`ResourceAttributes`
`Displayed Timestamp Column`	Columna de timestamp usada para la visualización en la UI.	Sí	Sí	`ResourceAttributes`
`Correlated Metric Source`	Fuente de métricas correlacionada (p. ej., métricas de HyperDX).	No	No	–
`Correlated Trace Source`	Fuente de trazas correlacionada (p. ej., trazas de HyperDX).	No	No	–
`Trace Id Expression`	Expresión o columna usada para extraer el ID de traza.	Sí	Sí	`TraceId`
`Span Id Expression`	Expresión o columna usada para extraer el ID de span.	Sí	Sí	`SpanId`
`Implicit Column Expression`	Columna usada para la búsqueda de texto completo si no se especifica ningún campo (estilo Lucene). Normalmente, el cuerpo del log.	Sí	Sí	`Body`
`Highlighted Attributes`	Expresiones o columnas que se muestran al abrir los detalles del log. Las expresiones que devuelvan URL se mostrarán como enlaces.	No	No	–
`Highlighted Trace Attributes`	Expresiones o columnas extraídas de cada log de una traza, que se muestran sobre el waterfall de la traza. Las expresiones que devuelvan URL se mostrarán como enlaces.	No	No	–

Trazas

Configuración	Descripción	Requerido	Inferido en el esquema predeterminado	Valor inferido
`Name`	Nombre de la fuente.	Sí	No	–
`Server Connection`	Nombre de la conexión al servidor.	Sí	No	`Default`
`Database`	Nombre de la base de datos de ClickHouse.	Sí	Sí	`default`
`Table`	Nombre de la tabla de destino. Establécelo en `otel_traces` si usas el esquema predeterminado.	Sí	Sí	-
`Timestamp Column`	Columna de fecha y hora o expresión que forma parte de la clave primaria.	Sí	Sí	`Timestamp`
`Timestamp`	Alias de `Timestamp Column`.	Sí	Sí	`Timestamp`
`Default Select`	Columnas que se muestran en los resultados de búsqueda predeterminados.	Sí	Sí	`Timestamp, ServiceName as service, StatusCode as level, round(Duration / 1e6) as duration, SpanName`
`Duration Expression`	Expresión para calcular la duración del span.	Sí	Sí	`Duration`
`Duration Precision`	Precisión de la expresión de duración (p. ej., nanosegundos, microsegundos).	Sí	Sí	ns
`Trace Id Expression`	Expresión o columna para los ID de traza.	Sí	Sí	`TraceId`
`Span Id Expression`	Expresión o columna para los ID de span.	Sí	Sí	`SpanId`
`Parent Span Id Expression`	Expresión o columna para los ID del span padre.	Sí	Sí	`ParentSpanId`
`Span Name Expression`	Expresión o columna para los nombres de span.	Sí	Sí	`SpanName`
`Span Kind Expression`	Expresión o columna para el tipo de span (p. ej., cliente, servidor).	Sí	Sí	`SpanKind`
`Correlated Log Source`	Opcional. Fuente de logs correlacionada (p. ej., logs de HyperDX).	No	No	–
`Correlated Session Source`	Opcional. Fuente de sesión correlacionada.	No	No	–
`Correlated Metric Source`	Opcional. Fuente de métricas correlacionada (p. ej., métricas de HyperDX).	No	No	–
`Status Code Expression`	Expresión para el código de estado del span.	Sí	Sí	`StatusCode`
`Status Message Expression`	Expresión para el mensaje de estado del span.	Sí	Sí	`StatusMessage`
`Service Name Expression`	Expresión o columna para el nombre del servicio.	Sí	Sí	`ServiceName`
`Resource Attributes Expression`	Expresión o columna para los atributos a nivel de recurso.	Sí	Sí	`ResourceAttributes`
`Event Attributes Expression`	Expresión o columna para los atributos del evento.	Sí	Sí	`SpanAttributes`
`Span Events Expression`	Expresión para extraer eventos del span. Normalmente, es una columna de tipo `Nested`. Esto permite mostrar trazas de pila de excepciones con SDKs de lenguaje compatibles.	Sí	Sí	`Events`
`Implicit Column Expression`	Columna usada para la búsqueda de texto completo si no se especifica ningún campo (estilo Lucene). Normalmente, el cuerpo del log.	Sí	Sí	`SpanName`
`Highlighted Attributes`	Expresiones o columnas que se muestran al abrir los detalles del span. Las expresiones que devuelven URL se mostrarán como enlaces.	No	No	–
`Highlighted Trace Attributes`	Expresiones o columnas extraídas de cada span de una traza, que se muestran encima de la cascada de la traza. Las expresiones que devuelven URL se mostrarán como enlaces.	No	No	–

Métricas

Configuración	Descripción	Obligatorio	Inferido en el esquema predeterminado	Valor inferido
`Name`	Nombre de la fuente.	Sí	No	–
`Server Connection`	Nombre de la conexión al servidor.	Sí	No	`Default`
`Database`	Nombre de la base de datos de ClickHouse.	Sí	Sí	`default`
`Gauge Table`	Tabla que almacena métricas de tipo gauge.	Sí	No	`otel_metrics_gauge`
`Histogram Table`	Tabla que almacena métricas de tipo histograma.	Sí	No	`otel_metrics_histogram`
`Sum Table`	Tabla que almacena métricas de tipo suma (counter).	Sí	No	`otel_metrics_sum`
`Correlated Log Source`	Opcional. Fuente de logs correlacionada (p. ej., logs de HyperDX).	No	No	–

Sesiones

Configuración	Descripción	Obligatorio	Inferido en el esquema predeterminado	Valor inferido
`Name`	Nombre de la fuente.	Sí	No	–
`Server Connection`	Nombre de la conexión al servidor.	Sí	No	`Default`
`Database`	Nombre de la base de datos de ClickHouse.	Sí	Sí	`default`
`Table`	Tabla de destino para los datos de sesión. Nombre de la tabla de destino. Establézcala en `hyperdx_sessions` si usa el esquema predeterminado.	Sí	Sí	-
`Timestamp Column`	Columna de fecha y hora o expresión que forma parte de su clave primaria.	Sí	Sí	`TimestampTime`
`Log Attributes Expression`	Expresión para extraer atributos a nivel de log de los datos de sesión.	Sí	Sí	`LogAttributes`
`LogAttributes`	Alias o referencia de campo utilizada para almacenar atributos de log.	Sí	Sí	`LogAttributes`
`Resource Attributes Expression`	Expresión para extraer metadatos a nivel de recurso.	Sí	Sí	`ResourceAttributes`
`Correlated Trace Source`	Opcional. Fuente de trazas correlacionada para la correlación de sesiones.	No	No	–
`Implicit Column Expression`	Columna utilizada para la búsqueda de texto completo cuando no se especifica ningún campo (p. ej., análisis de consultas al estilo Lucene).	Sí	Sí	`Body`

Atributos destacados

Los Atributos destacados y los Atributos de traza destacados se pueden configurar en los orígenes de datos de Log y Trace.

Los Atributos destacados son columnas o expresiones que se muestran para cada log o span al ver los detalles del log o del span.
Los Atributos de traza destacados son columnas o expresiones que se consultan de cada log o span de una traza y se muestran sobre el waterfall de la traza.

Estos atributos se definen en la configuración de la fuente y pueden ser expresiones SQL arbitrarias. Si la expresión SQL devuelve un valor con formato de URL, el atributo se mostrará como un enlace. Los valores vacíos no se muestran. Por ejemplo, esta fuente de trazas se ha configurado con un Atributo destacado y un Atributo de traza destacado: Estos atributos se muestran en el panel lateral después de hacer clic en un log o span: Al hacer clic en un atributo, se ofrecen opciones para usarlo como valor de búsqueda. Si se proporciona la expresión Lucene opcional en la configuración del atributo, se utilizará la expresión Lucene para la búsqueda en lugar de la expresión SQL.

Fuentes correlacionadas

Para habilitar la correlación completa entre fuentes en ClickStack, debe configurar fuentes correlacionadas para logs, trazas, métricas y sesiones. Esto permite que HyperDX asocie datos relacionados y proporcione un contexto enriquecido al mostrar eventos.

Logs: Se pueden correlacionar con trazas y métricas.
Traces: Se pueden correlacionar con logs, sesiones y métricas.
Metrics: Se pueden correlacionar con logs.
Sessions: Se pueden correlacionar con trazas.

Configurar estas correlaciones habilita varias funcionalidades. Por ejemplo, HyperDX puede mostrar logs relevantes junto a una traza o resaltar anomalías de métricas vinculadas a una sesión. Por ejemplo, a continuación se muestra la fuente de logs configurada con fuentes correlacionadas:

Opciones de configuración de la aplicación

HyperDX en ClickHouse CloudEstas opciones no se pueden modificar cuando HyperDX se gestiona en ClickHouse Cloud.

HYPERDX_API_KEY
- Predeterminado: Ninguno (obligatorio)
- Descripción: Clave de autenticación para la API de HyperDX.
- Orientación:
- Obligatoria para telemetría y logging
- En el desarrollo local, puede ser cualquier valor no vacío
- Para producción, use una clave segura y única
- Puede obtenerse en la página de configuración del equipo después de crear la cuenta
HYPERDX_LOG_LEVEL
- Predeterminado: info
- Descripción: Establece el nivel de detalle del registro.
- Opciones: debug, info, warn, error
- Guía:
- Use debug para la solución detallada de problemas
- Use info para el funcionamiento normal
- Use warn o error en producción para reducir el volumen de logs
HYPERDX_API_PORT
- Predeterminado: 8000
- Descripción: Puerto del servidor de la API de HyperDX.
- Guía:
- Asegúrese de que este puerto esté disponible en el host
- Cámbielo si hay conflictos de puertos
- Debe coincidir con el puerto de las configuraciones del cliente de la API
HYPERDX_APP_PORT
- Valor predeterminado: 8000
- Descripción: Puerto de la aplicación frontend de HyperDX.
- Recomendaciones:
- Asegúrate de que este puerto esté disponible en el host
- Cámbialo si hay conflictos de puertos
- Debe ser accesible desde el navegador
HYPERDX_APP_URL
- Predeterminado: http://localhost
- Descripción: URL base de la aplicación frontend.
- Guía:
- En producción, configúralo con tu dominio
- Incluye el protocolo (http/https)
- No incluyas la barra final
MONGO_URI
- Predeterminado: mongodb://db:27017/hyperdx
- Descripción: cadena de conexión de MongoDB.
- Guía:
- Use el valor predeterminado para el desarrollo local con Docker
- Para producción, use una cadena de conexión segura
- Incluya autenticación si es necesario
- Ejemplo: mongodb://user:pass@host:port/db
MINER_API_URL
- Predeterminado: http://miner:5123
- Descripción: URL del servicio de minería de patrones de logs.
- Guía:
- Usa el valor predeterminado para el desarrollo local con Docker
- Configúralo con la URL de tu servicio de miner en producción
- Debe ser accesible desde el servicio de la API
FRONTEND_URL
- Predeterminado: http://localhost:3000
- Descripción: URL de la aplicación frontend.
- Orientación:
- Use el valor predeterminado para el desarrollo local
- Establézcalo con su dominio en producción
- Debe ser accesible desde el servicio API
OTEL_SERVICE_NAME
- Predeterminado: hdx-oss-api
- Descripción: Nombre del servicio para la instrumentación de OpenTelemetry.
- Indicaciones:
- Use un nombre descriptivo para su servicio de HyperDX. Se aplica si HyperDX se instrumenta automáticamente.
- Ayuda a identificar el servicio de HyperDX en los datos de telemetría
NEXT_PUBLIC_OTEL_EXPORTER_OTLP_ENDPOINT
- Predeterminado: http://localhost:4318
- Descripción: endpoint del collector de OpenTelemetry.
- Indicaciones:
- Relevante para la autoinstrumentación de HyperDX.
- Use el valor predeterminado para el desarrollo local
- Configúrelo con la URL de su collector en producción
- Debe ser accesible desde su servicio de HyperDX
USAGE_STATS_ENABLED
- Predeterminado: true
- Descripción: Activa o desactiva la recopilación de estadísticas de uso.
- Orientación:
- Establézcalo en false para desactivar el seguimiento de uso
- Útil para implementaciones con requisitos estrictos de privacidad
- El valor predeterminado es true para facilitar la mejora del producto
IS_OSS
- Predeterminado: true
- Descripción: Indica si se ejecuta en modo OSS.
- Recomendaciones:
- Manténgalo como true para implementaciones de código abierto
- Establézcalo en false para implementaciones empresariales
- Afecta a la disponibilidad de funciones
IS_LOCAL_MODE
- Valor predeterminado: false
- Descripción: Indica si se ejecuta en modo local.
- Recomendaciones:
- Establézcalo en true para el desarrollo local
- Desactiva determinadas funciones de producción
- Útil para pruebas y desarrollo
EXPRESS_SESSION_SECRET
- Predeterminado: hyperdx is cool 👋
- Descripción: Secreto para la gestión de sesiones de Express.
- Recomendaciones:
- Cámbielo en producción
- Use una cadena segura y aleatoria
- Manténgalo en secreto y protegido
ENABLE_SWAGGER
- Valor predeterminado: false
- Descripción: Activa o desactiva la documentación de la API de Swagger.
- Recomendaciones:
- Establézcalo en true para habilitar la documentación de la API
- Útil para desarrollo y pruebas
- Desactívelo en producción
BETA_CH_OTEL_JSON_SCHEMA_ENABLED
- Predeterminado: false
- Descripción: Habilita la compatibilidad beta con el tipo JSON en HyperDX. Consulta también OTEL_AGENT_FEATURE_GATE_ARG para habilitar la compatibilidad con JSON en el OTel collector.
- Guía:
  - Habilita una funcionalidad beta. Los esquemas con tipo JSON no se recomiendan para las cargas de trabajo de observabilidad habituales. Consulta Map vs JSON type para ver la comparación y cuándo conviene usar cada uno.
  - Establécelo en true para habilitar la compatibilidad con JSON en la UI de ClickStack.

OpenTelemetry collector

Consulta “ClickStack OpenTelemetry Collector” para obtener más información.

CLICKHOUSE_ENDPOINT
- Predeterminado: Ninguno (obligatorio) si se usa una imagen independiente. Si se usa una distribución All-in-one o Docker Compose, se establece en la instancia integrada de ClickHouse.
- Descripción: La URL HTTPS de la instancia de ClickHouse a la que se exportarán los datos de telemetría.
- Guía:
  - Debe ser un endpoint HTTPS completo, incluido el puerto (p. ej., https://clickhouse.example.com:8443)
  - Es obligatorio para que el collector envíe datos a ClickHouse
CLICKHOUSE_USER
- Predeterminado: default
- Descripción: Nombre de usuario utilizado para autenticarse con la instancia de ClickHouse.
- Guía:
  - Asegúrate de que el usuario tenga permisos de INSERT y CREATE TABLE
  - Se recomienda crear un usuario dedicado para la ingestión
CLICKHOUSE_PASSWORD
- Predeterminado: Ninguno (obligatorio si la autenticación está habilitada)
- Descripción: Contraseña del usuario de ClickHouse especificado.
- Guía:
  - Es obligatorio si la cuenta de usuario tiene una contraseña configurada
  - Almacénala de forma segura mediante secretos en implementaciones de producción
HYPERDX_LOG_LEVEL
- Predeterminado: info
- Descripción: Nivel de verbosidad de los logs del collector.
- Guía:
  - Acepta valores como debug, info, warn, error
  - Usa debug durante la resolución de problemas
OPAMP_SERVER_URL
- Predeterminado: Ninguno (obligatorio) si se usa una imagen independiente. Si se usa una distribución All-in-one o Docker Compose, apunta a la instancia de HyperDX desplegada.
- Descripción: URL del servidor OpAMP utilizado para gestionar el collector (p. ej., una instancia de HyperDX). De forma predeterminada, usa el puerto 4320.
- Guía:
  - Debe apuntar a tu instancia de HyperDX
  - Habilita la configuración dinámica y la ingestión segura
  - Si se omite, la ingestión segura se desactiva a menos que se especifique un valor para OTLP_AUTH_TOKEN.
OTLP_AUTH_TOKEN
- Predeterminado: Ninguno. Solo se usa para la imagen independiente.
- Descripción: Permite especificar un token de autenticación OTLP. Si se configura, toda la comunicación requiere este token Bearer.
- Guía:
  - Se recomienda si usas la imagen independiente del collector en producción.
HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE
- Predeterminado: default
- Descripción: Base de datos de ClickHouse en la que el collector escribe los datos de telemetría.
- Guía:
  - Establécelo si usas un nombre de base de datos personalizado
  - Asegúrate de que el usuario especificado tenga acceso a esta base de datos
OTEL_AGENT_FEATURE_GATE_ARG
- Predeterminado: <cadena vacía>
- Descripción: Habilita feature flags en el collector. Si se establece en --feature-gates=clickhouse.json, habilita la compatibilidad Beta con el tipo JSON en el collector, lo que garantiza que los esquemas se creen con ese tipo. Consulta también BETA_CH_OTEL_JSON_SCHEMA_ENABLED para habilitar la compatibilidad con JSON en HyperDX.
- Guía:
  - Habilita una función beta. Los esquemas con tipo JSON no se recomiendan para cargas de trabajo de observabilidad típicas. Consulta Map vs JSON type para ver la comparación y cuándo es apropiado cada uno.
  - Establécelo en --feature-gates=clickhouse.json para crear tablas nuevas con el tipo JSON.

ClickHouse

ClickStack Open Source incluye una configuración predeterminada de ClickHouse diseñada para escalar a varios terabytes, pero los usuarios pueden modificarla y optimizarla según su carga de trabajo. Para optimizar ClickHouse de forma eficaz, debe comprender conceptos clave de almacenamiento como las partes, las particiones, los segmentos y réplicas y cómo se producen las fusiones durante la inserción. Recomendamos revisar los fundamentos de los índices primarios, los índices secundarios dispersos y los índices de omisión de datos, junto con técnicas para gestionar el ciclo de vida de los datos, por ejemplo, mediante TTL. ClickStack admite la personalización del esquema: puede modificar los tipos de las columnas, extraer nuevos campos (p. ej., de logs), aplicar codecs y diccionarios, y acelerar las consultas mediante proyecciones. Además, las vistas materializadas pueden utilizarse para transformar o filtrar datos durante la ingestión, siempre que los datos se escriban en la tabla origen de la vista y la aplicación lea de la tabla de destino. Las vistas materializadas también pueden utilizarse para acelerar consultas de forma nativa en ClickStack. Para obtener más información, consulte la documentación de ClickHouse sobre diseño de esquemas, estrategias de indexación y buenas prácticas para la gestión de datos; la mayoría se aplican directamente a las implementaciones de ClickStack.

Features

Guides

Configuración para distribuciones de código abierto

Docker

Docker Compose

Helm

Personalización de los valores (opcional)

Aplicación ClickStack UI (HyperDX)

Configuración de los orígenes de datos

Logs

Trazas

Métricas

Sesiones

Atributos destacados

Fuentes correlacionadas

Opciones de configuración de la aplicación

OpenTelemetry collector

ClickHouse

​Configuración para distribuciones de código abierto

​Docker

​Docker Compose

​Helm

​Personalización de los valores (opcional)

​Aplicación ClickStack UI (HyperDX)

​Configuración de los orígenes de datos

​Logs

​Trazas

​Métricas

​Sesiones

​Atributos destacados

​Fuentes correlacionadas

​Opciones de configuración de la aplicación

​OpenTelemetry collector

​ClickHouse

Configuración para distribuciones de código abierto

Docker

Docker Compose

Helm

Personalización de los valores (opcional)

Aplicación ClickStack UI (HyperDX)

Configuración de los orígenes de datos

Logs

Trazas

Métricas

Sesiones

Atributos destacados

Fuentes correlacionadas

Opciones de configuración de la aplicación

OpenTelemetry collector

ClickHouse