Troubleshooting CDC

Симптомы

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

Причина

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

Решение

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

Симптомы

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

Причина

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

Решение

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 если удалили слот

Симптомы

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

Причина

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

Решение

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

Симптомы

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

Причина

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

Решение

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';

Симптомы

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

Причина

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

Решение

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 на малоактивных таблицах

Симптомы

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

Причина

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

Решение

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 для предотвращения проблемы

Симптомы

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

Причина

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

Решение

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

Симптомы

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

Причина

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

Решение

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

Симптомы

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

Причина

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

Решение

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

Симптомы

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

Причина

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

Решение

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

Симптомы

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

Причина

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

Решение

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;

Симптомы

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

Причина

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

Решение

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"

Симптомы

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

Причина

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

Решение

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 коннекторов в вашей инфраструктуре

Симптомы

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

Причина

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

Решение

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. После изменения пересоздайте коннектор для корректной обработки новых событий

Симптомы

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

Причина

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

Решение

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

Симптомы

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

Причина

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

Решение

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. Убедитесь, что имя уникально перед созданием

Симптомы

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

Причина

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

Решение

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

Симптомы

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

Причина

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

Решение

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

Симптомы

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

Причина

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

Решение

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

Симптомы

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

Причина

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

Решение

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