Construtor de consultas

Uso do construtor de consultas no plugin do ClickHouse para Grafana

É possível executar qualquer consulta com o plugin do ClickHouse. O construtor de consultas é uma opção prática para consultas mais simples, mas, para consultas mais complexas, você precisará usar o SQL Editor.

Todas as consultas no construtor de consultas têm um tipo de consulta e exigem que pelo menos uma coluna seja selecionada.

Os tipos de consulta disponíveis são:

• Table: o tipo de consulta mais simples para exibir dados em formato de tabela. Funciona bem como uma opção genérica tanto para consultas simples quanto para consultas complexas que contêm funções de agregação.
• Logs: otimizado para criar consultas de logs. Funciona melhor na visualização Explore com as configurações padrão definidas.
• Time Series: mais indicado para criar consultas de séries temporais. Permite selecionar uma coluna de tempo específica e adicionar funções de agregação.
• Traces: otimizado para pesquisar/visualizar rastreamentos. Funciona melhor na visualização Explore com as configurações padrão definidas.
• SQL Editor: o SQL Editor pode ser usado quando você quiser controle total sobre a consulta. Nesse modo, qualquer consulta SQL pode ser executada.

​

Tipos de consulta

A configuração Tipo de consulta altera o layout do construtor de consultas para corresponder ao tipo de consulta que está sendo criada. O tipo de consulta também determina qual painel é usado para visualizar os dados.

​

Tabela

O tipo de consulta mais flexível é a consulta de tabela. Ela funciona como uma categoria genérica para os outros construtores de consulta, projetada para lidar com consultas simples e de agregação.

Campo	Descrição
Modo do construtor	Consultas simples não incluem Aggregates nem Group By, enquanto consultas de agregação incluem essas opções.
Colunas	As colunas selecionadas. É possível digitar SQL puro neste campo para usar funções e aliases de coluna.
Agregações	Uma lista de funções de agregação. Permite valores personalizados para função e coluna. Visível apenas no modo Aggregate.
Agrupar por	Uma lista de expressões GROUP BY. Visível apenas no modo Aggregate.
Ordenar por	Uma lista de expressões ORDER BY.
Limite	Adiciona uma instrução LIMIT ao final da consulta. Se definido como 0, será omitido. Algumas visualizações podem exigir que isso seja definido como 0 para exibir todos os dados.
Filtros	Uma lista de filtros a serem aplicados na cláusula WHERE.

Esse tipo de consulta exibirá os dados como uma tabela.

​

Logs

O tipo de consulta de logs oferece um construtor de consultas voltado para consultar dados de logs. Os padrões podem ser configurados na configuração de logs da fonte de dados, permitindo que o construtor de consultas seja pré-carregado com um database/table e colunas padrão. OpenTelemetry também pode ser habilitado para selecionar automaticamente as colunas de acordo com uma versão do esquema.

Os filtros Time e Level são adicionados por padrão, juntamente com um Order By para a coluna Time. Esses filtros estão vinculados aos respectivos campos e serão atualizados conforme as colunas forem alteradas. O filtro Level é excluído do SQL por padrão; ao alterá-lo da opção IS ANYTHING, ele será habilitado.

O tipo de consulta de logs oferece suporte a links de dados.

Campo	Descrição
Usar OTel	Habilita colunas do OpenTelemetry. Substitui as colunas selecionadas para usar as colunas definidas pela versão do esquema OTel selecionada (desabilita a seleção de colunas).
Colunas	Colunas extras a serem adicionadas às linhas de log. É possível digitar SQL bruto neste campo para permitir funções e aliases de colunas.
Time	A coluna de timestamp principal do log. Exibe tipos semelhantes a tempo, mas permite valores/funções personalizados.
Nível do log	Opcional. O level ou severity do log. Os valores normalmente são como INFO, error, Debug etc.
Mensagem	O conteúdo da mensagem de log.
Order By	Uma lista de expressões ORDER BY.
Limite	Anexa uma instrução LIMIT ao final da consulta. Se definido como 0, ele será excluído, mas isso não é recomendado para grandes datasets de logs.
Filtros	Uma lista de filtros a serem aplicados na cláusula WHERE.
Filtro de mensagem	Um campo de texto para filtrar logs de forma prática usando LIKE %value%. Excluído quando a entrada estiver vazia.

Esse tipo de consulta renderiza os dados no painel de logs, juntamente com um painel de histograma de logs na parte superior.

As colunas extras selecionadas na consulta podem ser visualizadas na linha de log expandida:

​

Séries temporais

O tipo de consulta de séries temporais é semelhante a table, mas com foco em dados de séries temporais.

As duas visualizações são, em grande parte, iguais, com estas diferenças importantes:

• Um campo Time dedicado.
• No modo Aggregate, uma macro de intervalo de tempo é aplicada automaticamente junto com um Group By para o campo Time.
• No modo Aggregate, o campo “Columns” fica oculto.
• Um filtro de intervalo de tempo e um Order By são adicionados automaticamente para o campo Time.

