> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-detect-table-modification.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Opções de configuração do plugin de fonte de dados ClickHouse no Grafana

# Como configurar a fonte de dados ClickHouse no Grafana

export const ClickHouseSupportedBadge = () => {
  return <div className="ClickHouseSupportedBadge">
            <div className="ClickHouseSupportedIcon">
                <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                    <path d="M1.30762 1.39073C1.30762 1.3103 1.37465 1.22986 1.46849 1.22986H2.64824C2.72868 1.22986 2.80912 1.29689 2.80912 1.39073V14.4886C2.80912 14.5691 2.74209 14.6495 2.64824 14.6495H1.46849C1.38805 14.6495 1.30762 14.5825 1.30762 14.4886V1.39073Z" fill="currentColor" />
                    <path d="M4.2832 1.39073C4.2832 1.3103 4.35023 1.22986 4.44408 1.22986H5.62383C5.70427 1.22986 5.7847 1.29689 5.7847 1.39073V14.4886C5.7847 14.5691 5.71767 14.6495 5.62383 14.6495H4.44408C4.36364 14.6495 4.2832 14.5825 4.2832 14.4886V1.39073Z" fill="currentColor" />
                    <path d="M7.25977 1.39073C7.25977 1.3103 7.3268 1.22986 7.42064 1.22986H8.60039C8.68083 1.22986 8.76127 1.29689 8.76127 1.39073V14.4886C8.76127 14.5691 8.69423 14.6495 8.60039 14.6495H7.42064C7.3402 14.6495 7.25977 14.5825 7.25977 14.4886V1.39073Z" fill="currentColor" />
                    <path d="M10.2354 1.39073C10.2354 1.3103 10.3024 1.22986 10.3962 1.22986H11.576C11.6564 1.22986 11.7369 1.29689 11.7369 1.39073V14.4886C11.7369 14.5691 11.6698 14.6495 11.576 14.6495H10.3962C10.3158 14.6495 10.2354 14.5825 10.2354 14.4886V1.39073Z" fill="currentColor" />
                    <path d="M13.2256 6.6057C13.2256 6.52526 13.2926 6.44482 13.3865 6.44482H14.5662C14.6466 6.44482 14.7271 6.51186 14.7271 6.6057V9.27354C14.7271 9.35398 14.6601 9.43442 14.5662 9.43442H13.3865C13.306 9.43442 13.2256 9.36739 13.2256 9.27354V6.6057Z" fill="currentColor" />
                </svg>
            </div>
            Suportado pelo ClickHouse
        </div>;
};

export const Image = ({img, alt, size = "lg"}) => {
  const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
  return <div className={`ch-image-${normalizedSize}`}>
      <Frame>
        <img src={img} alt={alt} />
      </Frame>
    </div>;
};

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](https://grafana.com/docs/grafana/latest/administration/provisioning/#data-sources).

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](#all-yaml-options) a lista completa de opções de configuração.

<div id="common-settings">
  ## Configurações comuns
</div>

Exemplo de tela de configuração:

<Image size="sm" img="https://mintcdn.com/private-7c7dfe99-detect-table-modification/L7_COrR7NltKl_Va/images/integrations/data-visualization/grafana/config_common.webp?fit=max&auto=format&n=L7_COrR7NltKl_Va&q=85&s=bc841b182170ad7ae9a207c36720eef7" alt="Exemplo de configuração nativa segura" border width="601" height="813" data-path="images/integrations/data-visualization/grafana/config_common.webp" />

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

```yaml theme={null}
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.

<div id="http-protocol">
  ### Protocolo HTTP
</div>

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

<Image size="md" img="https://mintcdn.com/private-7c7dfe99-detect-table-modification/L7_COrR7NltKl_Va/images/integrations/data-visualization/grafana/config_http.webp?fit=max&auto=format&n=L7_COrR7NltKl_Va&q=85&s=7d758cb8cb1be634bd6ff4a6dc6677fb" alt="Opções extras de configuração de HTTP" border width="975" height="442" data-path="images/integrations/data-visualization/grafana/config_http.webp" />

<div id="http-path">
  #### Caminho HTTP
</div>

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

```yaml theme={null}
jsonData:
  # exclui a primeira barra
  path: additional/path/example
```

<div id="custom-http-headers">
  #### Cabeçalhos HTTP personalizados
</div>

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`).

<Warning>
  **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.
</Warning>

Exemplo de YAML para cabeçalhos simples/seguros:

```yaml theme={null}
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
```

<div id="additional-settings">
  ## Configurações adicionais
</div>

Estas configurações adicionais são opcionais.

