Como configurar a fonte de dados ClickHouse no Grafana

A maneira mais fácil de modificar uma configuração é na UI do Grafana, na página de configuração do plugin, mas as fontes de dados também podem ser provisionadas por meio de um arquivo YAML. Esta página mostra uma lista das opções de configuração disponíveis no plugin ClickHouse, bem como exemplos de configuração para quem provisiona uma fonte de dados com YAML. Para ter uma visão geral rápida de todas as opções, consulte aqui a lista completa de opções de configuração.

Configurações comuns

Exemplo de tela de configuração: Exemplo de YAML de configuração para configurações comuns:

jsonData:
  host: 127.0.0.1 # (obrigatório) endereço do servidor.
  port: 9000      # (obrigatório) porta do servidor. Para native, o padrão é 9440 (seguro) e 9000 (inseguro). Para HTTP, o padrão é 8443 (seguro) e 8123 (inseguro).

  protocol: native # (obrigatório) o protocolo usado para a conexão. Pode ser definido como "native" ou "http".
  secure: false    # defina como true se a conexão for segura.

  username: default # o nome de usuário utilizado para autenticação.

  tlsSkipVerify:     <boolean> # ignora a verificação TLS quando definido como true.
  tlsAuth:           <boolean> # defina como true para habilitar a autenticação de cliente TLS.
  tlsAuthWithCACert: <boolean> # defina como true se o certificado CA for fornecido. Obrigatório para verificar certificados TLS autoassinados.

secureJsonData:
  password: secureExamplePassword # a senha utilizada para autenticação.

  tlsCACert:     <string> # certificado CA TLS
  tlsClientCert: <string> # certificado de cliente TLS
  tlsClientKey:  <string> # chave de cliente TLS

Observe que uma propriedade version é adicionada quando a configuração é salva pela UI. Isso indica a versão do plugin com a qual a configuração foi salva.

Protocolo HTTP

Mais configurações serão exibidas se você optar por se conectar pelo protocolo HTTP.

Caminho HTTP

Se o seu servidor HTTP estiver exposto em um caminho de URL diferente, você pode adicioná-lo aqui.

jsonData:
  # exclui a primeira barra
  path: additional/path/example

Cabeçalhos HTTP personalizados

Você pode adicionar cabeçalhos personalizados às solicitações enviadas ao seu servidor. Os cabeçalhos podem ser de texto simples ou seguros. Todas as chaves dos cabeçalhos são armazenadas em texto simples, enquanto os valores seguros dos cabeçalhos são salvos na configuração segura (de forma semelhante ao campo password).

Valores seguros via HTTPEmbora os valores seguros dos cabeçalhos sejam armazenados com segurança na configuração, o valor ainda será enviado por HTTP se a conexão segura estiver desabilitada.

Exemplo de YAML para cabeçalhos simples/seguros:

jsonData:
  httpHeaders:
  - name: X-Example-Plain-Header
    value: plain text value
    secure: false
  - name: X-Example-Secure-Header
    # "value" é omitido
    secure: true
secureJsonData:
  secureHttpHeaders.X-Example-Secure-Header: secure header value

Configurações adicionais

Estas configurações adicionais são opcionais. Exemplo em YAML:

jsonData:
  defaultDatabase: default # banco de dados padrão carregado pelo construtor de consultas. Padrão: "default".
  defaultTable: <string>   # tabela padrão carregada pelo construtor de consultas.

  dialTimeout: 10    # timeout de conexão ao servidor, em segundos. Padrão: "10".
  queryTimeout: 60   # timeout de consulta ao executar uma consulta, em segundos. Padrão: 60. Requer permissões no usuário; se ocorrer um erro de permissão, tente definir como "0" para desativá-lo.
  validateSql: false # quando definido como true, valida o SQL no SQL Editor.

OpenTelemetry

O OpenTelemetry (OTel) é fortemente integrado ao plugin. Os dados do OpenTelemetry podem ser exportados para o ClickHouse com nosso plugin exporter. Para obter o melhor uso, recomenda-se configurar o OTel tanto para logs quanto para traces. Também é necessário configurar esses padrões para habilitar data links, um recurso que permite fluxos de trabalho avançados de observabilidade.

Logs