A visualização está sem dados?

Em alguns casos, o painel de séries temporais pode parecer cortado porque o limite padrão é 1000.

Tente remover a cláusula LIMIT definindo-a como 0 (se o seu conjunto de dados permitir).

Campo	Descrição
modo do construtor	Consultas simples não incluem Aggregates nem Group By, enquanto consultas agregadas incluem essas opções.
Time	A coluna de tempo principal da consulta. Exibe tipos de dados temporais, mas permite valores/funções personalizados.
Columns	As colunas selecionadas. É possível digitar SQL bruto neste campo para permitir funções e aliases de coluna. Visível apenas no modo Simple.
Aggregates	Uma lista de funções de agregação. Permite valores personalizados para função e coluna. Visível apenas no modo Aggregate.
Group By	Uma lista de expressões GROUP BY. Visível apenas no modo Aggregate.
Order By	Uma lista de expressões ORDER BY.
Limit	Adiciona uma instrução LIMIT ao final da consulta. Se for definido como 0, ele será omitido; isso é recomendado para alguns conjuntos de dados de séries temporais a fim de exibir a visualização completa.
Filters	Uma lista de filtros a serem aplicados na cláusula WHERE.

Esse tipo de consulta exibirá os dados no painel de séries temporais.

​

Rastreamentos

O tipo de consulta de rastreamento oferece um construtor de consultas para pesquisar e visualizar rastreamentos com facilidade. Ele foi projetado para dados do OpenTelemetry, mas é possível selecionar colunas para renderizar rastreamentos de um esquema diferente. Os padrões podem ser configurados na configuração de rastreamento da fonte de dados para permitir que o construtor de consultas seja pré-carregado com um banco de dados/tabela e colunas padrão. Se houver padrões configurados, a seleção de colunas ficará recolhida por padrão. O OpenTelemetry também pode ser ativado para selecionar automaticamente as colunas de acordo com uma versão do esquema.

Filtros padrão são adicionados com o objetivo de mostrar apenas spans de nível superior. Também é incluído um ORDER BY para as colunas Time e Duration Time. Esses filtros estão vinculados aos respectivos campos e serão atualizados conforme as colunas forem alteradas. O filtro Service Name é excluído do SQL por padrão; ao alterá-lo da opção IS ANYTHING, ele será ativado.

O tipo de consulta de rastreamento oferece suporte a links de dados.

Field	Description
Trace Mode	Altera a consulta de Trace Search para Trace ID lookup.
Use OTel	Ativa colunas do OpenTelemetry. Substitui as colunas selecionadas para usar as colunas definidas pela versão de esquema OTel selecionada (desativa a seleção de colunas).
Trace ID Column	O ID do rastreamento.
Span ID Column	ID do span.
Parent Span ID Column	ID do span pai. Geralmente fica vazio em rastreamentos de nível superior.
Service Name Column	Nome do serviço.
Operation Name Column	Nome da operação.
Start Time Column	A coluna de tempo principal do trace span. O momento em que o span foi iniciado.
Duration Time Column	A duração do span. Por padrão, o Grafana espera que seja um float em milissegundos. Uma conversão é aplicada automaticamente por meio do menu suspenso Duration Unit.
Duration Unit	A unidade de tempo usada para a duração. O padrão é nanossegundos. A unidade selecionada será convertida em um float em milissegundos, conforme exigido pelo Grafana.
Tags Column	Tags do span. Exclua esta coluna se não estiver usando um esquema baseado em OTel, pois é esperado um tipo específico de coluna map.
Service Tags Column	Tags do serviço. Exclua esta coluna se não estiver usando um esquema baseado em OTel, pois é esperado um tipo específico de coluna map.
Order By	Uma lista de expressões ORDER BY.
Limit	Acrescenta uma instrução LIMIT ao final da consulta. Se definido como 0, ele será excluído, mas isso não é recomendado para grandes datasets de rastreamento.
Filters	Uma lista de filtros a serem aplicados na cláusula WHERE.
Trace ID	O Trace ID pelo qual filtrar. Usado apenas no modo Trace ID e ao abrir um link de dados de Trace ID.

Esse tipo de consulta renderiza os dados na visualização de tabela no modo Trace Search e no painel de rastreamento no modo Trace ID.

​

SQL Editor

Para consultas complexas demais para o construtor de consultas, você pode usar o SQL Editor. Isso dá a você controle total sobre a consulta, permitindo escrever e executar ClickHouse SQL puro.

O SQL Editor pode ser aberto selecionando “SQL Editor” na parte superior do editor de consultas.

Funções de macro ainda podem ser usadas nesse modo.

Você pode alternar entre tipos de consulta para obter a visualização que melhor se adapta à sua consulta. Essa alternância também tem efeito na visualização de dashboard, especialmente com dados de séries temporais.

​

Links de dados

