Constructor de consultas

Uso del Constructor de consultas en el plugin de ClickHouse para Grafana

Cualquier consulta puede ejecutarse con el plugin de ClickHouse. El constructor de consultas es una opción práctica para las consultas más simples, pero para las más complejas tendrás que usar el SQL Editor.

Todas las consultas del constructor de consultas tienen un tipo de consulta y requieren seleccionar al menos una columna.

Los tipos de consulta disponibles son:

• Tabla: el tipo de consulta más sencillo para mostrar datos en formato de tabla. Funciona bien como opción general tanto para consultas simples como para consultas complejas que incluyen funciones de agregación.
• Logs: optimizado para crear consultas de logs. Funciona mejor en la vista Explore con los valores predeterminados configurados.
• Series temporales: ideal para crear consultas de series temporales. Permite seleccionar una columna de tiempo específica y añadir funciones de agregación.
• Trazas: optimizado para buscar y visualizar trazas. Funciona mejor en la vista Explore con los valores predeterminados configurados.
• SQL Editor: el SQL Editor puede usarse cuando necesitas un control total sobre la consulta. En este modo, se puede ejecutar cualquier consulta SQL.

​

Tipos de consulta

La configuración Tipo de consulta cambiará el diseño del constructor de consultas para ajustarlo al tipo de consulta que se esté creando. El tipo de consulta también determina qué panel se utiliza al visualizar los datos.

​

Tabla

El tipo de consulta más flexible es la consulta de tabla. Sirve como opción general para los demás constructores de consultas, diseñados para manejar consultas simples y de agregación.

Field	Description
Builder Mode	Las consultas simples excluyen Aggregates y Group By, mientras que las consultas de agregación incluyen estas opciones.
Columna	Las columnas seleccionadas. En este campo se puede escribir Raw SQL para permitir funciones y alias de columnas.
Aggregates	Una lista de funciones de agregación. Permite definir valores personalizados para la función y la columna. Solo es visible en el modo Aggregate.
Group By	Una lista de expresiones GROUP BY. Solo es visible en el modo Aggregate.
ORDER BY	Una lista de expresiones ORDER BY.
Límite	Añade una sentencia LIMIT al final de la consulta. Si se establece en 0, se omitirá. Algunas visualizaciones pueden requerir que se establezca en 0 para mostrar todos los datos.
Filters	Una lista de filtros que se aplicarán en la cláusula WHERE.

Este tipo de consulta mostrará los datos en forma de tabla.

​

Logs

El tipo de consulta de logs ofrece un constructor de consultas centrado en consultar datos de logs. Los valores predeterminados pueden configurarse en la configuración de logs de la fuente de datos para que el constructor de consultas se cargue previamente con una base de datos/tabla y columnas predeterminadas. OpenTelemetry también puede habilitarse para seleccionar automáticamente las columnas según una versión del esquema.

Los filtros de Tiempo y Nivel se agregan de forma predeterminada, junto con un ORDER BY para la columna Tiempo. Estos filtros están vinculados a sus respectivos campos y se actualizarán a medida que cambien las columnas. El filtro de Nivel se excluye del SQL de forma predeterminada; al cambiarlo desde la opción IS ANYTHING, se habilitará.

El tipo de consulta de logs admite enlaces de datos.

Campo	Descripción
Usar OTel	Habilita las columnas de OpenTelemetry. Sobrescribirá las columnas seleccionadas para usar las columnas definidas por la versión del esquema de OTel seleccionada (deshabilita la selección de columnas).
Columnas	Columnas adicionales que se añadirán a las filas de log. En este campo se puede escribir SQL directamente para permitir funciones y alias de columnas.
Tiempo	La columna principal de marca de tiempo del log. Mostrará tipos de datos similares a tiempo, pero permite valores/funciones personalizados.
Nivel de log	Opcional. El nivel o la severidad del log. Los valores suelen ser INFO, error, Debug, etc.
Mensaje	El contenido del mensaje del log.
ORDER BY	Una lista de expresiones ORDER BY.
Límite	Añade una sentencia LIMIT al final de la consulta. Si se establece en 0, se excluirá, pero esto no se recomienda para conjuntos de datos de logs grandes.
Filtros	Una lista de filtros que se aplicarán en la cláusula WHERE.
Filtro de mensaje	Un campo de texto para filtrar logs cómodamente mediante LIKE %value%. Se excluye cuando el campo está vacío.

