ClickStack - logs, trazas y métricas de ejemplo

Primeros pasos con ClickStack y un conjunto de datos de ejemplo con logs, sesiones, trazas y métricas

Esta guía presenta tanto ClickStack Open Source como Managed ClickStack con un conjunto de datos de ejemplo.

ClickStack gestionado

La siguiente guía asume que ha completado la Guía de introducción para Managed ClickStack y que tiene las credenciales de conexión anotadas.

1. ​

   Selecciona tu servicio

   Selecciona el servicio con Managed ClickStack en la página principal de ClickHouse Cloud.

2. ​

   Ve a la UI de ClickStack (HyperDX)

   Selecciona ClickStack en el menú de la izquierda para ir a la UI de ClickStack, donde se te autenticará automáticamente.

3. ​

   Descargar datos de ejemplo

   Para cargar la UI con datos de ejemplo, descargue el siguiente archivo:

   Datos de ejemplo

   # curl
   curl -O https://storage.googleapis.com/hyperdx/sample.tar.gz
   # o
   # wget https://storage.googleapis.com/hyperdx/sample.tar.gz
   

   Este archivo contiene logs, métricas y trazas de ejemplo de nuestra demo pública de OpenTelemetry, una sencilla tienda en línea con microservicios. Copia este archivo en el directorio que prefieras.

4. ​

   Cargar datos de ejemplo

   Para cargar estos datos, simplemente los enviamos al endpoint HTTP del OTel collector de OpenTelemetry ya desplegado.

   Ejecute el siguiente comando para enviar los datos al OTel collector:

   for filename in $(tar -tf sample.tar.gz); do
     endpoint="http://localhost:4318/v1/${filename%.json}"
     echo "loading ${filename%.json}"
     tar -xOf sample.tar.gz "$filename" | while read -r line; do
       printf '%s\n' "$line" | curl -s -o /dev/null -X POST "$endpoint" \
       -H "Content-Type: application/json" \
       -H "authorization: ${CLICKSTACK_API_KEY}" \
       --data-binary @-
     done
   done
   

   Esto simula fuentes OTLP de logs, trazas y métricas que envían datos al OTel collector. En producción, estas fuentes pueden ser clientes en distintos lenguajes o incluso otros OTel collectors.

   Al volver a la vista Search, deberías ver que los datos han empezado a cargarse (ajusta el marco temporal a Last 1 hour si los datos no aparecen):

   La carga de datos tardará unos minutos. Espera a que finalice antes de pasar a los siguientes pasos.

5. ​

   Explorar sesiones

   Supongamos que hemos recibido informes de que nuestros usuarios están teniendo problemas para pagar sus compras. Podemos ver su experiencia usando la función de session replay de HyperDX.

   Selecciona Client Sessions en el menú de la izquierda.

   Esta vista nos permite ver las sesiones del front-end de nuestra tienda de comercio electrónico. Las sesiones permanecen como Anonymous hasta que los usuarios pasan por caja e intentan completar una compra.

   Ten en cuenta que algunas sesiones con correos electrónicos tienen un error asociado, lo que podría confirmar los informes de transacciones fallidas.

   Selecciona una traza con un fallo y un correo electrónico asociado. La vista siguiente nos permite reproducir la sesión del usuario y revisar el problema. Pulsa play para ver la sesión.

   La reproducción muestra al usuario navegando por el sitio y añadiendo artículos al carrito. Si quieres, puedes avanzar hasta un punto posterior de la sesión donde intenta completar el pago.

   Los errores aparecen anotados en rojo en la línea de tiempo.

   El usuario no pudo realizar el pedido, sin que hubiera ningún error evidente. Desplázate hasta la parte inferior del panel izquierdo, que contiene los eventos de red y de consola del navegador del usuario. Verás que se produjo un error 500 al hacer una llamada a /api/checkout.

   Selecciona este error 500. Ni Overview ni Column Values indican el origen del problema, más allá de que el error es inesperado, lo que provoca un Internal Error.

6. ​

   Explorar trazas

   Ve a la pestaña Trace para ver la traza distribuida completa.

   Desplázate hacia abajo en la traza para ver el origen del error: el span del servicio checkout. Selecciona el span del servicio Payment.

   Selecciona la pestaña Column Values y desplázate hacia abajo. Podemos ver que el problema está asociado a que la caché está llena.

   Al volver a subir y regresar a la traza, podemos ver que los logs están correlacionados con el span gracias a la configuración anterior. Esto aporta más contexto.

   Hemos determinado que la caché se está llenando en el servicio de pagos, lo que impide que los pagos se completen.

7. ​

   Explorar logs

   Para obtener más detalles, podemos volver a Search:

   Selecciona Logs en las fuentes y aplica un filtro al servicio payment.

   Podemos ver que, aunque el problema es reciente, el número de pagos afectados es elevado. Además, parece que una caché relacionada con los pagos con Visa está causando problemas.

8. ​

   Métricas del gráfico

   Aunque claramente se ha introducido un error en el código, podemos usar métricas para confirmar el tamaño de la caché. Ve a la vista Chart Explorer.

   Selecciona Metrics como fuente de datos. Completa el generador de gráficos para representar el Maximum de visa_validation_cache.size (Gauge) y pulsa el botón play. La caché fue aumentando claramente hasta alcanzar un tamaño máximo, tras lo cual se generaron errores.

