Uso de Grafana y ClickHouse para la observabilidad

Grafana es la herramienta de visualización preferida para los datos de observabilidad en ClickHouse. Esto se consigue mediante el plugin oficial de ClickHouse para Grafana. Puede seguir las instrucciones de instalación aquí. La V4 del plugin convierte los logs y las trazas en funcionalidades de primer nivel dentro de una nueva experiencia de constructor de consultas. Esto reduce la necesidad de que los SRE escriban consultas SQL y simplifica la observabilidad basada en SQL, haciendo avanzar este paradigma emergente. Parte de este esfuerzo ha consistido en situar OpenTelemetry (OTel) en el núcleo del plugin, ya que creemos que será la base de la observabilidad basada en SQL en los próximos años y de cómo se recopilarán los datos.

Integración de OpenTelemetry

Al configurar un origen de datos de ClickHouse en Grafana, el plugin permite especificar una base de datos y una tabla predeterminadas para logs y trazas, así como si esas tablas se ajustan al esquema de OTel. Esto permite que el plugin devuelva las columnas necesarias para que los logs y las trazas se muestren correctamente en Grafana. Si has modificado el esquema predeterminado de OTel y prefieres usar tus propios nombres de columna, puedes especificarlos. Si usas los nombres de columna predeterminados de OTel para columnas como el tiempo (Timestamp), el nivel de log (SeverityText) o el cuerpo del mensaje (Body), no hace falta realizar ningún cambio.

HTTP o NativePuedes conectar Grafana a ClickHouse mediante el protocolo HTTP o el protocolo Native. Este último ofrece ventajas de rendimiento marginales que difícilmente se apreciarán en las consultas de agregación ejecutadas por los usuarios de Grafana. En cambio, el protocolo HTTP suele ser más fácil de usar con un proxy y de inspeccionar.

La configuración de Logs requiere una columna de tiempo, una de nivel de log y una de mensaje para que los logs se muestren correctamente. La configuración de Traces es algo más compleja (la lista completa está aquí). Estas columnas obligatorias son necesarias para abstraer las consultas posteriores que construyen un perfil completo de la traza. Estas consultas asumen que los datos tienen una estructura similar a OTel, por lo que los usuarios que se desvíen significativamente del esquema estándar tendrán que usar vistas para aprovechar esta funcionalidad. Una vez configurado, puedes ir a Grafana Explore y empezar a buscar logs y trazas.

Logs

Si cumples con los requisitos de Grafana para logs, puedes seleccionar Query Type: Log en el constructor de consultas y hacer clic en Run Query. El constructor de consultas formulará una consulta para listar los logs y garantizar que se muestren correctamente, p. ej.

SELECT Timestamp as timestamp, Body as body, SeverityText as level, TraceId as traceID FROM "default"."otel_logs" WHERE ( timestamp >= $__fromTime AND timestamp <= $__toTime ) ORDER BY timestamp DESC LIMIT 1000

El constructor de consultas ofrece una forma sencilla de modificar la consulta sin necesidad de escribir SQL. El filtrado, incluida la búsqueda de logs que contengan palabras clave, puede realizarse desde el constructor de consultas. Los usuarios que necesiten escribir consultas más complejas pueden cambiar al editor SQL. Siempre que la consulta devuelva las columnas adecuadas y se seleccione logs como tipo de consulta, los resultados se mostrarán como logs. Las columnas necesarias para la visualización de logs se enumeran aquí.

De logs a trazas

Si los logs contienen IDs de traza, puedes navegar desde una línea de log concreta hasta su traza correspondiente.

Trazas

De forma similar a lo anterior con los logs, si se cumplen las columnas que Grafana necesita para representar las trazas (por ejemplo, al usar el esquema OTel), el constructor de consultas puede formular automáticamente las consultas necesarias. Al seleccionar Query Type: Traces y hacer clic en Run Query, se generará y ejecutará una consulta similar a la siguiente (en función de las columnas configuradas; el siguiente ejemplo asume el uso de OTel):

SELECT "TraceId" as traceID,
  "ServiceName" as serviceName,
  "SpanName" as operationName,
  "Timestamp" as startTime,
  multiply("Duration", 0.000001) as duration
FROM "default"."otel_traces"
WHERE ( Timestamp >= $__fromTime AND Timestamp <= $__toTime )
  AND ( ParentSpanId = '' )
  AND ( Duration > 0 )
  ORDER BY Timestamp DESC, Duration DESC LIMIT 1000

Esta consulta devuelve los nombres de columna que espera Grafana y muestra una tabla de trazas, como se ve a continuación. Se puede filtrar por la duración u otras columnas sin necesidad de escribir SQL. Los usuarios que deseen escribir consultas más complejas pueden cambiar al SQL Editor.

Ver detalles de la traza

Como se muestra arriba, los ID de traza aparecen como enlaces en los que se puede hacer clic. Al hacer clic en un ID de traza, el usuario puede ver los spans asociados mediante el enlace View Trace. Esto ejecuta la siguiente consulta (suponiendo columnas de OTel) para recuperar los spans con la estructura requerida y mostrar los resultados en forma de cascada.

