> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> Подробно описывает лучшие практики, которых следует придерживаться при работе с Kafka ClickPipes.

# Лучшие практики

<div id="compression">
  ## Сжатие сообщений
</div>

Мы настоятельно рекомендуем использовать сжатие для топиков Kafka. Сжатие позволяет существенно сократить затраты на передачу данных практически без ущерба для производительности.
Чтобы узнать больше о сжатии сообщений в Kafka, рекомендуем начать с этого [руководства](https://www.confluent.io/blog/apache-kafka-message-compression/).

<div id="limitations">
  ## Ограничения
</div>

* [`DEFAULT`](/docs/ru/reference/statements/create/table#default) не поддерживается.
* По умолчанию размер отдельного сообщения ограничен 16 МБ (без сжатия) при использовании реплики минимального размера (XS) и 32 МБ (без сжатия) при использовании реплик большего размера.  Сообщения, превышающие этот лимит, будут отклонены с ошибкой.  Если вам нужны сообщения большего размера, обратитесь в службу поддержки.

<div id="delivery-semantics">
  ## Семантика доставки
</div>

ClickPipes for Kafka по умолчанию гарантирует доставку как минимум один раз, отслеживая ход ингестии по смещениям группы потребителей Kafka. Также он опционально поддерживает семантику «ровно один раз»: каждая запись Kafka вставляется в ClickHouse ровно один раз, даже при перезапусках подов, перебалансировках потребителей и сбоях вставки.

Для обеспечения семантики «ровно один раз» ClickPipes сохраняет прогресс каждой партиции во внутреннем хранилище состояния, используя два значения:

* **Метка верхней границы** — смещение, до которого подтверждена вставка в ClickHouse всех записей партиции. После перезапуска ClickPipes отбрасывает записи с этим смещением или меньшим, поэтому уже доставленные данные никогда не отправляются повторно.
* **Ожидающие диапазоны** — диапазоны смещений блоков вставки, отправленных в ClickHouse, но ещё не подтверждённых. После сбоя ClickPipes повторно обрабатывает именно эти диапазоны.

Каждый блок вставки охватывает непрерывный диапазон смещений и содержит детерминированный [токен дедупликации](/docs/ru/concepts/features/operations/insert/deduplicating-inserts-on-retries) вида `topic:partition:firstOffset-lastOffset`. При повторной обработке ClickPipes воспроизводит тот же диапазон смещений и, следовательно, тот же токен, поэтому ClickHouse отклоняет дубликат. Поскольку токен зависит только от диапазона смещений, повторная обработка дедуплицируется, даже если заново сформированный блок не идентичен исходному побайтно.

<Note>
  **Окно дедупликации**

  Дедупликация по токенам ограничена параметрами целевой таблицы [`replicated_deduplication_window`](/docs/ru/reference/settings/merge-tree-settings/replicated-deduplication-window#replicated_deduplication_window) (по умолчанию последние 10 000 блоков вставки) и [`replicated_deduplication_window_seconds`](/docs/ru/reference/settings/merge-tree-settings/replicated-deduplication-window#replicated_deduplication_window_seconds) (по умолчанию один час). Пайпы с высокой пропускной способностью могут быстро исчерпать окно по количеству блоков, поэтому рекомендуем проверить и при необходимости увеличить оба параметра целевой таблицы, чтобы они покрывали максимальную возможную задержку повторной обработки. Данные, повторно обработанные после того, как их токен вышел из окна, могут быть вставлены снова, поэтому в этом случае семантика «ровно один раз» не гарантируется.
</Note>

Основной компромисс связан с размером частей. Более крупные блоки вставки создают в ClickHouse меньше, но более крупных [частей](/docs/ru/concepts/core-concepts/parts), что снижает накладные расходы на слияние. ClickPipes хранит строки партиции в памяти при формировании блока, поэтому достижимый размер части зависит от памяти, доступной пайпу: при нехватке памяти он формирует меньшие блоки, и в таблице накапливается больше частей. Чем больше памяти выделено пайпу, тем более крупные блоки он может формировать и тем меньше частей создавать.

Пайп работает лучше всего, когда количество партиций близко к количеству внутренних «воркеров» вставки: тогда каждый воркер обрабатывает примерно одну партицию и имеет достаточный запас памяти для формирования крупных блоков. Количество воркеров и доступная память масштабируются в зависимости от размера и количества реплик; их можно настроить в разделе **Настройки** -> **Расширенная настройка** -> **Масштабирование**.

<div id="authentication">
  ## Аутентификация
</div>

Для источников данных, использующих протокол Apache Kafka, ClickPipes поддерживает аутентификацию [SASL/PLAIN](https://docs.confluent.io/platform/current/kafka/authentication_sasl/authentication_sasl_plain.html) с шифрованием TLS, а также `SASL/SCRAM-SHA-256` и `SASL/SCRAM-SHA-512`. В зависимости от источника стриминга (Redpanda, MSK и т. д.) будут доступны все или только некоторые из этих механизмов аутентификации — в зависимости от совместимости. Если вам нужны другие способы аутентификации, пожалуйста, [сообщите нам об этом](https://clickhouse.com/company/contact?loc=clickpipes).

<div id="warpstream-settings">
  ## Размер выборки в Warpstream
</div>

ClickPipes используют параметр Kafka `max.fetch_bytes`, чтобы ограничить размер данных, одновременно обрабатываемых одним узлом ClickPipes. В некоторых случаях
Warpstream игнорирует этот параметр, что может приводить к непредвиденным сбоям пайпов. Мы настоятельно рекомендуем при настройке агента WarpStream установить специальный параметр Warpstream `kafkaMaxFetchPartitionBytesUncompressedOverride`
в значение 8 MB (или меньше), чтобы предотвратить сбои ClickPipes.

<div id="iam">
  ### IAM
</div>

ClickPipes поддерживает следующие способы аутентификации AWS MSK

* аутентификация [SASL/SCRAM-SHA-512](https://docs.aws.amazon.com/msk/latest/developerguide/msk-password.html)
* аутентификация с использованием [учетных данных IAM или доступа на основе ролей](https://docs.aws.amazon.com/msk/latest/developerguide/how-to-use-iam-access-control.html)

При использовании аутентификации IAM для подключения к брокеру MSK роль IAM должна иметь необходимые разрешения.
Ниже приведен пример необходимой политики IAM для API Apache Kafka в MSK:

```json theme={null}
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "kafka-cluster:Connect"
            ],
            "Resource": [
                "arn:aws:kafka:us-west-2:12345678912:cluster/clickpipes-testing-brokers/b194d5ae-5013-4b5b-ad27-3ca9f56299c9-10"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "kafka-cluster:DescribeTopic",
                "kafka-cluster:ReadData"
            ],
            "Resource": [
                "arn:aws:kafka:us-west-2:12345678912:topic/clickpipes-testing-brokers/*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "kafka-cluster:AlterGroup",
                "kafka-cluster:DescribeGroup"
            ],
            "Resource": [
                "arn:aws:kafka:us-east-1:12345678912:group/clickpipes-testing-brokers/*"
            ]
        }
    ]
}
```

<div id="configuring-a-trusted-relationship">
  #### Настройка доверительной связи
</div>

Если вы выполняете аутентификацию в MSK с помощью ARN роли IAM, вам нужно настроить доверительную связь между вашим экземпляром ClickHouse Cloud и этой ролью, чтобы экземпляр мог принять роль.

<Note>
  Доступ на основе ролей работает только для экземпляров ClickHouse Cloud, развернутых в AWS.
</Note>

```json theme={null}
{
    "Version": "2012-10-17",
    "Statement": [
        ...
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::12345678912:role/CH-S3-your-clickhouse-cloud-role"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}
```

<div id="custom-certificates">
  ### Пользовательские сертификаты
</div>

ClickPipes for Kafka поддерживает загрузку пользовательских сертификатов для брокеров Kafka, использующих непубличные серверные сертификаты.
Также можно загружать клиентские сертификаты и ключи для аутентификации на основе взаимного TLS (mTLS).

<div id="performance">
  ## Производительность
</div>

<div id="batching">
  ### Батчинг
</div>

ClickPipes вставляет данные в ClickHouse батчами. Это позволяет избежать создания слишком большого количества частей в базе данных, что может привести к проблемам с производительностью кластера.

Батчи вставляются при выполнении одного из следующих условий:

* Размер батча достиг максимального значения (100 000 строк или 28 МБ на 1 ГБ памяти пода)
* Батч оставался открытым в течение максимально допустимого времени (5 секунд)

<div id="latency">
  ### Задержка
</div>

Задержка (определяемая как время между публикацией сообщения в Kafka и моментом, когда оно становится доступным в ClickHouse) зависит от ряда факторов (например, задержки брокера, сетевой задержки, размера/формата сообщения). [Батчинг](#batching), описанный в разделе выше, также влияет на задержку. Мы всегда рекомендуем тестировать ваш конкретный сценарий при типичных нагрузках, чтобы определить ожидаемую задержку.

ClickPipes не предоставляет никаких гарантий по задержке. Если у вас есть строгие требования к низкой задержке, пожалуйста, [свяжитесь с нами](https://clickhouse.com/company/contact?loc=clickpipes).

<div id="scaling">
  ### Масштабирование
</div>

ClickPipes for Kafka поддерживает горизонтальное и вертикальное масштабирование. По умолчанию создается группа потребителей с одним потребителем. Это можно настроить при создании ClickPipe или позже в разделе **Настройки** -> **Дополнительные настройки** -> **Масштабирование**.

ClickPipes обеспечивает высокую доступность благодаря архитектуре, распределенной по зонам доступности.
Для этого необходимо масштабирование как минимум до двух потребителей.

Независимо от количества работающих потребителей отказоустойчивость обеспечивается на уровне архитектуры.
Если потребитель или базовая инфраструктура выйдет из строя,
ClickPipe автоматически перезапустит потребителя и продолжит обработку сообщений.

<div id="benchmarks">
  ### Бенчмарки
</div>

Ниже приведены несколько неформальных бенчмарков для ClickPipes for Kafka, которые помогут получить общее представление о базовой производительности. Важно учитывать, что на производительность влияет множество факторов, включая размер сообщений, типы данных и формат данных. Фактические результаты могут отличаться, и приведенные здесь значения не гарантируют такой же производительности в реальных условиях.

Детали бенчмарка:

* Мы использовали сервисы ClickHouse Cloud в продакшн-конфигурации с достаточным объемом ресурсов, чтобы пропускная способность не упиралась в обработку вставки на стороне ClickHouse.
* Сервис ClickHouse Cloud, кластер Kafka (Confluent Cloud) и ClickPipe работали в одном регионе (`us-east-2`).
* ClickPipe был настроен с одной репликой размера L (4 GiB оперативной памяти и 1 vCPU).
* Тестовые данные включали вложенные структуры и сочетание типов `UUID`, `String` и `Int`. Другие типы данных, такие как `Float`, `Decimal` и `DateTime`, могут давать более низкую производительность.
* Заметной разницы в производительности между сжатыми и несжатыми данными не наблюдалось.

| Размер реплики | Размер сообщения | Формат данных | Пропускная способность |
| -------------- | ---------------- | ------------- | ---------------------- |
| Large (L)      | 1.6kb            | JSON          | 63mb/s                 |
| Large (L)      | 1.6kb            | Avro          | 99mb/s                 |