@@ -5,52 +5,32 @@ toc_title: OpenTelemetry Support
# [experimental] OpenTelemetry Support
[OpenTelemetry](https://opentelemetry.io/) is an open standard for collecting
traces and metrics from distributed application. ClickHouse has some support
for OpenTelemetry.
[OpenTelemetry](https://opentelemetry.io/) is an open standard for collecting traces and metrics from the distributed application. ClickHouse has some support for `OpenTelemetry`.
!!! warning "Warning"
This is an experimental feature that will change in backwards-incompatible ways in the future releases.
This is an experimental feature that will change in backward-incompatible ways in future releases.
## Supplying Trace Context to ClickHouse
ClickHouse accepts trace context HTTP headers, as described by
the [W3C recommendation](https://www.w3.org/TR/trace-context/).
It also accepts trace context over native protocol that is used for
communication between ClickHouse servers or between the client and server.
For manual testing, trace context headers conforming to the Trace Context
recommendation can be supplied to `clickhouse-client` using
`--opentelemetry-traceparent` and `--opentelemetry-tracestate` flags.
If no parent trace context is supplied, ClickHouse can start a new trace, with
probability controlled by the `opentelemetry_start_trace_probability` setting.
ClickHouse accepts trace context HTTP headers, as described by the [W3C recommendation](https://www.w3.org/TR/trace-context/). It also accepts trace context over a native protocol that is used for communication between ClickHouse servers or between the client and server. For manual testing, trace context headers conforming to the Trace Context recommendation can be supplied to `clickhouse-client` using `--opentelemetry-traceparent` and `--opentelemetry-tracestate` flags.
If no parent trace context is supplied, ClickHouse can start a new trace, with probability controlled by the `opentelemetry_start_trace_probability` setting.
## Propagating the Trace Context
The trace context is propagated to downstream services in the following cases:
* Queries to remote ClickHouse servers, such as when using `Distributed` table
engine.
* Queries to remote ClickHouse servers, such as when using `Distributed` table engine.
*`URL` table function. Trace context information is sent in HTTP headers.
## Tracing the ClickHouse Itself
ClickHouse creates _trace spans_ for each query and some of the query execution
stages, such as query planning or distributed queries.
ClickHouse creates _trace spans_ for each query and some of the query execution stages, such as query planning or distributed queries.
To be useful, the tracing information has to be exported to a monitoring system
that supports OpenTelemetry, such as Jaeger or Prometheus. ClickHouse avoids
a dependency on a particular monitoring system, instead only providing the
tracing data through a system table. OpenTelemetry trace span information
[required by the standard](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/overview.md#span)
is stored in the `system.opentelemetry_span_log` table.
To be useful, the tracing information has to be exported to a monitoring system that supports `OpenTelemetry`, such as `Jaeger` or `Prometheus`. ClickHouse avoids a dependency on a particular monitoring system, instead only providing the tracing data through a system table. `OpenTelemetry` trace span information [required by the standard](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/overview.md#span) is stored in the `system.opentelemetry_span_log` table.
The table must be enabled in the server configuration, see the `opentelemetry_span_log`
element in the default config file `config.xml`. It is enabled by default.
The table must be enabled in the server configuration, see the `opentelemetry_span_log` element in the default config file `config.xml`. It is enabled by default.
The table has the following columns:
...
...
@@ -64,8 +44,7 @@ The table has the following columns:
-`attribute.name`
-`attribute.values`
The tags or attributes are saved as two parallel arrays, containing the keys
and values. Use `ARRAY JOIN` to work with them.
The tags or attributes are saved as two parallel arrays, containing the keys and values. Use `ARRAY JOIN` to work with them.
## Integration with monitoring systems
...
...
@@ -94,3 +73,5 @@ FROM system.opentelemetry_span_log
```
In case of any errors, the part of the log data for which the error has occurred will be silently lost. Check the server log for error messages if the data does not arrive.
@@ -17,7 +17,7 @@ When `OPTIMIZE` is used with the [ReplicatedMergeTree](../../engines/table-engin
- If `OPTIMIZE` doesn’t perform a merge for any reason, it doesn’t notify the client. To enable notifications, use the [optimize_throw_if_noop](../../operations/settings/settings.md#setting-optimize_throw_if_noop) setting.
- If you specify a `PARTITION`, only the specified partition is optimized. [How to set partition expression](../../sql-reference/statements/alter/index.md#alter-how-to-specify-part-expr).
- If you specify `FINAL`, optimization is performed even when all the data is already in one part.
- If you specify `FINAL`, optimization is performed even when all the data is already in one part. Also merge is forced even if concurrent merges are performed.
- If you specify `DEDUPLICATE`, then completely identical rows will be deduplicated (all columns are compared), it makes sense only for the MergeTree engine.
[OpenTelemetry](https://opentelemetry.io/) — это открытый стандарт для сбора трассировок и метрик из распределенного приложения. В ClickHouse есть поддержка `OpenTelemetry`.
!!! warning "Предупреждение"
Этот стандарт экспериментальный и будет изменяться в будущих релизах.
## Обеспечение поддержки контекста трассировки в ClickHouse
ClickHouse принимает контекст трассировки HTTP заголовков, как описано в [рекомендации W3C](https://www.w3.org/TR/trace-context/). Также он принимает контекст трассировки через нативный протокол, который используется для связи между серверами ClickHouse или между клиентом и сервером. В ручном тестировании заголовки контекста трассировки, соответствующие рекомендации контекста трассировки, могут быть переданы в `clickhouse-client` через флаги: `--opentelemetry-traceparent` и `--opentelemetry-tracestate`.
Если доставлен не родительский контекст трассировки, ClickHouse может запустить новую трассировку, которая будет контролироваться настройкой `opentelemetry_start_trace_probability`.
## Распространение контекста трассировки
Контекст трассировки распространяется на нижестоящие сервисы в следующих случаях:
* При использовании запросов к удаленным серверам ClickHouse, например при использовании движка таблиц `Distributed`.
* При использовании табличной функции `URL`. Информация контекста трассировки передается в HTTP заголовки.
## Трассировка ClickHouse
ClickHouse создает _trace spans_ для каждого запроса и некоторых этапов выполнения запроса, таких как планирование запросов или распределенные запросы.
Чтобы быть полезной, информация трассировки должна быть экспортирована в систему мониторинга, поддерживающую `OpenTelemetry`, такую как `Jaeger` или `Prometheus`. ClickHouse не зависит от конкретной системы мониторинга, вместо этого предоставляя данные трассировки только через системную таблицу. Информация о диапазоне трассировки в `OpenTelemetry`, [требуемая стандартом](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/overview.md#span), хранится в системной таблице `system.opentelemetry_span_log`.
Таблица должна быть включена в конфигурации сервера, смотрите элемент `opentelemetry_span_log` в файле конфигурации `config.xml`. По умолчанию таблица уже включена.
В таблице имеются следующие столбцы:
-`trace_id`
-`span_id`
-`parent_span_id`
-`operation_name`
-`start_time`
-`finish_time`
-`finish_date`
-`attribute.name`
-`attribute.values`
Теги или атрибуты сохраняются в виде двух параллельных массивов, содержащих ключи и значения. Для работы с ними используйте `ARRAY JOIN`.
Поддерживаются только часовые пояса, отличающиеся от UTC на целое число часов.
## toTimeZone {#totimezone}
Переводит дату или дату-с-временем в указанный часовой пояс. Часовой пояс (таймзона) это атрибут типов Date/DateTime, внутреннее значение (количество секунд) поля таблицы или колонки результата не изменяется, изменяется тип поля и автоматически его текстовое отображение.
Функция позволяет получить доступ к значению в колонке `column`, находящемуся на смещении `offset` относительно текущей строки. Является частичной реализацией [оконных функций](https://en.wikipedia.org/wiki/SQL_window_function)`LEAD()` и `LAG()`.
Функция позволяет получить доступ к значению в столбце `column`, находящемуся на смещении `offset` относительно текущей строки. Является частичной реализацией [оконных функций](https://en.wikipedia.org/wiki/SQL_window_function)`LEAD()` и `LAG()`.
**Синтаксис**
...
...
@@ -570,7 +570,13 @@ SELECT
neighbor(column,offset[,default_value])
```
Результат функции зависит от затронутых блоков данных и порядка данных в блоке. Если сделать подзапрос с ORDER BY и вызывать функцию извне подзапроса, можно будет получить ожидаемый результат.
Результат функции зависит от затронутых блоков данных и порядка данных в блоке.
!!! warning "Предупреждение"
Функция может получить доступ к значению в столбце соседней строки только внутри обрабатываемого в данный момент блока данных.
Порядок строк, используемый при вычислении функции `neighbor`, может отличаться от порядка строк, возвращаемых пользователю.
Чтобы этого не случилось, вы можете сделать подзапрос с `ORDER BY` и вызвать функцию изне подзапроса.
**Параметры**
...
...
@@ -675,8 +681,13 @@ FROM numbers(16)
Считает разницу между последовательными значениями строк в блоке данных.
Возвращает 0 для первой строки и разницу с предыдущей строкой для каждой последующей строки.
!!! warning "Предупреждение"
Функция может взять значение предыдущей строки только внутри текущего обработанного блока данных.
Результат функции зависит от затронутых блоков данных и порядка данных в блоке.
Если сделать подзапрос с ORDER BY и вызывать функцию извне подзапроса, можно будет получить ожидаемый результат.
Порядок строк, используемый при вычислении функции `runningDifference`, может отличаться от порядка строк, возвращаемых пользователю.
Чтобы этого не случилось, вы можете сделать подзапрос с `ORDER BY` и вызвать функцию извне подзапроса.
- Если `OPTIMIZE` не выполняет мёрж по любой причине, ClickHouse не оповещает об этом клиента. Чтобы включить оповещения, используйте настройку [optimize_throw_if_noop](../../operations/settings/settings.md#setting-optimize_throw_if_noop).
- Если указать `PARTITION`, то оптимизация выполняется только для указанной партиции. [Как задавать имя партиции в запросах](alter/index.md#alter-how-to-specify-part-expr).
- Если указать `FINAL`, то оптимизация выполняется даже в том случае, если все данные уже лежат в одном куске.
- Если указать `FINAL`, то оптимизация выполняется даже в том случае, если все данные уже лежат в одном куске. Кроме того, слияние является принудительным, даже если выполняются параллельные слияния.
- Если указать `DEDUPLICATE`, то произойдет схлопывание полностью одинаковых строк (сравниваются значения во всех колонках), имеет смысл только для движка MergeTree.
!!! warning "Внимание"
Запрос `OPTIMIZE` не может устранить причину появления ошибки «Too many parts».