Este tipo de consulta mostrará los datos en el panel de logs, junto con un panel de histograma de logs en la parte superior.

Las columnas adicionales seleccionadas en la consulta pueden verse en la fila de log expandida:

​

Series temporales

El tipo de consulta de series temporales es similar a tabla, pero se centra en datos de series temporales.

Ambas vistas son prácticamente iguales, con estas diferencias principales:

• Un campo Tiempo específico.
• En Aggregate mode, se aplica automáticamente una macro de intervalo de tiempo junto con un Group By para el campo Tiempo.
• En Aggregate mode, el campo “Columns” se oculta.
• Se añaden automáticamente un filtro de rango temporal y ORDER BY para el campo Tiempo.

¿Faltan datos en tu visualización?

En algunos casos, el panel de series temporales puede parecer recortado porque el límite predeterminado es 1000.

Prueba a eliminar la cláusula LIMIT estableciéndola en 0 (si tu conjunto de datos lo permite).

Campo	Descripción
Builder Mode	Las consultas simples excluyen Aggregates y Group By, mientras que las consultas de agregación incluyen estas opciones.
Tiempo	La columna de tiempo principal de la consulta. Mostrará tipos de datos temporales, pero también permite valores y funciones personalizados.
Columns	Las columnas seleccionadas. En este campo se puede escribir Raw SQL para permitir funciones y alias de columna. Solo es visible en Simple mode.
Aggregates	Una lista de funciones de agregación. Permite valores personalizados para la función y la columna. Solo es visible en Aggregate mode.
Group By	Una lista de expresiones GROUP BY. Solo es visible en Aggregate mode.
ORDER BY	Una lista de expresiones ORDER BY.
Límite	Añade una sentencia LIMIT al final de la consulta. Si se establece en 0, se omitirá; esto se recomienda para algunos conjuntos de datos de series temporales a fin de mostrar la visualización completa.
Filters	Una lista de filtros que se aplicarán en la cláusula WHERE.

Este tipo de consulta mostrará los datos en el panel de series temporales.

​

Trazas

El tipo de consulta de trazas ofrece un constructor de consultas para buscar y ver trazas fácilmente. Está diseñado para datos de OpenTelemetry, pero se pueden seleccionar columnas para mostrar trazas a partir de un esquema distinto. Los valores predeterminados se pueden configurar en la configuración de trazas de la fuente de datos para permitir que el constructor de consultas se precargue con una base de datos/tabla y columnas predeterminadas. Si se configuran valores predeterminados, la selección de columnas aparecerá contraída de forma predeterminada. OpenTelemetry también se puede habilitar para seleccionar automáticamente las columnas según una versión del esquema.

Se agregan filtros predeterminados con el objetivo de mostrar solo spans de nivel superior. También se incluye un ORDER BY para las columnas Time y Duration Time. Estos filtros están vinculados a sus respectivos campos y se actualizarán a medida que cambien las columnas. El filtro Service Name está excluido del SQL de forma predeterminada; si se cambia la opción IS ANYTHING, se habilitará.

El tipo de consulta de trazas admite enlaces de datos.