Para acelerar a montagem de consultas de logs, você pode definir um banco de dados/tabela padrão, bem como colunas para a consulta de logs. Isso pré-carregará o construtor de consultas com uma consulta de logs pronta para execução, o que agiliza a navegação na página Explore para observabilidade. Se você estiver usando OpenTelemetry, ative a opção “Use OTel” e defina a tabela de logs padrão como otel_logs. Isso substituirá automaticamente as colunas padrão para usar a versão de esquema do OTel selecionada. Embora OpenTelemetry não seja obrigatório para logs, usar um único dataset de logs/traces ajuda a manter um fluxo de trabalho de observabilidade mais fluido com links de dados. Exemplo de tela de configuração de logs: Exemplo de YAML de configuração de logs:

jsonData:
  logs:
    defaultDatabase: default # banco de dados de log padrão.
    defaultTable: otel_logs  # tabela de log padrão. Se estiver usando OTel, defina como "otel_logs".

    otelEnabled: false  # defina como true se o OTel estiver habilitado.
    otelVersion: latest # a versão do esquema do OTel collector a ser usada. As versões são exibidas na UI, mas "latest" utilizará a versão mais recente disponível no plugin.

    # Colunas padrão selecionadas ao abrir uma nova consulta de log. Ignorado se o OTel estiver habilitado.
    timeColumn:       <string> # a coluna de tempo principal do log.
    levelColumn:   <string> # o nível/severidade do log. Os valores geralmente aparecem como "INFO", "error" ou "Debug".
    messageColumn: <string> # a mensagem/conteúdo do log.

Traces

Para acelerar a criação de consultas para traces, você pode definir um banco de dados/tabela padrão, bem como as colunas da consulta de trace. Isso pré-carregará o construtor de consultas com uma consulta de busca de trace pronta para execução, tornando a navegação na página Explore mais rápida para observabilidade. Se você estiver usando OpenTelemetry, deverá ativar a opção “Use OTel” e definir a tabela de traces padrão como otel_traces. Isso substituirá automaticamente as colunas padrão para usar a versão do esquema OTel selecionada. Embora OpenTelemetry não seja obrigatório, esse recurso funciona melhor ao usar o esquema dele para traces. Exemplo de tela de configuração de traces: Exemplo de YAML de configuração de traces:

jsonData:
  traces:
    defaultDatabase: default  # banco de dados de trace padrão.
    defaultTable: otel_traces # tabela de trace padrão. Se estiver usando OTel, deve ser definida como "otel_traces".

    otelEnabled: false  # defina como true se o OTel estiver habilitado.
    otelVersion: latest # versão do schema do OTel collector a ser usada. As versões são exibidas na UI, mas "latest" usará a versão mais recente disponível no plugin.

    # Colunas padrão selecionadas ao abrir uma nova consulta de trace. Ignorado se o OTel estiver habilitado.
    traceIdColumn:       <string>    # coluna de trace ID.
    spanIdColumn:        <string>    # coluna de span ID.
    operationNameColumn: <string>    # coluna de nome da operação.
    parentSpanIdColumn:  <string>    # coluna de span ID pai.
    serviceNameColumn:   <string>    # coluna de nome do serviço.
    durationTimeColumn:  <string>    # coluna de duração.
    durationUnitColumn:  <time unit> # unidade de tempo da duração. Pode ser definida como "seconds", "milliseconds", "microseconds" ou "nanoseconds". Para OTel, o padrão é "nanoseconds".
    startTimeColumn:     <string>    # coluna de hora de início. É a coluna de tempo principal do trace span.
    tagsColumn:          <string>    # coluna de tags. Deve ser do tipo map.
    serviceTagsColumn:   <string>    # coluna de tags do serviço. Deve ser do tipo map.

Aliases de coluna

Usar aliases de coluna é uma forma prática de consultar seus dados com nomes e tipos diferentes. Com aliases, você pode pegar um esquema aninhado e achatá-lo para que possa ser selecionado facilmente no Grafana. Usar aliases pode ser útil para você se:

Você conhece seu esquema e a maioria de suas propriedades/tipos aninhados
Você armazena seus dados em tipos map
Você armazena JSON como strings
Você costuma aplicar funções para transformar as colunas que seleciona

Colunas ALIAS definidas na tabela

O ClickHouse oferece aliases de coluna nativamente e funciona com o Grafana sem necessidade de configuração adicional. As colunas ALIAS podem ser definidas diretamente na tabela.

CREATE TABLE alias_example (
  TimestampNanos DateTime(9),
  TimestampDate ALIAS toDate(TimestampNanos)
)

No exemplo acima, criamos um alias chamado TimestampDate que converte o timestamp em nanossegundos para o tipo Date. Esse dado não é armazenado em disco como a primeira coluna; ele é calculado no momento da consulta. Aliases definidos na tabela não são retornados com SELECT *, mas isso pode ser configurado nas configurações do servidor. Para mais informações, leia a documentação do tipo de coluna ALIAS.