<Image size="sm" img="https://mintcdn.com/private-7c7dfe99-detect-table-modification/L7_COrR7NltKl_Va/images/integrations/data-visualization/grafana/config_additional.webp?fit=max&auto=format&n=L7_COrR7NltKl_Va&q=85&s=ad12cd6ffc5b03f9b3bc8344a89d50bb" alt="Exemplo de configurações adicionais" border width="406" height="452" data-path="images/integrations/data-visualization/grafana/config_additional.webp" />

Exemplo em YAML:

```yaml theme={null}
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.
```

<div id="opentelemetry">
  ### OpenTelemetry
</div>

O OpenTelemetry (OTel) é fortemente integrado ao plugin.
Os dados do OpenTelemetry podem ser exportados para o ClickHouse com nosso [plugin exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/clickhouseexporter).
Para obter o melhor uso, recomenda-se configurar o OTel tanto para [logs](#logs) quanto para [traces](#traces).

Também é necessário configurar esses padrões para habilitar [data links](/pt-BR/integrations/connectors/data-visualization/grafana/query-builder#data-links), um recurso que permite fluxos de trabalho avançados de observabilidade.

<div id="logs">
  ### Logs
</div>

Para acelerar a [montagem de consultas de logs](/pt-BR/integrations/connectors/data-visualization/grafana/query-builder#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](/pt-BR/integrations/connectors/data-visualization/grafana/query-builder#data-links).

Exemplo de tela de configuração de logs:

<Image size="sm" img="https://mintcdn.com/private-7c7dfe99-detect-table-modification/L7_COrR7NltKl_Va/images/integrations/data-visualization/grafana/config_logs.webp?fit=max&auto=format&n=L7_COrR7NltKl_Va&q=85&s=6ed942710a1005a257e6fa88bd1c1d9a" alt="Configuração de logs" border width="460" height="402" data-path="images/integrations/data-visualization/grafana/config_logs.webp" />

Exemplo de YAML de configuração de logs:

```yaml theme={null}
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.
```

<div id="traces">
  ### Traces
</div>

Para acelerar a [criação de consultas para traces](/pt-BR/integrations/connectors/data-visualization/grafana/query-builder#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:

<Image size="sm" img="https://mintcdn.com/private-7c7dfe99-detect-table-modification/L7_COrR7NltKl_Va/images/integrations/data-visualization/grafana/config_traces.webp?fit=max&auto=format&n=L7_COrR7NltKl_Va&q=85&s=39ef2cd877faeae72d09482c43be3531" alt="Configuração de traces" border width="476" height="625" data-path="images/integrations/data-visualization/grafana/config_traces.webp" />

Exemplo de YAML de configuração de traces:

```yaml theme={null}
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.
```

<div id="column-aliases">
  ### Aliases de coluna
</div>

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

<div id="table-defined-alias-columns">
  #### Colunas ALIAS definidas na tabela
</div>

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.

```sql theme={null}
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](/pt-BR/reference/statements/create/table#alias).

<div id="column-alias-tables">
  #### Tabelas de aliases de colunas
</div>

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:

```sql theme={null}
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:

```sql theme={null}
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:

<Image size="md" img="https://mintcdn.com/private-7c7dfe99-detect-table-modification/L7_COrR7NltKl_Va/images/integrations/data-visualization/grafana/alias_table_config_example.webp?fit=max&auto=format&n=L7_COrR7NltKl_Va&q=85&s=e9a4000a57875b11b72ae8faee1e13b7" alt="Exemplo de configuração de tabela de aliases" border width="974" height="199" data-path="images/integrations/data-visualization/grafana/alias_table_config_example.webp" />

Agora o Grafana verá os resultados da tabela de aliases em vez dos resultados de `DESC example_table`:

<Image size="md" img="https://mintcdn.com/private-7c7dfe99-detect-table-modification/L7_COrR7NltKl_Va/images/integrations/data-visualization/grafana/alias_table_select_example.webp?fit=max&auto=format&n=L7_COrR7NltKl_Va&q=85&s=d2898e15a9cbfe301017aa0ca36da6c9" alt="Exemplo de seleção de tabela de aliases" border width="508" height="188" data-path="images/integrations/data-visualization/grafana/alias_table_select_example.webp" />

Ambas as formas de alias podem ser usadas para realizar conversões complexas de tipo ou extração de campos JSON.

<div id="all-yaml-options">
  ## Todas as opções de YAML
</div>

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](https://grafana.com/docs/grafana/latest/administration/provisioning/#data-sources) para mais informações sobre o provisionamento de fontes de dados com YAML.

```yaml theme={null}
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
```