Configurer la source de données ClickHouse dans Grafana

Options de configuration du plugin de source de données ClickHouse dans Grafana

Le moyen le plus simple de modifier une configuration consiste à passer par l’UI de Grafana, sur la page de configuration du plugin, mais les sources de données peuvent aussi être provisionnées avec un fichier YAML.

Cette page présente la liste des options de configuration disponibles dans le plugin ClickHouse, ainsi que des extraits de configuration pour ceux qui provisionnent une source de données avec YAML.

Pour un aperçu rapide de toutes les options, consultez la liste complète des options de configuration ici.

​

Paramètres communs

Exemple d’écran de configuration :

Exemple de configuration YAML pour les paramètres communs :

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

Notez qu’une propriété version est ajoutée lorsque la configuration est enregistrée via l’UI. Cela indique la version du plugin utilisée lors de l’enregistrement de la configuration.

​

Protocole HTTP

Des paramètres supplémentaires s’afficheront si vous choisissez de vous connecter via le protocole HTTP.

​

Chemin HTTP

Si votre serveur HTTP est exposé sous un chemin d’URL différent, vous pouvez l’indiquer ici.

jsonData:
  # excludes first slash
  path: additional/path/example

​

En-têtes HTTP personnalisés

Vous pouvez ajouter des en-têtes personnalisés aux requêtes envoyées à votre serveur.

Les en-têtes peuvent être en texte brut ou sécurisés. Toutes les clés d’en-tête sont stockées en texte brut, tandis que les valeurs des en-têtes sécurisés sont enregistrées dans la config sécurisée (comme le champ password).

Valeurs sécurisées sur HTTP

Bien que les valeurs des en-têtes sécurisés soient stockées de manière sécurisée dans la config, elles seront tout de même envoyées sur HTTP si la connexion sécurisée est désactivée.

Exemple de YAML pour les en-têtes en texte brut et sécurisés :

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

​

Paramètres supplémentaires

Ces paramètres supplémentaires sont facultatifs.

Exemple 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

OpenTelemetry (OTel) est étroitement intégré au plugin. Les données OpenTelemetry peuvent être exportées vers ClickHouse avec notre plugin exporter. Pour une utilisation optimale, il est recommandé de configurer OTel à la fois pour les logs et les traces.

Il est également nécessaire de configurer ces paramètres par défaut pour activer les liens de données, une fonctionnalité qui permet de mettre en place de puissants workflows d’observabilité.

​

Logs

Pour accélérer la création de requêtes pour les logs, vous pouvez définir une base de données/table par défaut, ainsi que les colonnes de la requête de logs. Cela précharge le query builder avec une requête de logs exécutable, ce qui accélère la navigation dans la page Explore pour l’observabilité.

Si vous utilisez OpenTelemetry, vous devez activer le commutateur “Use OTel” et définir la table de logs par défaut sur otel_logs. Cela remplacera automatiquement les colonnes par défaut afin d’utiliser la version du schéma OTel sélectionnée.

Bien qu’OpenTelemetry ne soit pas requis pour les logs, l’utilisation d’un jeu de données unique pour les logs et les traces permet de rendre le workflow d’observabilité plus fluide grâce aux liens de données.

Exemple d’écran de configuration des logs :

Exemple de YAML de configuration des 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

Pour accélérer la création de requêtes pour les traces, vous pouvez définir une base de données/table par défaut, ainsi que les colonnes de la requête de trace. Le query builder sera alors préchargé avec une requête de recherche de traces exécutable, ce qui accélère la navigation dans la page Explore.

Si vous utilisez OpenTelemetry, vous devez activer l’option “Use OTel” et définir la table de traces par défaut sur otel_traces. Cela remplacera automatiquement les colonnes par défaut pour utiliser la version du schéma OTel sélectionnée. Même si OpenTelemetry n’est pas obligatoire, cette fonctionnalité fonctionne mieux lorsque vous utilisez son schéma pour les traces.

Exemple d’écran de configuration des traces :

Exemple de configuration YAML pour les 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.

​

Alias de colonnes

L’utilisation d’alias de colonnes est un moyen pratique d’interroger vos données sous différents noms et types. Avec les alias, vous pouvez prendre un schéma imbriqué et l’aplatir pour faciliter sa sélection dans Grafana.

Les alias peuvent vous être utiles si :

• Vous connaissez votre schéma et la plupart de ses propriétés et types imbriqués
• Vous stockez vos données dans des types Map
• Vous stockez du JSON sous forme de chaînes de caractères
• Vous appliquez souvent des fonctions pour transformer les colonnes que vous sélectionnez

​

Colonnes ALIAS définies au niveau de la table

ClickHouse prend en charge nativement les alias de colonnes et fonctionne avec Grafana sans configuration supplémentaire. Les colonnes ALIAS peuvent être définies directement dans la table.

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

Dans l’exemple ci-dessus, nous créons un alias appelé TimestampDate qui convertit le timestamp en nanosecondes en type Date. Ces données ne sont pas stockées sur le disque comme la première colonne ; elles sont calculées au moment de la requête. Les alias définis dans la table ne sont pas renvoyés avec SELECT *, mais cela peut être configuré dans les paramètres du serveur.

Pour plus d’informations, consultez la documentation du type de colonne ALIAS.

​

Tables d’alias de colonnes

Par défaut, Grafana propose des suggestions de colonnes à partir de la réponse de DESC table. Dans certains cas, vous pouvez vouloir remplacer complètement les colonnes que Grafana voit. Cela permet de masquer votre schéma dans Grafana lors de la sélection des colonnes, ce qui peut améliorer l’expérience utilisateur selon la complexité de votre table.

L’avantage par rapport aux alias définis au niveau de la table est que vous pouvez les mettre à jour facilement sans avoir à modifier votre table. Dans certains schémas, cela peut représenter des milliers d’entrées, ce qui risque d’encombrer la définition de la table sous-jacente. Cela permet également de masquer les colonnes que vous voulez que l’utilisateur ignore.

Grafana exige que la table d’alias ait la structure de colonnes suivante :

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

Voici comment reproduire le comportement de la colonne ALIAS à l’aide de la table alias :

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

Nous pouvons ensuite configurer cette table pour l’utiliser dans Grafana. Notez que le nom peut être quelconque, ou même défini dans une base de données distincte :

Grafana verra alors les résultats de la table d’alias au lieu de ceux de DESC example_table :

Les deux types d’alias peuvent être utilisés pour effectuer des conversions de types complexes ou extraire des champs JSON.

​

Toutes les options YAML

Voici toutes les options de configuration YAML proposées par le plugin. Certains champs comportent des valeurs d’exemple, tandis que d’autres indiquent simplement le type du champ.

Consultez la documentation Grafana pour plus d’informations sur le provisionnement des sources de données avec 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