Campo	Descripción
Modo de traza	Cambia la consulta de Búsqueda de trazas a búsqueda por Trace ID.
Usar OTel	Habilita las columnas de OpenTelemetry. Sobrescribirá las columnas seleccionadas para usar las columnas definidas por la versión del esquema OTel seleccionada (deshabilita la selección de columnas).
Columna de Trace ID	El ID de la traza.
Columna de Span ID	ID del span.
Columna de Parent Span ID	ID del span padre. Normalmente está vacío para las trazas de nivel superior.
Columna de Service Name	Nombre del servicio.
Columna de Operation Name	Nombre de la operación.
Columna de Start Time	La columna de tiempo principal para el trace span. El momento en que comenzó el span.
Columna de Duration Time	La duración del span. De forma predeterminada, Grafana espera que sea un valor de coma flotante en milisegundos. Se aplica automáticamente una conversión mediante la lista desplegable Duration Unit.
Duration Unit	La unidad de tiempo utilizada para la duración. Nanosegundos de forma predeterminada. La unidad seleccionada se convertirá a un valor de coma flotante en milisegundos, tal como requiere Grafana.
Columna de Tags	Tags del span. Exclúyela si no usas un esquema basado en OTel, ya que espera un tipo de columna Map específico.
Columna de Service Tags	Tags del servicio. Exclúyela si no usas un esquema basado en OTel, ya que espera un tipo de columna Map específico.
ORDER BY	Una lista de expresiones ORDER BY.
límite	Agrega una sentencia LIMIT al final de la consulta. Si se establece en 0, se excluirá, pero esto no se recomienda para conjuntos de datos de trazas grandes.
Filtros	Una lista de filtros que se aplicarán en la cláusula WHERE.
Trace ID	El Trace ID por el que filtrar. Solo se usa en el modo Trace ID y al abrir un enlace de datos de Trace ID.

Este tipo de consulta mostrará los datos con la vista de tabla para el modo Búsqueda de trazas y con el panel de trazas para el modo Trace ID.

​

Editor SQL

Para las consultas demasiado complejas para el constructor de consultas, puede usar el SQL Editor. Esto le da control total sobre la consulta, ya que le permite escribir y ejecutar ClickHouse SQL directamente.

El editor SQL se puede abrir seleccionando “SQL Editor” en la parte superior del editor de consultas.

Las funciones macro también se pueden usar en este modo.

Puede alternar entre tipos de consulta para obtener la visualización que mejor se adapte a su consulta. Este cambio también surte efecto en la vista de dashboard, especialmente con datos de series temporales.

​

Enlaces de datos

Los enlaces de datos de Grafana pueden usarse para enlazar a nuevas consultas. Esta función se ha habilitado en el plugin de ClickHouse para enlazar una traza con los logs y viceversa. Funciona mejor con OpenTelemetry configurado tanto para logs como para trazas en la configuración de la fuente de datos

Ejemplo de enlaces de trazas en una tabla

Ejemplo de enlaces de trazas en logs

​

Cómo crear un enlace de datos

Puedes crear un enlace de datos seleccionando una columna llamada traceID en tu consulta. Este nombre no distingue entre mayúsculas y minúsculas y admite añadir un guion bajo antes de “ID”. Por ejemplo, traceId, TraceId, TRACE_ID y tracE_iD serían válidos.

Si OpenTelemetry está habilitado en una consulta de logs o traza, se incluirá automáticamente una columna de ID de traza.

Cuando hay una columna de ID de traza, el plugin puede añadir enlaces “Ver traza” y “Ver logs” a los datos.

Los interruptores están habilitados de forma predeterminada. Un enlace para el tipo de consulta actual no requiere valores predeterminados configurados, mientras que un enlace entre señales aparece solo cuando la fuente de datos tiene valores predeterminados configurados para la señal de destino. Puedes ocultarlos con los interruptores Mostrar enlaces de “Ver traza” y Mostrar enlaces de “Ver logs” en las secciones de configuración de traza y logs de la fuente de datos.

​

Funciones de enlace

Con los enlaces de datos disponibles, puedes abrir trazas y logs con el ID de traza proporcionado.

“Ver traza” abrirá un panel dividido con la traza, y “Ver logs” abrirá una consulta de logs filtrada por el ID de traza. Si se hace clic en el enlace desde un dashboard en lugar de la vista Explore, el enlace se abrirá en una pestaña nueva de la vista Explore.

