> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-fbfa8bee.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Параметры конфигурации плагина источника данных ClickHouse для Grafana

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

export const ClickHouseSupportedBadge = () => {
  return <div className="ClickHouseSupportedBadge">
            <div className="ClickHouseSupportedIcon">
                <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                    <path d="M1.30762 1.39073C1.30762 1.3103 1.37465 1.22986 1.46849 1.22986H2.64824C2.72868 1.22986 2.80912 1.29689 2.80912 1.39073V14.4886C2.80912 14.5691 2.74209 14.6495 2.64824 14.6495H1.46849C1.38805 14.6495 1.30762 14.5825 1.30762 14.4886V1.39073Z" fill="currentColor" />
                    <path d="M4.2832 1.39073C4.2832 1.3103 4.35023 1.22986 4.44408 1.22986H5.62383C5.70427 1.22986 5.7847 1.29689 5.7847 1.39073V14.4886C5.7847 14.5691 5.71767 14.6495 5.62383 14.6495H4.44408C4.36364 14.6495 4.2832 14.5825 4.2832 14.4886V1.39073Z" fill="currentColor" />
                    <path d="M7.25977 1.39073C7.25977 1.3103 7.3268 1.22986 7.42064 1.22986H8.60039C8.68083 1.22986 8.76127 1.29689 8.76127 1.39073V14.4886C8.76127 14.5691 8.69423 14.6495 8.60039 14.6495H7.42064C7.3402 14.6495 7.25977 14.5825 7.25977 14.4886V1.39073Z" fill="currentColor" />
                    <path d="M10.2354 1.39073C10.2354 1.3103 10.3024 1.22986 10.3962 1.22986H11.576C11.6564 1.22986 11.7369 1.29689 11.7369 1.39073V14.4886C11.7369 14.5691 11.6698 14.6495 11.576 14.6495H10.3962C10.3158 14.6495 10.2354 14.5825 10.2354 14.4886V1.39073Z" fill="currentColor" />
                    <path d="M13.2256 6.6057C13.2256 6.52526 13.2926 6.44482 13.3865 6.44482H14.5662C14.6466 6.44482 14.7271 6.51186 14.7271 6.6057V9.27354C14.7271 9.35398 14.6601 9.43442 14.5662 9.43442H13.3865C13.306 9.43442 13.2256 9.36739 13.2256 9.27354V6.6057Z" fill="currentColor" />
                </svg>
            </div>
            Поддерживается в ClickHouse
        </div>;
};

export const Image = ({img, alt, size}) => {
  return <Frame>
      <img src={img} alt={alt} />
    </Frame>;
};

