Troubleshooting CDC

Symptoms

• Debezium не может подключиться к PostgreSQL для репликации
• В логах коннектора: "FATAL: no pg_hba.conf entry for replication connection"
• Connector status: FAILED при попытке старта

Cause

PostgreSQL не разрешает подключения для репликации от указанного хоста. Файл pg_hba.conf контролирует аутентификацию и должен явно разрешать replication connections для пользователя и хоста Debezium.

Solution

1. Откройте файл pg_hba.conf (обычно /var/lib/postgresql/data/pg_hba.conf)
2. Добавьте строку для репликации: host replication debezium 0.0.0.0/0 md5
3. Перезагрузите конфигурацию: SELECT pg_reload_conf(); (или перезапуск PostgreSQL)
4. Проверьте подключение: psql -h localhost -U debezium -d postgres -c "IDENTIFY_SYSTEM" replication=database

Symptoms

• Коннектор не стартует после рестарта Kafka Connect
• Ошибка при создании нового коннектора с тем же именем слота
• PostgreSQL показывает slot с active = true

Cause

Предыдущий инстанс коннектора не освободил replication slot корректно, или slot уже используется другим процессом репликации. PostgreSQL позволяет только одно активное соединение к каждому слоту.

Solution

1. Проверьте активные слоты: SELECT slot_name, active, active_pid FROM pg_replication_slots;
2. Если slot показывает active = true, найдите процесс: SELECT pid, usename, application_name FROM pg_stat_replication;
3. Терминируйте соединение: SELECT pg_terminate_backend();
4. Или удалите слот (ПОТЕРЯЕТЕ ПОЗИЦИЮ!): SELECT pg_drop_replication_slot('debezium');
5. Пересоздайте коннектор с snapshot.mode=initial если удалили слот

Symptoms

• Директория pg_wal занимает десятки/сотни GB
• Диск PostgreSQL заполняется
• Replication slot показывает большой lag между current_lsn и restart_lsn

Cause

Replication slot удерживает WAL-сегменты, не позволяя PostgreSQL удалять их до тех пор, пока Debezium не прочитает. Если коннектор остановлен или работает медленно, WAL накапливается.

Solution

1. Проверьте lag слота: SELECT slot_name, pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn) AS lag_bytes FROM pg_replication_slots;
2. Если коннектор МЁРТВ и не планируется запускать — удалите слот: SELECT pg_drop_replication_slot('debezium');
3. Если коннектор временно остановлен — запустите его для чтения накопленного WAL
4. Настройте мониторинг lag и автоудаление неиспользуемых слотов: max_slot_wal_keep_size = 10GB

Symptoms

• Snapshot фаза зависает или падает с timeout
• Ошибка "could not obtain lock" в логах коннектора
• Snapshot не завершается на больших таблицах

Cause

Debezium пытается сделать consistent snapshot и требует короткую блокировку таблиц. Если на таблице есть долгие транзакции или активные записи, блокировку получить невозможно.

Solution

1. Увеличьте snapshot.lock.timeout.ms в конфигурации коннектора (по умолчанию 10 секунд)
2. Запланируйте snapshot на период низкой нагрузки (ночь, выходные)
3. Используйте snapshot.mode=never и snapshot.mode=schema_only если начальные данные не критичны
4. Проверьте активные транзакции: SELECT pid, usename, query, state FROM pg_stat_activity WHERE state != 'idle';

Symptoms

• MySQL коннектор не может начать streaming или snapshot
• Ошибка ERROR 1236 при инициализации коннектора
• Binlog файлы были ротированы или удалены

Cause

Debezium пытается читать binlog с позиции, которая уже была удалена из-за ротации логов. Это происходит после длительного downtime коннектора или при агрессивных настройках expire_logs_days / binlog_expire_logs_seconds.

Solution

1. Проверьте доступные binlog файлы: SHOW BINARY LOGS;
2. Увеличьте retention период: SET GLOBAL expire_logs_days = 7; или SET GLOBAL binlog_expire_logs_seconds = 604800;
3. Удалите коннектор и пересоздайте с snapshot.mode=initial для полного ресканирования
4. Настройте Heartbeat для предотвращения удаления binlog на малоактивных таблицах