Es necesario tener valores predeterminados configurados tanto para logs como para traces al cambiar entre tipos de consulta (de logs a trazas y de trazas a logs). Los valores predeterminados no son necesarios al abrir un enlace del mismo tipo de consulta, ya que basta con copiar la consulta.

Ejemplo de visualización de una traza (panel derecho) desde una consulta de logs (panel izquierdo)

​

Macros

Las macros son una forma sencilla de añadir SQL dinámico a la consulta. Antes de que una consulta se envíe al servidor de ClickHouse, el plugin expandirá la macro y la sustituirá por la expresión completa.

Las consultas tanto del SQL Editor como del constructor de consultas pueden usar macros.

​

Uso de macros

Las macros pueden incluirse en cualquier parte de la consulta, varias veces si es necesario.

A continuación se muestra un ejemplo de uso de la macro $__timeFilter:

Entrada:

SELECT log_time, log_message
FROM logs
WHERE $__timeFilter(log_time)

Resultado final de la consulta:

SELECT log_time, log_message
FROM logs
WHERE log_time >= toDateTime(1415792726) AND log_time <= toDateTime(1447328726)

En este ejemplo, el intervalo de tiempo del dashboard de Grafana se aplica a la columna log_time.

El plugin también admite la notación con llaves {}. Use esta notación cuando se necesiten consultas dentro de los parámetros.

​

Lista de macros

Esta es una lista de todas las macros disponibles en el plugin:

Macro	Descripción	Ejemplo de salida
$__dateFilter(columnName)	Se reemplaza por un filtro de rango de tiempo en la columna proporcionada, usando el intervalo de tiempo del panel de Grafana como Date.	columnName >= toDate('2022-10-21') AND columnName <= toDate('2022-10-23')
$__timeFilter(columnName)	Se reemplaza por un filtro de rango de tiempo en la columna proporcionada, usando el intervalo de tiempo del panel de Grafana como DateTime.	columnName >= toDateTime(1415792726) AND time <= toDateTime(1447328726)
$__timeFilter_ms(columnName)	Se reemplaza por un filtro de rango de tiempo en la columna proporcionada, usando el intervalo de tiempo del panel de Grafana como DateTime64.	columnName >= fromUnixTimestamp64Milli(1415792726123) AND columnName <= fromUnixTimestamp64Milli(1447328726456)
$__dateTimeFilter(dateColumn, timeColumn)	Abreviatura que combina $__dateFilter() y $__timeFilter() usando columnas Date y DateTime independientes. Alias: $__dt()	$__dateFilter(dateColumn) AND $__timeFilter(timeColumn)
$__fromTime	Se reemplaza por la hora de inicio del intervalo del panel de Grafana convertida a DateTime.	toDateTime(1415792726)
$__fromTime_ms	Se reemplaza por la hora de inicio del intervalo del panel convertida a DateTime64.	fromUnixTimestamp64Milli(1415792726123)
$__toTime	Se reemplaza por la hora de finalización del intervalo del panel de Grafana convertida a DateTime.	toDateTime(1447328726)
$__toTime_ms	Se reemplaza por la hora de finalización del intervalo del panel convertida a DateTime64.	fromUnixTimestamp64Milli(1447328726456)
$__timeInterval(columnName)	Se reemplaza por una función que calcula el intervalo en función del tamaño de la ventana en segundos.	toStartOfInterval(toDateTime(columnName), INTERVAL 20 second)
$__timeInterval_ms(columnName)	Se reemplaza por una función que calcula el intervalo en función del tamaño de la ventana en milisegundos.	toStartOfInterval(toDateTime64(columnName, 3), INTERVAL 20 millisecond)
$__interval_s	Se reemplaza por el intervalo del dashboard en segundos.	20
$__conditionalAll(condition, $templateVar)	Se reemplaza por el primer parámetro cuando la variable de plantilla del segundo parámetro no selecciona todos los valores. Se reemplaza por 1=1 cuando la variable de plantilla selecciona todos los valores.	condition o 1=1