WITH '<trace_id>' AS trace_id,
  (SELECT min(Start) FROM "default"."otel_traces_trace_id_ts"
    WHERE TraceId = trace_id) AS trace_start,
  (SELECT max(End) + 1 FROM "default"."otel_traces_trace_id_ts"
    WHERE TraceId = trace_id) AS trace_end
SELECT "TraceId" AS traceID,
  "SpanId" AS spanID,
  "ParentSpanId" AS parentSpanID,
  "ServiceName" AS serviceName,
  "SpanName" AS operationName,
  "Timestamp" AS startTime,
  multiply("Duration", 0.000001) AS duration,
  arrayMap(key -> map('key', key, 'value',"SpanAttributes"[key]),
  mapKeys("SpanAttributes")) AS tags,
  arrayMap(key -> map('key', key, 'value',"ResourceAttributes"[key]),
  mapKeys("ResourceAttributes")) AS serviceTags
FROM "default"."otel_traces"
WHERE traceID = trace_id
  AND startTime >= trace_start
  AND startTime <= trace_end
LIMIT 1000

Fíjese en cómo la consulta anterior usa la vista materializada otel_traces_trace_id_ts para realizar la búsqueda por ID de traza. Consulte Aceleración de consultas: uso de vistas materializadas para búsquedas para obtener más información.

De trazas a logs

Si los logs contienen ID de traza, puede navegar desde una traza hasta los logs asociados. Para ver los logs, haga clic en un ID de traza y seleccione View Logs. Esto ejecuta la siguiente consulta, asumiendo las columnas predeterminadas de OTel.

SELECT Timestamp AS "timestamp",
  Body AS "body", SeverityText AS "level",
  TraceId AS "traceID" FROM "default"."otel_logs"
WHERE ( traceID = '<trace_id>' )
ORDER BY timestamp ASC LIMIT 1000

Paneles

Puede crear paneles en Grafana con el origen de datos de ClickHouse. Para obtener más información, recomendamos la documentación del origen de datos de Grafana y ClickHouse, especialmente la del concepto de macros y las variables. El complemento incluye varios paneles listos para usar, entre ellos un panel de ejemplo, “Simple ClickHouse OTel dashboarding”, para datos de logging y tracing conformes con la especificación OTel. Para ello, los usuarios deben ceñirse a los nombres de columna predeterminados de OTel, y puede instalarse desde la configuración del origen de datos. A continuación, ofrecemos algunos consejos sencillos para crear visualizaciones.

Series temporales

Junto con las estadísticas, los gráficos de líneas son una de las formas de visualización más comunes en casos de uso de observabilidad. El plugin de ClickHouse mostrará automáticamente un gráfico de líneas si una consulta devuelve un datetime llamado time y una columna numérica. Por ejemplo:

SELECT
 $__timeInterval(Timestamp) as time,
 quantile(0.99)(Duration)/1000000 AS p99
FROM otel_traces
WHERE
 $__timeFilter(Timestamp)
 AND ( Timestamp  >= $__fromTime AND Timestamp <= $__toTime )
GROUP BY time
ORDER BY time ASC
LIMIT 100000

Gráficos multilínea

Los gráficos multilínea se renderizarán automáticamente para una consulta siempre que se cumplan las siguientes condiciones:

campo 1: campo de fecha y hora con el alias time
campo 2: valor por el que se agrupa. Debe ser un String.
campo 3+: los valores de las métricas

Por ejemplo:

SELECT
  $__timeInterval(Timestamp) as time,
  ServiceName,
  quantile(0.99)(Duration)/1000000 AS p99
FROM otel_traces
WHERE $__timeFilter(Timestamp)
AND ( Timestamp  >= $__fromTime AND Timestamp <= $__toTime )
GROUP BY ServiceName, time
ORDER BY time ASC
LIMIT 100000

Visualización de datos geográficos

En secciones anteriores, vimos cómo enriquecer los datos de observabilidad con coordenadas geográficas mediante diccionarios IP. Suponiendo que tenga las columnas latitude y longitude, la observabilidad puede visualizarse con la función geohashEncode. Esto genera geohashes compatibles con el gráfico Geo Map de Grafana. A continuación, se muestran una consulta de ejemplo y su visualización:

WITH coords AS
        (
        SELECT
                Latitude,
                Longitude,
                geohashEncode(Longitude, Latitude, 4) AS hash
        FROM otel_logs_v2
        WHERE (Longitude != 0) AND (Latitude != 0)
        )
SELECT
        hash,
        count() AS heat,
        round(log10(heat), 2) AS adj_heat
FROM coords
GROUP BY hash

Guías de ClickHouse

Guías de casos de uso

Uso de Grafana y ClickHouse para la observabilidad

Integración de OpenTelemetry

Logs

De logs a trazas

Trazas

Ver detalles de la traza

De trazas a logs

Paneles

Series temporales

Gráficos multilínea

Visualización de datos geográficos

​Integración de OpenTelemetry

​Logs

​De logs a trazas

​Trazas

​Ver detalles de la traza

​De trazas a logs

​Paneles

​Series temporales

​Gráficos multilínea

​Visualización de datos geográficos

Integración de OpenTelemetry

Logs

De logs a trazas

Trazas

Ver detalles de la traza

De trazas a logs

Paneles

Series temporales

Gráficos multilínea

Visualización de datos geográficos