Symptoms

• MySQL коннектор падает при попытке подключения в GTID режиме
• Ошибка про purged GTIDs в логах Debezium
• После восстановления сервера или длительного downtime

Cause

MySQL удалил binlog файлы, содержащие GTID транзакции, которые Debezium ещё не прочитал. При использовании GTID режима невозможно продолжить репликацию с пропущенными GTID.

Solution

1. Проверьте purged GTID set: SHOW GLOBAL VARIABLES LIKE 'gtid_purged';
2. Проверьте executed GTID set: SHOW MASTER STATUS;
3. ВАРИАНТ 1: Пересоздайте коннектор с полным snapshot
4. ВАРИАНТ 2 (ОПАСНО): Сбросьте gtid_purged на slave (Debezium): RESET MASTER; и SET GLOBAL gtid_purged='';
5. Увеличьте binlog retention для предотвращения проблемы

Symptoms

• Коннектор не создаётся, валидация конфигурации падает
• Ошибка при POST /connectors с некорректным database.server.name
• Спецсимволы в имени сервера

Cause

Параметр database.server.name используется как префикс для Kafka топиков. Kafka топики не поддерживают большинство спецсимволов, только [a-zA-Z0-9._-].

Solution

1. Используйте только буквы, цифры, точку, дефис и подчёркивание в database.server.name
2. Пример правильного значения: dbserver1, pg-prod, mysql.replica_01
3. Пример неправильного: db@server, pg prod, mysql:5432
4. Измените конфигурацию коннектора и пересоздайте

Symptoms

• Consumer group показывает растущий lag
• Задержка между изменением в БД и доставкой в Kafka увеличивается
• kafka-consumer-groups --describe показывает LAG > 0 и растёт

Cause

Consumer приложение не успевает обрабатывать CDC события с той скоростью, с которой они поступают. Возможные причины: медленная бизнес-логика, неоптимальная сериализация, недостаточная параллелизация.

Solution

1. Проверьте метрики consumer: throughput, processing time per message
2. Увеличьте количество партиций топика для параллельной обработки
3. Увеличьте количество consumer инстансов (до числа партиций)
4. Оптимизируйте бизнес-логику: используйте batch processing, асинхронность
5. Рассмотрите использование Kafka Streams для более эффективной обработки

Symptoms

• Коннектор не может создать replication slot
• Ошибка "logical decoding requires wal_level >= logical" в PostgreSQL логах
• pg_create_logical_replication_slot() возвращает ошибку

Cause

PostgreSQL параметр wal_level установлен в replica или minimal, что недостаточно для logical replication. Debezium требует wal_level = logical для захвата изменений через логическую репликацию.

Solution

1. Проверьте текущий уровень: SHOW wal_level;
2. Откройте postgresql.conf и установите: wal_level = logical
3. Перезапустите PostgreSQL сервер (требуется полный рестарт, reload недостаточен)
4. Проверьте изменение: SHOW wal_level; должно вернуть "logical"
5. После перезапуска создайте коннектор заново

Symptoms

• PostgreSQL коннектор не стартует в pgoutput plugin режиме
• Ошибка "publication does not exist" при инициализации
• Connector status: FAILED с упоминанием publication

Cause

При использовании pgoutput plugin (Debezium 2.0+), коннектор ожидает существующую PostgreSQL publication. Если publication.autocreate.mode=disabled, publication должна быть создана вручную.

Solution

1. Проверьте существующие publications: SELECT * FROM pg_publication;
2. Создайте publication для всех таблиц: CREATE PUBLICATION dbz_publication FOR ALL TABLES;
3. Или для конкретных таблиц: CREATE PUBLICATION dbz_publication FOR TABLE customers, orders;
4. Или включите автосоздание в конфигурации: publication.autocreate.mode=all_tables
5. Убедитесь, что пользователь Debezium имеет права на publication

Symptoms

• Коннектор не может создать replication slot
• Ошибка "must be superuser or replication role"
• pg_create_logical_replication_slot() падает с permission denied

Cause

Пользователь БД, который использует Debezium, не имеет прав REPLICATION. Только пользователи с REPLICATION role или SUPERUSER могут создавать и использовать replication slots.

