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

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

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

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

jsonData:
  host: 127.0.0.1 # (обязательно) адрес сервера.
  port: 9000      # (обязательно) порт сервера. Для native: по умолчанию 9440 (защищённый) и 9000 (незащищённый). Для HTTP: по умолчанию 8443 (защищённый) и 8123 (незащищённый).

  protocol: native # (обязательно) протокол для подключения. Допустимые значения: "native" или "http".
  secure: false    # установите true, если подключение защищённое.

  username: default # имя пользователя для аутентификации.

  tlsSkipVerify:     <boolean> # при значении true пропускает проверку TLS.
  tlsAuth:           <boolean> # установите true для включения TLS-аутентификации клиента.
  tlsAuthWithCACert: <boolean> # установите true, если предоставлен CA‑сертификат. Обязательно для проверки самоподписанных TLS-сертификатов.

secureJsonData:
  password: secureExamplePassword # пароль для аутентификации.

  tlsCACert:     <string> # TLS CA‑сертификат
  tlsClientCert: <string> # TLS-сертификат клиента
  tlsClientKey:  <string> # TLS-ключ клиента

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

HTTP-протокол

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

HTTP-путь

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

jsonData:
  # без первого слэша
  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" исключено
    secure: true
secureJsonData:
  secureHttpHeaders.X-Example-Secure-Header: secure header value

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

Эти настройки необязательны. Пример YAML:

jsonData:
  defaultDatabase: default # база данных по умолчанию, загружаемая конструктором запросов. По умолчанию: "default".
  defaultTable: <string>   # таблица по умолчанию, загружаемая конструктором запросов.

  dialTimeout: 10    # тайм-аут подключения к серверу, в секундах. По умолчанию: "10".
  queryTimeout: 60   # тайм-аут запроса при выполнении, в секундах. По умолчанию: 60. Требует наличия разрешений у пользователя; если возникает ошибка доступа, установите значение "0" для отключения.
  validateSql: false # если установлено значение true, выполняется проверка SQL в редакторе SQL.

OpenTelemetry

OpenTelemetry (OTel) тесно интегрирован в плагин. Данные OpenTelemetry можно экспортировать в ClickHouse с помощью нашего плагина-экспортёра. Для оптимальной работы рекомендуется настроить OTel и для журналов, и для трассировок. Также необходимо настроить эти значения по умолчанию, чтобы включить ссылки на данные — функцию, которая обеспечивает мощные сценарии обсервабилити.

Журналы

Чтобы ускорить построение запросов к журналам, можно задать базу данных и таблицу по умолчанию, а также столбцы для запроса к журналам. Это позволит заранее загрузить в конструктор запросов готовый к выполнению запрос к журналам, что ускорит просмотр на странице Explore в сценариях обсервабилити. Если вы используете OpenTelemetry, включите переключатель “Use OTel” и задайте таблицу журналов по умолчанию — otel_logs. Это автоматически заменит столбцы по умолчанию в соответствии с выбранной версией схемы OTel. Хотя OpenTelemetry не обязателен для журналов, использование единого набора данных для журналов и трассировки помогает выстроить более удобный процесс обсервабилити с связыванием данных. Пример экрана конфигурации журналов: Пример YAML-конфигурации журналов:

jsonData:
  logs:
    defaultDatabase: default # база данных журналов по умолчанию.
    defaultTable: otel_logs  # таблица журналов по умолчанию. При использовании OTel укажите значение "otel_logs".

    otelEnabled: false  # установите true, если OTel включён.
    otelVersion: latest # версия схемы OTel collector. Версии отображаются в интерфейсе; значение "latest" соответствует последней доступной версии в плагине.

    # Столбцы по умолчанию для нового запроса журналов. Игнорируется, если OTel включён.
    timeColumn:       <string> # основной столбец времени для журнала.
    levelColumn:   <string> # уровень/критичность записи журнала. Типичные значения: "INFO", "error" или "Debug".
    messageColumn: <string> # сообщение/содержимое записи журнала.

Трассировка

Чтобы ускорить построение запросов для трассировки, можно задать базу данных и таблицу по умолчанию, а также столбцы для запроса трассировки. Это позволит заранее загрузить в конструктор запросов готовый к выполнению поисковый запрос по трассировке, что ускорит просмотр данных на странице Explore для задач обсервабилити. Если вы используете OpenTelemetry, следует включить переключатель “Use OTel” и задать таблицу трассировки по умолчанию otel_traces. Это автоматически заменит столбцы по умолчанию в соответствии с выбранной версией схемы OTel. Хотя OpenTelemetry не обязателен, эта возможность лучше всего работает при использовании его схемы для трассировки. Пример экрана конфигурации трассировки: Пример YAML-конфигурации трассировки:

jsonData:
  traces:
    defaultDatabase: default  # база данных трассировки по умолчанию.
    defaultTable: otel_traces # таблица трассировки по умолчанию. Если используется OTel, должно быть установлено значение "otel_traces".

    otelEnabled: false  # установите true, если OTel включён.
    otelVersion: latest # версия схемы OTel collector для использования. Версии отображаются в интерфейсе, но "latest" будет использовать последнюю доступную версию в плагине.

    # Столбцы по умолчанию, выбираемые при открытии нового запроса трассировки. Игнорируется, если OTel включён.
    traceIdColumn:       <string>    # столбец trace ID.
    spanIdColumn:        <string>    # столбец span ID.
    operationNameColumn: <string>    # столбец имени операции.
    parentSpanIdColumn:  <string>    # столбец ID родительского спана.
    serviceNameColumn:   <string>    # столбец имени сервиса.
    durationTimeColumn:  <string>    # столбец длительности.
    durationUnitColumn:  <time unit> # единица измерения длительности. Допустимые значения: "seconds", "milliseconds", "microseconds" или "nanoseconds". Для OTel по умолчанию используется "nanoseconds".
    startTimeColumn:     <string>    # столбец времени начала. Это основной столбец времени для спана трассировки.
    tagsColumn:          <string>    # столбец тегов. Ожидается тип map.
    serviceTagsColumn:   <string>    # столбец тегов сервиса. Ожидается тип map.

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

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

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

ALIAS-столбцы, заданные в таблице

ClickHouse изначально поддерживает псевдонимы столбцов и сразу работает с Grafana. ALIAS-столбцы можно задавать прямо в таблице.

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,  -- Имя псевдонима, отображаемое в селекторе столбцов Grafana
  `select` String, -- Синтаксис SELECT для использования в генераторе SQL
  `type` String    -- Тип результирующего столбца, позволяющий плагину адаптировать параметры интерфейса под тип данных.
)

Вот как можно воспроизвести поведение столбца 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)'), -- Сохранить исходный столбец из таблицы (необязательно)
('TimestampDate', 'toDate(TimestampNanos)', 'Date'); -- Добавить новый столбец, преобразующий TimestampNanos в Date

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

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

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

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

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

​HTTP-протокол

​HTTP-путь

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

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

​OpenTelemetry

​Журналы

​Трассировка

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

​ALIAS-столбцы, заданные в таблице

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

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

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

HTTP-протокол

HTTP-путь

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

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

OpenTelemetry

Журналы

Трассировка

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

ALIAS-столбцы, заданные в таблице

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

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