Tabelas de aliases de colunas

Por padrão, o Grafana fornecerá sugestões de colunas com base na resposta de DESC table. Em alguns casos, talvez você queira substituir completamente as colunas que o Grafana enxerga. Isso ajuda a ocultar o esquema no Grafana durante a seleção de colunas, o que pode melhorar a experiência do usuário, dependendo da complexidade da sua tabela. A vantagem disso em relação aos aliases definidos na tabela é que você pode atualizá-los facilmente sem precisar alterar a tabela. Em alguns esquemas, isso pode ter milhares de entradas, o que pode sobrecarregar a definição da tabela subjacente. Isso também permite ocultar colunas que você quer que o usuário ignore. O Grafana exige que a tabela de aliases tenha a seguinte estrutura de colunas:

CREATE TABLE aliases (
  `alias` String,  -- O nome do alias, como exibido no seletor de colunas do Grafana
  `select` String, -- A sintaxe SELECT a ser usada no gerador de SQL
  `type` String    -- O tipo da coluna resultante, para que o plugin possa ajustar as opções da UI de acordo com o tipo de dado.
)

Veja como podemos reproduzir o comportamento da coluna ALIAS usando a tabela de aliases:

CREATE TABLE example_table (
  TimestampNanos DateTime(9)
);

CREATE TABLE example_table_aliases (`alias` String, `select` String, `type` String);

INSERT INTO example_table_aliases (`alias`, `select`, `type`) VALUES
('TimestampNanos', 'TimestampNanos', 'DateTime(9)'), -- Preserva a coluna original da tabela (opcional)
('TimestampDate', 'toDate(TimestampNanos)', 'Date'); -- Adiciona nova coluna que converte TimestampNanos para Date

Podemos então configurar essa tabela para uso no Grafana. Observe que o nome pode ser qualquer um, ou até mesmo ser definido em um banco de dados separado: Agora o Grafana verá os resultados da tabela de aliases em vez dos resultados de DESC example_table: Ambas as formas de alias podem ser usadas para realizar conversões complexas de tipo ou extração de campos JSON.

Todas as opções de YAML

Estas são todas as opções de configuração em YAML disponibilizadas pelo plugin. Alguns campos têm valores de exemplo, enquanto outros apenas mostram o tipo do campo. Consulte a documentação do Grafana para mais informações sobre o provisionamento de fontes de dados com YAML.

datasources:
  - name: Example ClickHouse
    uid: clickhouse-example
    type: grafana-clickhouse-datasource
    jsonData:
      host: 127.0.0.1
      port: 9000
      protocol: native
      secure: false
      username: default
      tlsSkipVerify: <boolean>
      tlsAuth: <boolean>
      tlsAuthWithCACert: <boolean>
      defaultDatabase: default
      defaultTable: <string>
      dialTimeout: 10
      queryTimeout: 60
      validateSql: false
      httpHeaders:
      - name: X-Example-Plain-Header
        value: plain text value
        secure: false
      - name: X-Example-Secure-Header
        secure: true
      logs:
        defaultDatabase: default
        defaultTable: otel_logs
        otelEnabled: false
        otelVersion: latest
        timeColumn: <string>
        levelColumn: <string>
        messageColumn: <string>
      traces:
        defaultDatabase: default
        defaultTable: otel_traces
        otelEnabled: false
        otelVersion: latest
        traceIdColumn: <string>
        spanIdColumn: <string>
        operationNameColumn: <string>
        parentSpanIdColumn: <string>
        serviceNameColumn: <string>
        durationTimeColumn: <string>
        durationUnitColumn: <time unit>
        startTimeColumn: <string>
        tagsColumn: <string>
        serviceTagsColumn: <string>
    secureJsonData:
      tlsCACert:     <string>
      tlsClientCert: <string>
      tlsClientKey:  <string>
      secureHttpHeaders.X-Example-Secure-Header: secure header value

​Configurações comuns

​Protocolo HTTP

​Caminho HTTP

​Cabeçalhos HTTP personalizados

​Configurações adicionais

​OpenTelemetry

​Logs

​Traces

​Aliases de coluna

​Colunas ALIAS definidas na tabela

​Tabelas de aliases de colunas

​Todas as opções de YAML

Configurações comuns

Protocolo HTTP

Caminho HTTP

Cabeçalhos HTTP personalizados

Configurações adicionais

OpenTelemetry

Logs

Traces

Aliases de coluna

Colunas ALIAS definidas na tabela

Tabelas de aliases de colunas

Todas as opções de YAML