Solution

1. Проверьте права пользователя: SELECT rolname, rolreplication FROM pg_roles WHERE rolname = 'debezium';
2. Предоставьте REPLICATION права: ALTER USER debezium WITH REPLICATION;
3. Или создайте пользователя с нужными правами: CREATE USER debezium WITH REPLICATION PASSWORD 'password';
4. Дополнительно дайте права на БД: GRANT CONNECT ON DATABASE mydb TO debezium;
5. И на схему: GRANT USAGE ON SCHEMA public TO debezium; GRANT SELECT ON ALL TABLES IN SCHEMA public TO debezium;

Symptoms

• MySQL коннектор не стартует
• Ошибка про row-level binlog format при инициализации
• Debezium требует ROW формат, но MySQL использует STATEMENT или MIXED

Cause

MySQL параметр binlog_format установлен в STATEMENT или MIXED. Debezium требует binlog_format = ROW для захвата всех изменений на уровне строк, включая изменения данных до и после.

Solution

1. Проверьте текущий формат: SHOW VARIABLES LIKE 'binlog_format';
2. Установите динамически (до перезапуска): SET GLOBAL binlog_format = 'ROW';
3. Сделайте постоянным в my.cnf: [mysqld] секция, добавьте binlog_format = ROW
4. Перезапустите MySQL для применения постоянных настроек
5. Проверьте: SHOW VARIABLES LIKE 'binlog_format'; должно вернуть "ROW"

Symptoms

• MySQL коннектор не может начать репликацию
• Ошибка "server_id is not set" или "server_id cannot be 0"
• Binlog replication не работает

Cause

MySQL параметр server_id не установлен или равен 0. Для репликации (включая CDC) каждый сервер в топологии должен иметь уникальный server_id > 0.

Solution

1. Проверьте текущий server_id: SHOW VARIABLES LIKE 'server_id';
2. Установите уникальный ID: SET GLOBAL server_id = 223344; (временно)
3. Сделайте постоянным в my.cnf: [mysqld] секция, добавьте server_id = 223344
4. Перезапустите MySQL
5. Убедитесь, что server_id уникален среди всех MySQL серверов и Debezium коннекторов в вашей инфраструктуре

Symptoms

• CDC события содержат неполные данные
• Для UPDATE операций отсутствуют значения "before"
• Warning в логах Debezium про binlog_row_image

Cause

MySQL параметр binlog_row_image установлен в MINIMAL или NOBLOB. Debezium требует FULL для получения полных данных "before" и "after" для всех операций.

Solution

1. Проверьте текущее значение: SHOW VARIABLES LIKE 'binlog_row_image';
2. Установите FULL: SET GLOBAL binlog_row_image = 'FULL';
3. Сделайте постоянным в my.cnf: [mysqld] секция, добавьте binlog_row_image = FULL
4. Перезапустите MySQL для применения
5. После изменения пересоздайте коннектор для корректной обработки новых событий

Symptoms

• MySQL коннектор периодически падает с ошибкой 2013
• Долгие snapshot операции прерываются
• Ошибка "Lost connection to MySQL server" во время чтения binlog

Cause

MySQL терминирует соединение из-за превышения таймаута или проблем сети. Причины: wait_timeout слишком мал, max_allowed_packet недостаточен, сетевые разрывы, большие транзакции.

Solution

1. Увеличьте wait_timeout и interactive_timeout на сервере: SET GLOBAL wait_timeout = 28800;
2. Увеличьте max_allowed_packet: SET GLOBAL max_allowed_packet = 67108864; (64MB)
3. В my.cnf добавьте: wait_timeout = 28800, max_allowed_packet = 64M
4. В конфигурации коннектора увеличьте connect.timeout.ms и connect.keep.alive.ms
5. Проверьте сетевую стабильность между Kafka Connect и MySQL

Symptoms

• POST /connectors возвращает 409 Conflict
• Ошибка "Connector xyz already exists"
• Невозможно создать коннектор с существующим именем

Cause

Имя коннектора уже используется в Kafka Connect кластере. Каждый коннектор должен иметь уникальное имя в пределах кластера.

Solution