ClickStack Open Source

El siguiente ejemplo asume que ha iniciado Open Source ClickStack siguiendo las instrucciones para la imagen todo en uno y se ha conectado a la instancia local de ClickHouse.

1. ​

   Ve a la UI de ClickStack (HyperDX)

   Visita http://localhost:8080 para acceder a la UI de ClickStack.

2. ​

   Copiar la API key de ingesta

   Ve a Team Settings y copia la Ingestion API Key de la sección API Keys. Esta API key garantiza que la ingestión de datos a través del collector de OpenTelemetry sea segura.

3. ​

   Descargar datos de ejemplo

   Para cargar la UI con datos de ejemplo, descargue el siguiente archivo:

   Datos de ejemplo

   # curl
   curl -O https://storage.googleapis.com/hyperdx/sample.tar.gz
   # o
   # wget https://storage.googleapis.com/hyperdx/sample.tar.gz
   

   Este archivo contiene logs, métricas y trazas de ejemplo de nuestra demo pública de OpenTelemetry, una sencilla tienda en línea con microservicios. Copia este archivo en el directorio que prefieras.

4. ​

   Cargar datos de ejemplo

   Para cargar estos datos, basta con enviarlos al endpoint HTTP del collector de OpenTelemetry (OTel) desplegado.

   Primero, exporte la API key que copió anteriormente.

   # exportar API key
   export CLICKSTACK_API_KEY=<YOUR_INGESTION_API_KEY>
   

   Ejecute el siguiente comando para enviar los datos al OTel collector:

   for filename in $(tar -tf sample.tar.gz); do
     endpoint="http://localhost:4318/v1/${filename%.json}"
     echo "loading ${filename%.json}"
     tar -xOf sample.tar.gz "$filename" | while read -r line; do
       printf '%s\n' "$line" | curl -s -o /dev/null -X POST "$endpoint" \
       -H "Content-Type: application/json" \
       -H "authorization: ${CLICKSTACK_API_KEY}" \
       --data-binary @-
     done
   done
   

   Esto simula fuentes OTLP de logs, trazas y métricas que envían datos al OTel collector. En producción, estas fuentes pueden ser clientes en distintos lenguajes o incluso otras instancias de OTel collector.

   Al volver a la vista Search, deberías ver que los datos han empezado a cargarse (ajusta el intervalo de tiempo a Last 1 hour si los datos no se muestran):

   La carga de datos tardará unos minutos. Espera a que termine antes de continuar con los siguientes pasos.

5. ​

   Explorar sesiones

   Supongamos que hemos recibido informes de usuarios que tienen problemas para pagar sus compras. Podemos ver su experiencia usando las capacidades de session replay de HyperDX.

   Selecciona Client Sessions en el menú de la izquierda.

   Esta vista nos permite ver las sesiones del front-end de nuestra tienda de comercio electrónico. Las sesiones permanecen como Anonymous hasta que los usuarios pasan por caja e intentan completar una compra.

   Ten en cuenta que algunas sesiones con direcciones de correo electrónico tienen un error asociado, lo que podría confirmar los informes de transacciones fallidas.

   Selecciona un trace con un fallo y una dirección de correo electrónico asociada. La vista siguiente nos permite reproducir la sesión del usuario y revisar su problema. Pulsa play para ver la sesión.

   La reproducción muestra al usuario navegando por el sitio y añadiendo artículos al carrito. No dudes en avanzar hasta un punto posterior de la sesión, donde intenta completar el pago.

   Los errores se anotan en rojo en la línea de tiempo.

   El usuario no pudo completar el pedido, sin ningún error evidente. Desplázate hasta la parte inferior del panel izquierdo, que contiene los eventos de Network y Console del navegador del usuario. Verás que se produjo un error 500 al hacer una llamada a /api/checkout.

   Selecciona este error 500. Ni Overview ni Column Values indican el origen del problema, más allá de que el error es inesperado y provoca un Internal Error.

6. ​

   Explorar trazas

   Ve a la pestaña Trace para ver la traza distribuida completa.

   Desplázate por la traza hasta ver el origen del error: el span del servicio checkout. Selecciona el span del servicio Payment.

   Selecciona la pestaña Column Values y desplázate hacia abajo. Podemos ver que el problema está relacionado con una caché llena.

   Al volver hacia arriba en la traza, vemos que los logs están correlacionados con el span gracias a la configuración anterior. Esto aporta más contexto.

   Hemos comprobado que se está llenando una caché en el servicio Payment, lo que impide que los pagos se completen.

7. ​

   Explorar logs

   Para obtener más detalles, podemos volver a la vista Search:

   Selecciona Logs entre las fuentes y aplica un filtro al servicio payment.

   Podemos ver que, aunque la incidencia es reciente, el número de pagos afectados es alto. Además, una cache relacionada con los pagos con Visa parece estar causando problemas.

8. ​

   Métricas del gráfico

   Aunque claramente se ha introducido un error en el código, podemos usar métricas para verificar el tamaño de la caché. Vaya a la vista Chart Explorer.

   Seleccione Metrics como fuente de datos. Complete el creador de gráficos para representar el Maximum de visa_validation_cache.size (Gauge) y pulse el botón play. La caché iba aumentando claramente hasta alcanzar un tamaño máximo, a partir del cual se generaron errores.