Os links de dados do Grafana podem ser usados para direcionar para novas consultas. Esse recurso foi habilitado no plugin do ClickHouse para vincular um trace a logs e vice-versa. Ele funciona melhor com o OpenTelemetry configurado tanto para logs quanto para rastreamento na configuração da fonte de dados

Exemplo de links de trace em uma tabela

Exemplo de links de trace em logs

​

Como criar um link de dados

Você pode criar um link de dados selecionando uma coluna chamada traceID na sua consulta. Esse nome não diferencia maiúsculas de minúsculas e permite adicionar um sublinhado antes de “ID”. Por exemplo: traceId, TraceId, TRACE_ID e tracE_iD seriam todos válidos.

Se o OpenTelemetry estiver habilitado em uma consulta de logs ou traces, uma coluna de trace ID será incluída automaticamente.

Ao incluir uma coluna de trace ID, os links “View Trace” e “View Logs” serão associados aos dados.

​

Recursos de vinculação

Com os links de dados disponíveis, você pode abrir rastreamento e logs usando o trace ID fornecido.

“View Trace” abrirá um painel dividido com o trace, e “View Logs” abrirá uma consulta de logs filtrada pelo trace ID. Se o link for clicado em um dashboard em vez da visualização Explore, ele será aberto em uma nova aba na visualização Explore.

É necessário ter padrões configurados tanto para logs quanto para rastreamento ao alternar entre tipos de consulta (de logs para rastreamento e de rastreamento para logs). Os padrões não são necessários ao abrir um link do mesmo tipo de consulta, já que a consulta pode ser simplesmente copiada.

Exemplo de visualização de um trace (painel direito) a partir de uma consulta de logs (painel esquerdo)

​

Macros

Macros são uma forma simples de adicionar SQL dinâmico à sua consulta. Antes de uma consulta ser enviada ao servidor ClickHouse, o plugin expandirá a macro e a substituirá pela expressão completa.

Consultas tanto do SQL Editor quanto do Query Builder podem usar macros.

​

Usando macros

As macros podem ser incluídas em qualquer parte da consulta, várias vezes, se necessário.

Veja um exemplo de uso da macro $__timeFilter:

Entrada:

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

Saída final da consulta:

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

Neste exemplo, o intervalo de tempo do dashboard do Grafana é aplicado à coluna log_time.

O plugin também aceita a notação com chaves {}. Use essa notação quando for necessário usar consultas dentro de parâmetros.

​

Lista de macros

Esta é uma lista de todas as macros disponíveis no plugin:

Macro	Descrição	Exemplo de saída
$__dateFilter(columnName)	Substituído por um filtro de intervalo de tempo na coluna informada usando o intervalo de tempo do painel do Grafana como Date.	columnName >= toDate('2022-10-21') AND columnName <= toDate('2022-10-23')
$__timeFilter(columnName)	Substituído por um filtro de intervalo de tempo na coluna informada usando o intervalo de tempo do painel do Grafana como DateTime.	columnName >= toDateTime(1415792726) AND time <= toDateTime(1447328726)
$__timeFilter_ms(columnName)	Substituído por um filtro de intervalo de tempo na coluna informada usando o intervalo de tempo do painel do Grafana como DateTime64.	columnName >= fromUnixTimestamp64Milli(1415792726123) AND columnName <= fromUnixTimestamp64Milli(1447328726456)
$__dateTimeFilter(dateColumn, timeColumn)	Abreviação que combina $__dateFilter() e $__timeFilter() usando colunas separadas de Date e DateTime. Alias $__dt()	$__dateFilter(dateColumn) AND $__timeFilter(timeColumn)
$__fromTime	Substituído pelo horário inicial do intervalo do painel do Grafana convertido para DateTime.	toDateTime(1415792726)
$__fromTime_ms	Substituído pelo horário inicial do intervalo do painel convertido para DateTime64.	fromUnixTimestamp64Milli(1415792726123)
$__toTime	Substituído pelo horário final do intervalo do painel do Grafana convertido para DateTime.	toDateTime(1447328726)
$__toTime_ms	Substituído pelo horário final do intervalo do painel convertido para DateTime64.	fromUnixTimestamp64Milli(1447328726456)
$__timeInterval(columnName)	Substituído por uma função que calcula o intervalo com base no tamanho da janela em segundos.	toStartOfInterval(toDateTime(columnName), INTERVAL 20 second)
$__timeInterval_ms(columnName)	Substituído por uma função que calcula o intervalo com base no tamanho da janela em milissegundos.	toStartOfInterval(toDateTime64(columnName, 3), INTERVAL 20 millisecond)
$__interval_s	Substituído pelo intervalo do dashboard em segundos.	20
$__conditionalAll(condition, $templateVar)	Substituído pelo primeiro parâmetro quando a variável de template no segundo parâmetro não seleciona todos os valores. Substituído por 1=1 quando a variável de template seleciona todos os valores.	condition ou 1=1