Kafka Connect Dead Letter Queue — sink 커넥터의 문제 레코드 격리
Kafka 트랜잭션 좀비 펜싱 및 Kafka Connect DLQ 공식 문서 종합 (웹 리서치, 2026) — Apache Kafka KIP-447/KIP-298 + Confluent 공식 블로그(Transactions in Apache Kafka, Kafka Connect Deep Dive Error Handling and Dead Letter Queues) Apache Kafka KIP-298 및 Confluent 블로그 Kafka Connect Deep Dive Error Handling and Dead Letter Queues
이 모듈을 다 읽으면
- errors.tolerance 설정이 커넥터의 에러 처리 모드를 어떻게 바꾸는지 설명할 수 있다
- DLQ가 source 커넥터가 아니라 sink 커넥터(및 그 변환/컨버터) 전용 기능인 이유를 설명할 수 있다
kafka-learn-50에서 다룬 source/sink 커넥터 구분을 전제로, sink 커넥터가 레코드를 처리하다 실패했을 때 커넥터 전체를 멈추는 대신 문제 레코드만 별도 토픽으로 격리해 계속 진행할 수 있게 해주는 Dead Letter Queue(DLQ) 기능을 정리한다.
기본값은 'none' — 에러 하나가 태스크 전체를 멈춘다
errors.tolerance의 기본값은 none으로, 레코드 처리 중 에러가 발생하면 커넥터 태스크가 즉시 멈춘다 — 문제 레코드 하나 때문에 이후의 정상 레코드까지 전부 처리가 중단되는 셈이다. errors.tolerance=all로 바꾸면 에러가 난 레코드는 건너뛰고 나머지 레코드 처리를 계속 진행할 수 있게 되는데, 이때 건너뛴 레코드를 그냥 버리지 않고 DLQ로 보내려면 errors.deadletterqueue.topic.name에 토픽 이름을 지정해야 한다(기본값은 빈 문자열이라 지정 안 하면 DLQ에 아무것도 안 남는다).
핵심 포인트
- errors.tolerance 기본값은 'none' — 에러 발생 시 태스크 전체가 즉시 멈춤
- errors.tolerance=all + errors.deadletterqueue.topic.name 지정 시 에러 레코드를 DLQ로 보내고 나머지는 계속 처리
왜 sink 커넥터 전용인가
DLQ는 sink 커넥터가 레코드를 외부 시스템에 쓰는 과정, 혹은 그 과정에 얹힌 변환(SMT)·컨버터에서 실패했을 때 그 레코드를 격리하는 기능이다 — source 커넥터에는 이런 개념이 적용되지 않는데, source 커넥터의 실패는 '외부 시스템에서 읽어오다가' 발생하는 것이라 애초에 Kafka에 쓸 레코드 자체가 만들어지지 않은 상태이기 때문이다(격리할 대상 레코드가 없다). 이 비대칭은 kafka-learn-50에서 다룬 source/sink의 근본적인 방향성 차이(외부→Kafka vs Kafka→외부)에서 자연스럽게 따라 나온다.
핵심 포인트
- DLQ는 sink 커넥터(및 그 SMT/컨버터)의 레코드 처리 실패 전용 — source 커넥터에는 적용 안 됨
- source 커넥터의 실패는 외부 시스템 읽기 단계에서 일어나 애초에 격리할 Kafka 레코드 자체가 없기 때문 — source/sink의 방향성 차이에서 자연스럽게 따라오는 비대칭
단일 노드 클러스터에서 흔히 놓치는 함정 — replication.factor
errors.deadletterqueue.topic.replication.factor의 기본값은 3인데, 개발 환경처럼 브로커가 1대뿐인 단일 노드 클러스터에서는 이 기본값으로 토픽 생성 자체가 실패한다 — 이런 환경에서는 반드시 errors.deadletterqueue.topic.replication.factor=1로 명시적으로 낮춰줘야 DLQ 토픽이 정상적으로 만들어진다. 프로덕션 다중 브로커 환경으로 옮길 때 이 설정을 다시 3(또는 그에 준하는 값)으로 되돌리는 것을 잊는 실수도 흔하다.
핵심 포인트
- errors.deadletterqueue.topic.replication.factor 기본값은 3 — 단일 브로커 개발환경에서는 1로 낮추지 않으면 DLQ 토픽 생성 자체가 실패
- 프로덕션 다중 브로커 환경 이관 시 이 값을 다시 적절히 되돌리는 것을 잊는 실수가 흔함