Como configurar a fonte de dados ClickHouse no Grafana

Opções de configuração do plugin de 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 # (required) server address.
  port: 9000      # (required) server port. For native, defaults to 9440 secure and 9000 insecure. For HTTP, defaults to 8443 secure and 8123 insecure.

  protocol: native # (required) the protocol used for the connection. Can be set to "native" or "http".
  secure: false    # set to true if the connection is secure.

  username: default # the username used for authentication.

  tlsSkipVerify:     <boolean> # skips TLS verification when set to true.
  tlsAuth:           <boolean> # set to true to enable TLS client authentication.
  tlsAuthWithCACert: <boolean> # set to true if CA certificate is provided. Required for verifying self-signed TLS certificates.

secureJsonData:
  password: secureExamplePassword # the password used for authentication.

  tlsCACert:     <string> # TLS CA certificate
  tlsClientCert: <string> # TLS client certificate
  tlsClientKey:  <string> # TLS client key

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 HTTP

Embora 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 # default database loaded by the query builder. Defaults to "default".
  defaultTable: <string>   # default table loaded by the query builder.

  dialTimeout: 10    # dial timeout when connecting to the server, in seconds. Defaults to "10".
  queryTimeout: 60   # query timeout when running a query, in seconds. Defaults to 60. This requires permissions on the user, if you get a permission error try setting it to "0" to disable it.
  validateSql: false # when set to true, will validate the SQL in the 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 criação 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 data links.

Exemplo de tela de configuração de logs:

Exemplo de YAML de configuração de logs:

jsonData:
  logs:
    defaultDatabase: default # default log database.
    defaultTable: otel_logs  # default log table. If you're using OTel, this should be set to "otel_logs".

    otelEnabled: false  # set to true if OTel is enabled.
    otelVersion: latest # the otel collector schema version to be used. Versions are displayed in the UI, but "latest" will use latest available version in the plugin.

    showLogLinks: true # set to false to hide the "View logs" data links on trace ID fields.

    # Default columns to be selected when opening a new log query. Will be ignored if OTel is enabled.
    timeColumn:       <string> # the primary time column for the log.
    levelColumn:   <string> # the log level/severity of the log. Values typically look like "INFO", "error", or "Debug".
    messageColumn: <string> # the log's message/content.

​

Desativando links “View logs”

A seção Correlação de ID de trace da configuração de logs contém o toggle Mostrar links “View logs”. Esse toggle controla se o plugin anexa links “View logs” de data links aos campos de ID de trace nos resultados das consultas. O toggle é ativado por padrão. Um link “View logs” para o mesmo tipo de consulta não requer padrões de logs configurados; já um link “View logs” entre sinais, proveniente de resultados de consultas de traces, requer. Desative o toggle ou defina showLogLinks: false no YAML para ocultá-los.

​

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  # default trace database.
    defaultTable: otel_traces # default trace table. If you're using OTel, this should be set to "otel_traces".

    otelEnabled: false  # set to true if OTel is enabled.
    otelVersion: latest # the otel collector schema version to be used. Versions are displayed in the UI, but "latest" will use latest available version in the plugin.

    showTraceLinks: true # set to false to hide the "View trace" data links on trace ID fields.

    # Default columns to be selected when opening a new trace query. Will be ignored if OTel is enabled.
    traceIdColumn:       <string>    # trace ID column.
    spanIdColumn:        <string>    # span ID column.
    operationNameColumn: <string>    # operation name column.
    parentSpanIdColumn:  <string>    # parent span ID column.
    serviceNameColumn:   <string>    # service name column.
    durationTimeColumn:  <string>    # duration time column.
    durationUnitColumn:  <time unit> # duration time unit. Can be set to "seconds", "milliseconds", "microseconds", or "nanoseconds". For OTel the default is "nanoseconds".
    startTimeColumn:     <string>    # start time column. This is the primary time column for the trace span.
    tagsColumn:          <string>    # tags column. This is expected to be a map type.
    serviceTagsColumn:   <string>    # service tags column. This is expected to be a map type.

​

Desativar links “View trace”

A seção Correlação de ID de trace da configuração de traces contém o toggle Mostrar links “View trace”. Esse toggle controla se o plugin adiciona links “View trace” de data links aos campos de ID de trace nos resultados de consultas. O toggle vem ativado por padrão. Um link “View trace” para o mesmo tipo de consulta não requer padrões de trace configurados; já um link “View trace” entre sinais, a partir de resultados de consultas de logs, requer. Desative o toggle ou defina showTraceLinks: false em YAML para ocultá-los.

​

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,  -- The name of the alias, as seen in the Grafana column selector
  `select` String, -- The SELECT syntax to use in the SQL generator
  `type` String    -- The type of the resulting column, so the plugin can modify the UI options to match the data type.
)

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)'), -- Preserve original column from table (optional)
('TimestampDate', 'toDate(TimestampNanos)', 'Date'); -- Add new column that converts TimestampNanos to a 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
        showLogLinks: <boolean>
        timeColumn: <string>
        levelColumn: <string>
        messageColumn: <string>
      traces:
        defaultDatabase: default
        defaultTable: otel_traces
        otelEnabled: false
        otelVersion: latest
        showTraceLinks: <boolean>
        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