Variáveis de dashboard
As variáveis de dashboard são a principal novidade desta semana. Elas se baseiam no modelo de filtros que os dashboards já utilizam: qualquer filtro existente ou novo pode ser disponibilizado como variável.
Por padrão, uma variável usa o nome de exibição do filtro. Se esse nome contiver caracteres especiais ou se dois filtros tiverem o mesmo nome de exibição, você poderá atribuir um nome personalizado à variável. Esse nome permanece inalterado caso o filtro seja renomeado posteriormente. A página de configuração mostra o nome a ser referenciado e, quando a variável é ativada, ele também aparece na dica de ferramenta do filtro.
Os gráficos de SQL bruto oferecem diversas formas de usar variáveis.
$__filter($var) expande a seleção atual de uma variável. É o equivalente, para uma única variável, da macro $__filters, que expande todos os filtros.
A adição mais interessante é $__conditionalAll(condition, $var). O primeiro argumento é uma condição, e o segundo, uma variável. Quando a variável tem uma seleção, a condição é incluída na consulta. Sem seleção, toda a expressão se torna 1 = 1 e não afeta a filtragem.
Isso possibilita mapeamentos entre fontes. Um dashboard pode mapear códigos de status de traces para error ou info, permitindo que um filtro de gravidade definido para uma tabela de logs filtre uma tabela de traces. Selecione error no nível do dashboard, e a consulta de traces filtrará por um status de erro.
O preenchimento automático sugere todas as variáveis disponíveis e os formatos compatíveis. Seguindo uma sugestão de Brandon, ele agora mostra a expansão efetiva em linha usando a seleção atual. As sugestões de macro também incluem suas expansões, e uma nova seção da documentação explica o que cada macro faz. A validação detecta referências a variáveis inexistentes e macros chamadas com argumentos incorretos.
Os gráficos do builder usam a mesma substituição de variáveis na maioria dos campos editáveis, tanto em entradas SQL quanto Lucene. As variáveis funcionam em WHERE, GROUP BY, HAVING e ORDER BY, com o mesmo preenchimento automático e validação. Os campos Lucene oferecem suporte a variáveis, mas não a macros. Os campos do builder SQL oferecem as macros relacionadas a variáveis, em vez do conjunto completo disponível no SQL bruto.
Os alertas têm uma regra rígida: todas as variáveis são avaliadas usando valores vazios. Se uma consulta de alerta fizer referência a variáveis, o editor emitirá um aviso antes de salvá-la. A visualização e o SQL gerado mostram a expansão vazia, inclusive na página de detalhes do alerta, e a tarefa de alerta aplica esses valores vazios durante a execução.
A configuração de variáveis continua protegida por NEXT_PUBLIC_ENABLE_DASHBOARD_VARIABLES. Sem variáveis configuradas, o comportamento do dashboard permanece inalterado.
PRs relacionados: #2836 adiciona configuração de variáveis de filtro, #2873 substitui variáveis em gráficos de SQL bruto, #2874 adiciona preenchimento automático e validações para variáveis SQL de dashboard, #2901 oferece suporte a variáveis de dashboard em blocos do chart builder, #2910 expande variáveis como vazias em consultas de alerta, #2923 oferece suporte a consultas de valores de variáveis dependentes, #2937 oferece suporte a macros aninhadas e referências a variáveis em macros, #2944 adiciona variáveis de dashboard à API externa
Página de detalhes do alerta com histórico de avaliações
Até agora, um alerta oferecia uma faixa de histórico e pouco mais. Não havia muito o que inspecionar para entender o que o alerta realmente fazia.
A nova página de detalhes mostra todas as avaliações. Para alertas agrupados, ela indica qual grupo foi acionado e qual valor ultrapassou o limite. Cada entrada também inclui a duração da consulta do ClickHouse, com a configuração do alerta disponível ao lado.
A coluna de buckets preenchidos retroativamente merece uma explicação. Quando uma avaliação é perdida, a próxima execução preenche a lacuna processando o bucket ausente. Portanto, qualquer bucket preenchido retroativamente indica que o alerta está atrasado em relação ao agendamento. Uma consulta lenta do ClickHouse agora deixa evidências visíveis, em vez de atrasar silenciosamente as avaliações posteriores.
Os marcadores do gráfico se alinham ao início do bucket avaliado, facilitando a visualização de quando o alerta foi acionado e quando voltou ao estado OK.
Você também pode editar ou excluir um alerta diretamente da página de detalhes. Não é necessário voltar ao modal de pesquisa salva nem ao editor de bloco do dashboard. A possibilidade de incluir mais configurações do alerta nesta página ainda está sendo avaliada.
A página continua disponível somente com
NEXT_PUBLIC_ENABLE_ALERT_DETAILS.
PRs relacionados: #2833 modelo de leitura das avaliações de alerta e GET /alerts/:id/evaluations, #2834 persistir erros de avaliação de alerta e analytics em AlertHistory, #2835 página de detalhes do alerta com histórico de avaliações, #2928 alinhar os marcadores do gráfico de alerta ao início do bucket avaliado, #2931 permitir editar e excluir alertas na página de detalhes do alerta
Investigando alertas e anotações de ferramentas MCP
Os alertas disparados agora têm um botão Investigar. Ao clicar nele, uma investigação em um notebook é iniciada pela página de alertas ou pela página de detalhes do alerta.
O objetivo final é iniciar essas investigações automaticamente quando um alerta for disparado. O botão é uma etapa intermediária útil, não a forma final pretendida.
Todas as ferramentas no servidor MCP do ClickStack agora também incluem anotações indicativas. Antes, o servidor não informava se uma ferramenta era somente leitura enquanto outra alterava ou excluía dados.
A adição de
readOnlyHint e destructiveHint fornece aos clientes informações suficientes para tratar essas ferramentas de forma diferente. As leituras podem prosseguir sem interrupção, enquanto ações destrutivas podem aguardar aprovação explícita. Excluir um alerta é o exemplo mais óbvio. Você deve receber uma solicitação de confirmação antes que isso aconteça.
A última alteração afeta quais ferramentas os agentes escolhem inicialmente. O uso de clickstack_sql vinha aumentando à medida que o conjunto de ferramentas se expandia sem uma política de seleção clara. Os agentes recorriam ao SQL bruto mesmo quando as ferramentas de builder eram mais adequadas.
Isso é importante além da correção da consulta. O SQL bruto cria blocos de resultados estáticos. As ferramentas de builder, clickstack_table, clickstack_timeseries e clickstack_search, produzem blocos que permitem detalhar os dados e pivotar a partir deles.
O MCP agora direciona os agentes primeiro para essas ferramentas de builder e reserva o SQL bruto para consultas que eles realmente não conseguem expressar. As pontuações de avaliação melhoraram consideravelmente após a alteração.
PRs relacionados: #2838 adiciona anotações de ferramentas MCP (readOnlyHint etc.) a todas as ferramentas, #2840 direciona agentes para ferramentas de builder de consultas em vez de SQL bruto, #2870 direciona agentes de dashboard para filtros de blocos por série. O próprio botão Investigar não tem um PR público para vincular.
Gráficos de métricas com várias séries em uma única consulta
Exibir várias métricas em um único gráfico costumava exigir a execução de uma consulta ClickHouse por série e, em seguida, a mesclagem dos conjuntos de resultados no Node ou no navegador. Um gráfico com N séries gerava N consultas.
Agora, gráficos com várias séries são compilados em uma única consulta SQL. Cada série se torna uma CTE, e o ClickHouse as mescla ao final. As razões seguem o mesmo fluxo: ambas as séries são geradas em uma única consulta, e a razão é calculada na projeção final.
O benefício imediato é ter menos consultas. O mesmo formato de consulta também estabelece a base para fórmulas de métricas. Uma fórmula precisa que todas as séries estejam disponíveis como colunas em uma única relação para poder ser expressa no
SELECT final. É exatamente isso que o compilador produz agora, e o trabalho com fórmulas já está sendo desenvolvido a partir disso.
A alteração revelou uma regressão. Blocos com várias séries não eram renderizados quando combinavam agregações que produziam números de ponto flutuante e inteiros. Bastava combinar um quantile de histograma, que retorna Float64, com um count de histograma, que retorna Int64, para acioná-la.
O UNION ALL composto e o pivô enviavam todas as séries pela mesma coluna, fazendo com que o ClickHouse ampliasse o tipo para Variant(Float64, Int64). Esse caso já foi corrigido.
PRs relacionados: #2858 ampliar a cobertura de testes de inteiros para a mesclagem de métricas com várias séries, #2859 mover o cálculo de mesclagem de métricas com várias séries para o ClickHouse, #2907 cobertura de tarefas de alerta para blocos de métricas com várias séries, #2916 corrigir gráficos de métricas com várias séries que combinam agregações de números de ponto flutuante e inteiros, #2872 modelo de expressão de fórmula, #2908 renderizar fórmulas na consulta de métricas composta, #2909 interface do editor de gráficos para fórmulas de métricas
Correções no preenchimento automático do Lucene e nos requisitos de senha
Os testes das variáveis do dashboard revelaram outra regressão: o preenchimento automático do Lucene havia deixado de funcionar silenciosamente em quase todos os lugares. A página de Busca era o único local em que ele ainda funcionava.
A outra alteração está na página Join Team, em que os usuários convidados definem suas senhas. A página não mostrava os requisitos de senha, embora o backend os aplicasse. Inserir algo inválido gerava uma mensagem genérica de “Senha inválida”, deixando o usuário sem saber qual era a política.
Esses requisitos agora estão visíveis. A análise do componente compartilhado que os exibe também revelou duas divergências em relação ao backend: quais caracteres especiais são considerados e o comprimento máximo da senha. Ambas foram corrigidas.
PRs relacionados: #2902 restaura o preenchimento automático do Lucene, #2904 mostra os requisitos de senha na página Join Team