> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/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>;
};

<ClickHouseSupportedBadge />

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/PWQnWTwcu17exYX2/images/integrations/data-visualization/grafana/config_common.webp?fit=max&auto=format&n=PWQnWTwcu17exYX2&q=85&s=ef8007c65279bb9df23fb52a0c6361d7" 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 # (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.

<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/PWQnWTwcu17exYX2/images/integrations/data-visualization/grafana/config_http.webp?fit=max&auto=format&n=PWQnWTwcu17exYX2&q=85&s=173a06bd7c26a19b181299cbf4e60f59" 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/PWQnWTwcu17exYX2/images/integrations/data-visualization/grafana/config_additional.webp?fit=max&auto=format&n=PWQnWTwcu17exYX2&q=85&s=335542c340901788318c16cd8625b5c3" 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 # 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.
```

<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](/docs/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](/docs/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 [data links](/docs/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/PWQnWTwcu17exYX2/images/integrations/data-visualization/grafana/config_logs.webp?fit=max&auto=format&n=PWQnWTwcu17exYX2&q=85&s=657c4d40f4f9875dc6c33ff8a538ed51" 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 # 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.

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

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

Para acelerar a [criação de consultas para traces](/docs/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/PWQnWTwcu17exYX2/images/integrations/data-visualization/grafana/config_traces.webp?fit=max&auto=format&n=PWQnWTwcu17exYX2&q=85&s=08216481b97764c5ffd49b94716ea0aa" 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  # 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.

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

<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](/docs/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,  -- 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:

```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)'), -- 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:

<Image size="md" img="https://mintcdn.com/private-7c7dfe99/PWQnWTwcu17exYX2/images/integrations/data-visualization/grafana/alias_table_config_example.webp?fit=max&auto=format&n=PWQnWTwcu17exYX2&q=85&s=0b8151e07c947f2afba1a4f91b86086b" 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/PWQnWTwcu17exYX2/images/integrations/data-visualization/grafana/alias_table_select_example.webp?fit=max&auto=format&n=PWQnWTwcu17exYX2&q=85&s=e04230ca34881112baab14f67b8ec663" 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
```