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

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

ClickHouse Supported

Проще всего изменять конфигурацию в интерфейсе 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> # пропускает проверку TLS, если установлено значение true.
  tlsAuth:           <boolean> # установите значение true для включения клиентской аутентификации TLS.
  tlsAuthWithCACert: <boolean> # установите значение true, если предоставлен сертификат CA. Требуется для проверки самоподписанных сертификатов TLS.

secureJsonData:
  password: secureExamplePassword # пароль, используемый для аутентификации.

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

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

Протокол HTTP​

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

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

HTTP path​

Если ваш 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: значение защищенного заголовка

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

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

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

Пример 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 как для журналов, так и для трассировок.

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

Логи​

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

Если вы используете OpenTelemetry, включите переключатель «Use OTel» и задайте default log table со значением 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" и задать default trace table равным otel_traces. Это автоматически изменит столбцы по умолчанию так, чтобы использовать выбранную версию схемы OTel. Хотя OpenTelemetry не является обязательным, эта функция работает лучше всего при использовании его схемы для трейсов.

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

Traces config

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

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

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

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

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

Использование псевдонимов столбцов — удобный способ выполнять запросы к данным под другими именами и с другими типами. С их помощью вы можете преобразовать вложенную схему данных в плоскую структуру, чтобы упростить выборку в 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,  -- Имя псевдонима, отображаемое в селекторе столбцов 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, доступные в этом плагине. Для некоторых полей приведены примеры значений, для других указаны только их типы.

См. документацию 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