Set up docs MCPA 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 keyObserve 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/exampleCabeç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).
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 valueConfiguraçõ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 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 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.
# 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.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.
# 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.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 DatePodemos 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