Перейти к основному содержанию
Перейти к основному содержанию

Настройка источника данных ClickHouse в Grafana

ClickHouse Supported

Проще всего изменять конфигурацию в интерфейсе Grafana на странице настройки плагина, но источники данных также могут создаваться и настраиваться с помощью YAML‑файла.

На этой странице приведён список параметров, доступных для настройки в плагине ClickHouse, а также примеры конфигурации для тех, кто настраивает источник данных с помощью YAML.

Для быстрого ознакомления со всеми параметрами полный список параметров конфигурации можно найти здесь.

Общие настройки​

Пример экрана конфигурации:

Пример защищённой нативной конфигурации

Пример конфигурации YAML для общих настроек:

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

Обратите внимание, что свойство version добавляется, когда конфигурация сохраняется через пользовательский интерфейс. Оно показывает версию плагина, в которой была сохранена конфигурация.

Протокол HTTP​

Если вы выберете подключение по протоколу HTTP, появятся дополнительные настройки.

Дополнительные параметры настройки HTTP

HTTP path​

Если ваш HTTP-сервер доступен по другому URL-пути, вы можете указать его здесь.

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

Пользовательские HTTP-заголовки​

Вы можете добавлять пользовательские заголовки к запросам, отправляемым на ваш сервер.

Заголовки могут быть как открытыми, так и защищёнными. Все имена заголовков хранятся в открытом виде, а значения защищённых заголовков сохраняются в защищённой конфигурации (аналогично полю password).

Передача защищённых значений по HTTP

Хотя значения защищённых заголовков хранятся в конфигурации безопасно, при отключённом защищённом соединении они всё равно будут передаваться по HTTP.

Пример YAML с открытыми и защищёнными заголовками:

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

Дополнительные настройки​

Эти дополнительные настройки не являются обязательными.

Пример дополнительных настроек

Пример 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) глубоко интегрирован в плагин. Данные OpenTelemetry могут экспортироваться в ClickHouse с помощью нашего плагина-экспортера. Для оптимального использования рекомендуется настроить OTel как для журналов, так и для трассировок.

Также необходимо настроить эти параметры по умолчанию, чтобы включить data links — функцию, которая обеспечивает мощные сценарии наблюдаемости.

Логи​

Чтобы ускорить построение запросов для логов, вы можете задать базу данных/таблицу и столбцы по умолчанию для запроса по логам. Это предварительно заполнит конструктор запросов готовым к выполнению запросом по логам, что ускорит работу на странице Explore при решении задач наблюдаемости.

Если вы используете OpenTelemetry, включите переключатель «Use OTel» и задайте default log table со значением otel_logs. Это автоматически изменит столбцы по умолчанию в соответствии с выбранной версией схемы OTel.

Хотя использование OpenTelemetry для логов не является обязательным, единый набор данных для логов и трассировок помогает обеспечить более плавный рабочий процесс наблюдаемости со связыванием данных.

Пример экрана конфигурации логов:

Конфигурация логов

Пример конфигурации логов в YAML:

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.

Трейсы​

Чтобы ускорить создание запросов для трейсов, вы можете задать базу данных/таблицу по умолчанию, а также столбцы для запроса по трейсам. Это предварительно заполнит конструктор запросов исполняемым запросом поиска по трейсам, что делает работу на странице Explore быстрее для задач наблюдаемости.

Если вы используете OpenTelemetry, следует включить переключатель "Use OTel" и задать default trace table равным otel_traces. Это автоматически изменит столбцы по умолчанию так, чтобы использовать выбранную версию схемы OTel. Хотя OpenTelemetry не является обязательным, эта функция работает лучше всего при использовании его схемы для трейсов.

Пример экрана настройки трейсов:

Traces config

Пример конфигурации трейсов в YAML:

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.

Псевдонимы столбцов​

Использование псевдонимов столбцов — удобный способ выполнять запросы к данным под другими именами и с другими типами. С их помощью вы можете преобразовать вложенную схему данных в плоскую структуру, чтобы упростить выборку в Grafana.

Псевдонимы столбцов могут быть полезны, если:

  • Вы хорошо знаете свою схему данных и большинство её вложенных свойств/типов
  • Вы храните данные в типе Map
  • Вы храните JSON в виде строк
  • Вы часто применяете функции для преобразования выбираемых столбцов

Столбцы-алиасы, определённые в таблице​

В ClickHouse встроена поддержка алиасов столбцов, и он «из коробки» работает с Grafana. Алиасы столбцов можно определять прямо в таблице.

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

В приведённом выше примере мы создаём псевдоним TimestampDate, который преобразует метку времени в наносекундах в значение типа Date. Эти данные не хранятся на диске, как данные в первом столбце, а вычисляются во время выполнения запроса. Псевдонимы, определённые на уровне таблицы, не возвращаются при SELECT *, но это поведение можно настроить в параметрах сервера.

Для получения дополнительной информации см. документацию по типу столбца ALIAS.

Таблицы с псевдонимами столбцов​

По умолчанию Grafana подсказывает столбцы на основе ответа DESC table. В некоторых случаях может потребоваться полностью переопределить столбцы, которые видит Grafana. Это помогает скрыть схему в Grafana при выборе столбцов, что может улучшить удобство работы в зависимости от сложности вашей таблицы.

Преимущество этого подхода по сравнению с псевдонимами, определёнными в таблице, состоит в том, что вы можете легко обновлять их без изменения самой таблицы. В некоторых схемах такой список может содержать тысячи элементов, что захламляет определение базовой таблицы. Этот подход также позволяет скрывать столбцы, которые вы не хотите показывать пользователю.

Grafana требует, чтобы таблица псевдонимов имела следующую структуру столбцов:

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

Вот как можно воспроизвести поведение столбца 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

Затем мы можем настроить эту таблицу для использования в Grafana. Обратите внимание, что имя может быть любым, его можно даже задать в отдельной базе данных:

Пример конфигурации таблицы-псевдонима

Теперь Grafana будет видеть результаты таблицы-псевдонима вместо результатов DESC example_table:

Пример запроса к таблице-псевдониму

Оба варианта псевдонимов можно использовать для выполнения сложных преобразований типов или извлечения полей из JSON.

Все параметры YAML​

Ниже перечислены все параметры конфигурации YAML, доступные в этом плагине. Для некоторых полей приведены примеры значений, для других указаны только их типы.

См. документацию Grafana для получения дополнительной информации об автоматическом создании (provisioning) источников данных с помощью 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