05 ClickStack

Reenvía la telemetría mediante un recolector local sin estado, activa Managed ClickStack e inspecciónala en HyperDX alojado en la nube.

Punto de partida

Estás en build-workshop-v1; no hace falta hacer checkout. Reserva unos 15 minutos. La aplicación ya está instrumentada para OpenTelemetry; en este módulo la activas con la superposición del recolector.

Requisito previo: tu servicio en la nube en ejecución (módulo 01).

Por qué

Para diagnosticar la aplicación más tarde, primero tienes que verla. ClickStack (la pila de observabilidad de ClickHouse, con HyperDX como interfaz) almacena traces y registros de OpenTelemetry en ClickHouse. En este módulo activas el recolector para que cada solicitud que atraviesa la aplicación genere telemetría consultable.

Objetivo

Traces de la aplicación y registros de consultas del back-end fluyendo a ClickStack, con al menos un trace de solicitud de extremo a extremo y un flujo visible de registros de consultas correctas.

Paso 1: ejecuta la superposición del recolector OpenTelemetry

HyperDX, el almacenamiento y el procesamiento de consultas siguen administrados en ClickHouse Cloud. El único componente local es un recolector OpenTelemetry sin estado junto a la aplicación local; reenvía la telemetría y no constituye una implementación local de ClickStack ni HyperDX.

Comprueba primero los puertos del recolector

El recolector publica OTLP en los puertos 4317 y 4318 del host, que suelen estar ocupados. Si ./preflight.sh en ClickHouse_Demos/workshops/build_workshop/app mostró una ADVERTENCIA sobre ellos en el módulo 00, define OTEL_GRPC_HOST_PORT y OTEL_HTTP_HOST_PORT en .env.workshop con los valores sugeridos por la comprobación previa (por ejemplo, 24317 / 24318) antes de iniciar la superposición. El back-end accede al recolector por la red interna, de modo que es seguro reasignar los puertos del host. Desde cualquier punto del repositorio clonado, vuelve a ejecutar cd "$(git rev-parse --show-toplevel)/workshops/build_workshop/app" && ./preflight.sh para confirmar que los puertos están libres.

`.env.workshop` y `docker-compose.otel.yml`

Estos valores se encuentran en la sección de observabilidad de ClickStack de .env.workshop.example; rellénalos en tu .env.workshop:

OTLP_AUTH_TOKEN=change-me-workshop-token   # shared secret securing OTLP ingest
CLICKSTACK_DATABASE=otel                   # ClickStack's own otel_* tables
OTEL_SERVICE_NAME=nyc-taxi-backend         # the service name shown in HyperDX
LOG_LEVEL=DEBUG                            # show successful queries in Log source

No importes este archivo al entorno del shell. El comando de Compose siguiente lo lee directamente, lo que mantiene sus contraseñas y claves de API fuera de las variables exportadas del shell y garantiza que los cambios posteriores del archivo surtan efecto.

Ahora inicia la pila con la superposición. La superposición define OTEL_ENABLED=true en el back-end, añade el servicio otel-collector (clickhouse/clickstack-otel-collector) y recompila el front-end con la configuración de telemetría del navegador:

docker compose --env-file .env.workshop \
  -f docker-compose.workshop.yml -f docker-compose.otel.yml up -d --build

El recolector reutiliza CLICKHOUSE_HOST / CLICKHOUSE_PORT / CLICKHOUSE_USER / CLICKHOUSE_PASSWORD de .env.workshop; el back-end exporta OTLP a http://otel-collector:4318 (HTTP/protobuf). Para recopilar también la salida estándar sin procesar de los contenedores en un host Linux, añade --profile container-logs.

Paso 2: activa Managed ClickStack en tu servicio

El taller utiliza Managed ClickStack (HyperDX) dentro de tu propio servicio ClickHouse Cloud: el recolector escribe tablas otel_* en tu servicio y la interfaz de HyperDX las muestra allí. Actívalo en la consola:

Consola - tu servicio -> ClickStack -> Start Ingestion -> omite el paso del recolector (el recolector de la aplicación ya se ejecuta desde el paso 1) -> Launch ClickStack

Esto inicia tu sesión en HyperDX mediante SSO. La telemetría ya ha empezado a fluir, por lo que la interfaz alojada puede mostrar datos en cuanto se abra.

Managed ClickStack: diferencias con la configuración clásica

El back-end utiliza OpenTelemetry estándar, no el paquete de conveniencia hyperdx-opentelemetry que recomienda la documentación de ClickStack. Ese paquete fija opentelemetry-api==1.30.0, que entra en conflicto con el SDK v4 de Langfuse usado por la función de chat (necesita opentelemetry-api>=1.33.1); ambos no pueden compartir un mismo entorno. El recolector de ClickStack recibe OTLP estándar, por lo que la distribución convencional se comporta igual; el taller simplemente define las variables de entorno del exportador.
La telemetría de ClickStack reside en una base de datos independiente de tu servicio (CLICKSTACK_DATABASE=otel), distinta de la base de datos de la aplicación (CLICKHOUSE_DATABASE=nyc_tlc_data).
Los traces y los registros Python del back-end fluyen por OTLP desde el back-end instrumentado automáticamente. El recolector opcional --profile container-logs sirve solo para servicios sin instrumentación, como el escritor de viajes; la ruta de registros de Docker para Linux puede no estar disponible en Docker Desktop.

Paso 3: genera y encuentra tráfico en ClickStack

Abre el panel Ops y deja su intervalo predeterminado 1m y la actualización automática 5s en ejecución durante unos 30 segundos. Después, abre ClickStack:

En Traces, sigue una solicitud de extremo a extremo (front-end -> back-end -> ClickHouse).
En Logs, selecciona nyc-taxi-backend y busca registros repetidos de ClickHouse query ok. Sus marcas de tiempo deben avanzar con cada actualización.
Mantén una gravedad significativa: las consultas correctas son DEBUG; los reintentos reales al reactivarse tras inactividad y los fallos aparecen como WARNING o ERROR.

Deberías ver un servicio llamado nyc-taxi-backend en HyperDX, con las solicitudes a /api/... mostradas como traces, cada una con un span secundario clickhouse.query.

Vista Search de HyperDX que muestra traces de nyc-taxi-backend: una lista en directo de spans GET /api/health y POST con columnas de fecha y hora, servicio y duración

HyperDX muestra los traces de la aplicación: el servicio nyc-taxi-backend con sus spans de solicitud /api/....

Cómo comprobar que has terminado

Aparece en HyperDX un servicio llamado nyc-taxi-backend.
Las solicitudes a /api/... aparecen como traces, cada una con un span secundario clickhouse.query que contiene db.statement, db.elapsed_ms y db.rows_returned.
El origen Log muestra registros recientes DEBUG ... ClickHouse query ok mientras el panel Ops permanece abierto.
Aún no verás errores de consulta: una aplicación en buen estado y con datos no activa los límites de seguridad, y las solicitudes 4xx nunca llegan a ClickHouse. En el módulo 07, el fallo inyectado hace visible un span clickhouse.query con error (y error.category).

Resumen

La aplicación ya es observable: los traces y los registros de consultas del back-end se guardan en ClickHouse y pueden explorarse en ClickStack. El perfil opcional container-logs añade la salida estándar del escritor de viajes en hosts Linux compatibles. Esa telemetría es la base del trabajo de SRE con IA que viene a continuación.

Estado final

La telemetría fluye a ClickStack. Continúa en 06 SRE con IA para que tu agente la utilice.