1. Проверьте существующие коннекторы: curl http://localhost:8083/connectors
2. Удалите старый коннектор: curl -X DELETE http://localhost:8083/connectors/xyz
3. Или используйте другое имя для нового коннектора
4. Или обновите существующий: curl -X PUT http://localhost:8083/connectors/xyz/config -H "Content-Type: application/json" -d @config.json
5. Убедитесь, что имя уникально перед созданием

Symptoms

• MySQL коннектор не стартует после перезапуска
• Ошибка про недоступный schema.history.internal.kafka.topic
• Коннектор не может восстановить историю DDL изменений

Cause

Kafka топик для хранения истории схем БД (DDL changes) был удалён или недоступен. MySQL коннектор требует этот топик для отслеживания структуры таблиц во времени.

Solution

1. Проверьте существование топика: kafka-topics --bootstrap-server localhost:9092 --list | grep schema-history
2. Если топик удалён, варианты восстановления:
3. ВАРИАНТ 1 (если есть бэкап): Восстановите топик из бэкапа
4. ВАРИАНТ 2: Пересоздайте коннектор с snapshot.mode=initial (потеряете offset)
5. ВАРИАНТ 3 (ОПАСНО): schema.history.internal.skip.unparseable.ddl=true
6. Настройте retention для schema history топика: min.compaction.lag.ms, delete.retention.ms

Symptoms

• Коннектор не может сохранить offset
• Ошибка про недоступный offset.storage.topic
• Connector повторно читает те же события после рестарта

Cause

Kafka топик для хранения offset (connect-offsets) недоступен, удалён, или у Kafka Connect нет прав на запись. Без offset коннектор не может отслеживать свою позицию в логах репликации.

Solution

1. Проверьте топик offset: kafka-topics --bootstrap-server localhost:9092 --describe --topic connect-offsets
2. Убедитесь, что топик существует и имеет достаточное число партиций и реплик
3. Проверьте права Kafka Connect на запись в топик (ACL если используется)
4. Проверьте настройки Kafka Connect worker: offset.storage.topic, offset.storage.replication.factor
5. Если топик удалён — создайте заново: kafka-topics --create --topic connect-offsets --replication-factor 3 --partitions 25 --config cleanup.policy=compact

Symptoms

• Kafka Connect worker падает с OutOfMemoryError
• Коннектор зависает во время snapshot больших таблиц
• Увеличение памяти в метриках JVM до предела heap

Cause

Недостаточно памяти JVM heap для обработки больших событий или snapshot операций. Причины: очень большие таблицы в snapshot, огромные транзакции, много коннекторов на одном worker, малый heap size.

Solution

1. Увеличьте heap size в KAFKA_HEAP_OPTS: export KAFKA_HEAP_OPTS="-Xms4G -Xmx4G"
2. Для snapshot: используйте incremental snapshot вместо initial (Debezium 1.6+)
3. Уменьшите max.batch.size и max.queue.size в конфигурации коннектора
4. Разделите коннекторы по разным worker процессам
5. Мониторьте JVM метрики: heap usage, GC frequency, GC pause time
6. Используйте G1GC для лучшего управления памятью: -XX:+UseG1GC

Symptoms

• PostgreSQL коннектор не стартует с plugin.name=pgoutput
• Ошибка "could not access file pgoutput"
• pg_create_logical_replication_slot падает при указании pgoutput

Cause

PostgreSQL не имеет установленного pgoutput плагина или используется старая версия PostgreSQL (< 10). pgoutput — это встроенный плагин логической репликации, доступный с PostgreSQL 10+.

Solution

1. Проверьте версию PostgreSQL: SELECT version(); — должна быть 10 или выше
2. Проверьте доступные плагины: SELECT * FROM pg_available_extensions WHERE name = 'pgoutput';
3. Если PostgreSQL < 10: обновите до версии 10+ или используйте decoderbufs plugin
4. Если PostgreSQL >= 10 но pgoutput отсутствует: переустановите PostgreSQL или плагин
5. Альтернативно используйте plugin.name=decoderbufs (требует отдельной установки)
6. Для RDS/Aurora: убедитесь, что rds.logical_replication = 1 в parameter group