Проще всего изменить конфигурацию в интерфейсе Grafana на странице конфигурации плагина, но источники данных также можно [настроить с помощью YAML-файла](https://grafana.com/docs/grafana/latest/administration/provisioning/#data-sources).

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

Краткий обзор всех параметров и полный список опций конфигурации можно найти [здесь](#all-yaml-options).

<div id="common-settings">
  ## Общие настройки
</div>

Экран с примером конфигурации:

<Image size="sm" img="https://mintcdn.com/private-7c7dfe99-mintlify-fbfa8bee/5u7Mhe0xzzPTUaXM/images/integrations/data-visualization/grafana/config_common.png?fit=max&auto=format&n=5u7Mhe0xzzPTUaXM&q=85&s=dfae6b92d49c6cd916fe6161ea16d1fb" alt="Пример безопасной конфигурации для native-протокола" border width="601" height="813" data-path="images/integrations/data-visualization/grafana/config_common.png" />

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

```yaml theme={null}
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`. Оно показывает версию плагина, с которой была сохранена конфигурация.

<div id="http-protocol">
  ### HTTP-протокол
</div>

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

<Image size="md" img="https://mintcdn.com/private-7c7dfe99-mintlify-fbfa8bee/5u7Mhe0xzzPTUaXM/images/integrations/data-visualization/grafana/config_http.png?fit=max&auto=format&n=5u7Mhe0xzzPTUaXM&q=85&s=0cc676ef3d86e535680d5184ec32b8e7" alt="Дополнительные параметры конфигурации HTTP" border width="975" height="442" data-path="images/integrations/data-visualization/grafana/config_http.png" />

<div id="http-path">
  #### HTTP-путь
</div>

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

```yaml theme={null}
jsonData:
  # без первого слэша
  path: additional/path/example
```

<div id="custom-http-headers">
  #### Пользовательские HTTP-заголовки
</div>

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

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

<Warning>
  **Защищённые значения по HTTP**

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

Пример YAML для обычных и защищённых заголовков:

```yaml theme={null}
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
```

<div id="additional-settings">
  ## Дополнительные настройки
</div>

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

<Image size="sm" img="https://mintcdn.com/private-7c7dfe99-mintlify-fbfa8bee/5u7Mhe0xzzPTUaXM/images/integrations/data-visualization/grafana/config_additional.png?fit=max&auto=format&n=5u7Mhe0xzzPTUaXM&q=85&s=d723ada17d48e6a820db134e7b85c967" alt="Пример дополнительных настроек" border width="406" height="452" data-path="images/integrations/data-visualization/grafana/config_additional.png" />

Пример YAML:

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

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

<div id="opentelemetry">
  ### OpenTelemetry
</div>

OpenTelemetry (OTel) тесно интегрирован в плагин.
Данные OpenTelemetry можно экспортировать в ClickHouse с помощью нашего [плагина-экспортёра](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/clickhouseexporter).
Для оптимальной работы рекомендуется настроить OTel и для [журналов](#logs), и для [трассировок](#traces).

Также необходимо настроить эти значения по умолчанию, чтобы включить [ссылки на данные](/ru/integrations/connectors/data-visualization/grafana/query-builder#data-links) — функцию, которая обеспечивает мощные сценарии обсервабилити.

<div id="logs">
  ### Журналы
</div>

Чтобы ускорить [построение запросов к журналам](/ru/integrations/connectors/data-visualization/grafana/query-builder#logs), можно задать базу данных и таблицу по умолчанию, а также столбцы для запроса к журналам. Это позволит заранее загрузить в конструктор запросов готовый к выполнению запрос к журналам, что ускорит просмотр на странице Explore в сценариях обсервабилити.

Если вы используете OpenTelemetry, включите переключатель "**Use OTel**" и задайте **таблицу журналов по умолчанию** — `otel_logs`.
Это автоматически заменит столбцы по умолчанию в соответствии с выбранной версией схемы OTel.

Хотя OpenTelemetry не обязателен для журналов, использование единого набора данных для журналов и трассировки помогает выстроить более удобный процесс обсервабилити с [связыванием данных](/ru/integrations/connectors/data-visualization/grafana/query-builder#data-links).

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

<Image size="sm" img="https://mintcdn.com/private-7c7dfe99-mintlify-fbfa8bee/5u7Mhe0xzzPTUaXM/images/integrations/data-visualization/grafana/config_logs.png?fit=max&auto=format&n=5u7Mhe0xzzPTUaXM&q=85&s=a759966f4aab7737c3cce33fab5b759d" alt="Конфигурация журналов" border width="460" height="402" data-path="images/integrations/data-visualization/grafana/config_logs.png" />

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

```yaml theme={null}
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> # сообщение/содержимое записи журнала.
```

<div id="traces">
  ### Трассировка
</div>

Чтобы ускорить [построение запросов для трассировки](/ru/integrations/connectors/data-visualization/grafana/query-builder#traces), можно задать базу данных и таблицу по умолчанию, а также столбцы для запроса трассировки. Это позволит заранее загрузить в конструктор запросов готовый к выполнению поисковый запрос по трассировке, что ускорит просмотр данных на странице Explore для задач обсервабилити.

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

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

<Image size="sm" img="https://mintcdn.com/private-7c7dfe99-mintlify-fbfa8bee/5u7Mhe0xzzPTUaXM/images/integrations/data-visualization/grafana/config_traces.png?fit=max&auto=format&n=5u7Mhe0xzzPTUaXM&q=85&s=71244fe327d415a84e6c9c8474ee890f" alt="Конфигурация трассировки" border width="476" height="625" data-path="images/integrations/data-visualization/grafana/config_traces.png" />

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

```yaml theme={null}
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.
```

<div id="column-aliases">
  ### Псевдонимы столбцов
</div>

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

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

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

<div id="table-defined-alias-columns">
  #### ALIAS-столбцы, заданные в таблице
</div>

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

```sql theme={null}
CREATE TABLE alias_example (
  TimestampNanos DateTime(9),
  TimestampDate ALIAS toDate(TimestampNanos)
)
```

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

Подробнее см. в документации по типу столбца [ALIAS](/ru/reference/statements/create/table#alias).

<div id="column-alias-tables">
  #### Таблицы псевдонимов столбцов
</div>

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

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

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

```sql theme={null}
CREATE TABLE aliases (
  `alias` String,  -- Имя псевдонима, отображаемое в селекторе столбцов Grafana
  `select` String, -- Синтаксис SELECT для использования в генераторе SQL
  `type` String    -- Тип результирующего столбца, позволяющий плагину адаптировать параметры интерфейса под тип данных.
)
```

Вот как можно воспроизвести поведение столбца `ALIAS` с помощью таблицы псевдонимов:

```sql theme={null}
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. Обратите внимание, что имя может быть любым и даже может быть задано в отдельной базе данных:

<Image size="md" img="https://mintcdn.com/private-7c7dfe99-mintlify-fbfa8bee/5u7Mhe0xzzPTUaXM/images/integrations/data-visualization/grafana/alias_table_config_example.png?fit=max&auto=format&n=5u7Mhe0xzzPTUaXM&q=85&s=b7f5ae57446a4e41fad0ece7dc3939e4" alt="Пример конфигурации таблицы псевдонимов" border width="974" height="199" data-path="images/integrations/data-visualization/grafana/alias_table_config_example.png" />

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

<Image size="md" img="https://mintcdn.com/private-7c7dfe99-mintlify-fbfa8bee/5u7Mhe0xzzPTUaXM/images/integrations/data-visualization/grafana/alias_table_select_example.png?fit=max&auto=format&n=5u7Mhe0xzzPTUaXM&q=85&s=16ff75e82a2987253ef2a4008f29fef8" alt="Пример выборки из таблицы псевдонимов" border width="508" height="188" data-path="images/integrations/data-visualization/grafana/alias_table_select_example.png" />

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

<div id="all-yaml-options">
  ## Все параметры YAML
</div>

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

Дополнительные сведения о настройке источников данных с помощью YAML см. в [документации Grafana](https://grafana.com/docs/grafana/latest/administration/provisioning/#data-sources).

```yaml theme={null}
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
```