05 ClickStack

Material del facilitador correspondiente a la lección 05 ClickStack del participante.

Tiempos

Unos 15 minutos. La telemetría debe acumularse antes del laboratorio de incidentes del módulo 07, así que inicia el recolector en cuanto este módulo lo permita y mantenlo en ejecución.

Guion de presentación

• Managed ClickStack almacena la telemetría en ClickHouse Cloud; HyperDX es la interfaz alojada. El recolector local solo reenvía los datos. Muestra tanto un trace de solicitud de extremo a extremo como un registro reciente DEBUG ... ClickHouse query ok en el origen Log.
• Pide a los participantes que inicien el recolector en el paso 1 antes de abrir Managed ClickStack en el paso 2. Así, la telemetría tiene tiempo para llegar y la primera vista de la interfaz alojada ya resulta útil.
• Muestra en el proyector un trace de solicitud de extremo a extremo.

Fallos habituales

• Los puertos OTLP 4317/4318 del host ya están en uso: pide que definan OTEL_GRPC_HOST_PORT / OTEL_HTTP_HOST_PORT en .env.workshop (la comprobación previa sugiere valores, por ejemplo, 24317/24318) y, desde cualquier punto del repositorio clonado, ejecuten cd "$(git rev-parse --show-toplevel)/workshops/build_workshop/app" && ./preflight.sh; el back-end accede al recolector por la red interna, de modo que es seguro reasignar los puertos.
• No se inició la superposición del recolector (se olvidó el segundo -f docker-compose.otel.yml), por lo que no llega nada a HyperDX.
• OTLP_AUTH_TOKEN no coincide o faltan valores CLICKHOUSE_* en .env.workshop (el recolector reutiliza CLICKHOUSE_HOST/PORT/USER/PASSWORD para acceder al servicio en la nube).
• Aún no se ha generado tráfico; pide que recorran los dos paneles.
• En Docker Desktop, el recolector opcional --profile container-logs no puede montar la ruta de registros del host (el daemon se ejecuta en una VM); es lo esperado. Los registros del back-end siguen viajando por OTLP. Usa docker compose ... logs solo para diagnosticar el reenviador si HyperDX está vacío.
• Antes, cuando la superposición volvía a crear el back-end, la aplicación devolvía 502 (el nginx del front-end conservaba en caché la IP antigua del back-end). Ahora el front-end vuelve a resolverla en cada solicitud, por lo que se recupera solo en unos 10 s y no requiere un reinicio manual. Corrección confirmada en el ensayo.
• Referencia del ensayo: canalización de telemetría verificada de extremo a extremo: traces de nyc-taxi-backend con spans secundarios clickhouse.query que contienen db.statement / db.elapsed_ms / db.rows_returned. Confirmado en el ensayo en entorno limpio de julio de 2026.

Pasos de restablecimiento

• Reinicia con los dos archivos de Compose: docker compose --env-file .env.workshop -f docker-compose.workshop.yml -f docker-compose.otel.yml up -d --build.
• En la consola de Cloud, abre el servicio, elige ClickStack y vuelve a abrir la interfaz alojada si la sesión de SSO ha caducado.