Kafka Connect の Dead Letter Queue 実践ガイド: 失敗メッセージのリカバリ設計（CCDAK 対応）

DLQ は、コネクタや SMT/コンバータで処理できなかったレコードを専用の Kafka トピックへ退避し、他の正常レコードの処理継続を可能にする仕組みです。

本稿では、どの失敗が DLQ に入るのか、設定の勘所、再処理（リカバリ）パターン、運用監視、試験で狙われやすい論点を一気通貫で解説します。

DLQ の基本と CCDAK で問われる観点

Kafka Connect の DLQ は、レコード処理に失敗した場合でもコネクタ全体を停止させず、失敗したレコードだけを別トピックに送るための仕組みです。errors.tolerance=all と DLQ トピック名の設定が基本要件です。

CCDAK では、DLQ に入る失敗の種類、errors.retry.* との関係、ログ出力との違い、順序保証の有無、トピック設計（パーティション数・保持期間・ACL）などが頻出です。

DLQ はレコード単位の隔離により「パイプライン停止」を避ける
DLQ はログよりも構造化された保全（ヘッダにメタ情報）を提供
DLQ は別トピックのため、元トピックとの順序整合性は保証されない
再処理の責務は DLQ 消費側（修復・再投入プロセス）にある

失敗の分類: DLQ に入るもの／入らないもの

Connect の失敗は大きく「コンバータ（シリアライズ/デシリアライズ）」「SMT（Single Message Transform）」「コネクタ本体の処理（特に Sink の外部システム書き込み）」の層で発生します。DLQ は主に Connect フレームワーク内で把握できるレコード処理失敗を対象にします。

一般に、コンバータや SMT の失敗は DLQ 対象です。Sink 側の外部システム書き込み失敗は、コネクタ実装がエラーレポートに対応していない限り DLQ に載らず、RetriableException による再試行やタスク失敗として扱われる点に注意します。

DLQ に入る典型例: スキーマ不整合でのデシリアライズ失敗、SMT 実行時の変換エラー
DLQ に入らない典型例: 外部 DB の一時障害、到達不能、タイムアウト等（多くは RetriableException で再試行）
非再試行（非 Retriable）かつレコード特有の原因であれば、errors.tolerance=all + DLQ で隔離可能
ヘッダに元トピック/パーティション/オフセット、エラー内容、失敗ステージ等のメタ情報を付与可能（設定で有効化）

DLQ の主要設定とトピック設計

DLQ を有効化する最低条件は、errors.tolerance=all と errors.deadletterqueue.topic.name の指定です。ヘッダ付与は errors.deadletterqueue.context.headers.enable を有効にします。auto-create に頼るとブローカー既定のパーティション数になるため、必要に応じて事前作成でパーティションや保持期間を明示します。

保持期間はリカバリの SLA に合わせ、容量見積もりと合わせて決めます。DLQ は調査・再処理に用いるため、ログコンパクションは通常有効化しません。セキュリティ上は、通常の業務トピックとは独立して ACL を厳格化します。

errors.tolerance=all（必須）: レコード単位の失敗を許容
errors.deadletterqueue.topic.name（必須）: DLQ 宛先トピック
errors.deadletterqueue.context.headers.enable=true: エラー情報をヘッダへ
errors.deadletterqueue.topic.replication.factor: 自動作成時のRF（事前作成推奨）
errors.log.enable / errors.log.include.messages: ログ観測と併用
errors.retry.timeout / errors.retry.delay.max.ms: 再試行の上限時間・最大待機（Retriable 時）

Kafka Connect と DLQ の流れ（概念図）

例: Sink コネクタで DLQ を有効化する設定（抜粋）

{
  "name": "jdbc-sink-orders",
  "config": {
    "connector.class": "io.confluent.connect.jdbc.JdbcSinkConnector",
    "topics": "orders",
    "connection.url": "jdbc:postgresql://db:5432/app",
    "tasks.max": "3",

    "errors.tolerance": "all",
    "errors.deadletterqueue.topic.name": "dlq.orders",
    "errors.deadletterqueue.context.headers.enable": "true",
    "errors.deadletterqueue.topic.replication.factor": "3",
    "errors.log.enable": "true",
    "errors.log.include.messages": "true",

    "errors.retry.timeout": "600000",
    "errors.retry.delay.max.ms": "60000"
  }
}

失敗メッセージのリカバリ設計パターン（比較）

DLQ に溜まったレコードは放置せず、リカバリ戦略をパターンとして設計します。代表的には、隔離・調査・修復・再投入のループを自動化するパターン、時間を置いた再投入（リトライ）パターン、手動審査を挟むパターンなどがあります。

いずれのパターンでも、重複許容（at-least-once）と順序非保証を前提に、冪等なシンク側設計（主キー・アップサート・重複排除）を組み合わせるのが実務の要点です。

修復アプリ（Remediator）が DLQ を消費し、修復後に元トピックまたは専用の再処理トピックへ再投入
原因別にルーティング（例: スキーマ不整合は A へ、外部キー欠落は B へ）
段階的なバックオフを入れた再投入でスパイクを回避
DLQ を監査証跡として保持し、再投入結果と相関可能にする

戦略	失敗時の挙動	再処理コスト	向いているケース
停止（errors.tolerance=none）	最初の失敗でタスク停止	低（ただし停止影響大）	データ完全性を最優先し即時介入したい
ログのみ（DLQ 無し）	処理継続、ログで確認	中（調査は手間）	失敗が極めて稀・影響軽微
DLQ（errors.tolerance=all）	失敗レコードのみ隔離	中（後段で修復・再投入）	通常の実務での既定解に近い
DLQ + 再試行制御	Retriable は再試行、非 Retriable は DLQ	中〜高（制御ロジック追加）	一過性障害と恒久的エラーが混在

DLQ から再投入する運用例（調査→修復→再投入の最小手順）

# 1) DLQ をヘッダ付きで調査
kafka-console-consumer \
  --bootstrap-server broker:9092 \
  --topic dlq.orders \
  --from-beginning \
  --property print.headers=true \
  --max-messages 10

# 2) 修復スクリプト等で JSON を整形（例: 欠落フィールド補完）
#    ここは各システムのバリデーションに合わせて実装

# 3) 修復済みメッセージを再処理用トピックへ投入
kafka-console-producer \
  --broker-list broker:9092 \
  --topic fixed.orders

運用監視と SLO 設計

DLQ は“最後の安全網”です。平常時は 0 に近いことが理想で、増加は即アラートと原因究明につなげます。保持切れで証跡が失われないよう、レート × SLA から保持期間・容量を見積もります。

メトリクスは、タスク単位の DLQ 書き込み成功/失敗カウンタ、再試行関連、DLQ コンシューマのレイテンシ/ラグを最低限モニタします。再投入により元トピックの負荷が跳ねないよう、レート制御やバッチ処理も検討します。

DLQ レートのベースライン化と逸脱検知（しきい値/変化率）
DLQ 書き込み失敗が発生した場合は即時対応（設定/権限/トピック存在確認）
保持と容量のダッシュボード化（推定日数、見込みフル時期）
修復・再投入パイプラインの処理件数/失敗率/リードタイムを可視化

試験対策チェックリストと落とし穴

CCDAK では、errors.tolerance と DLQ の関係、RetriableException の再試行、ヘッダによる調査容易性、順序・重複の扱い、そして“外部システム書き込み失敗が必ずしも DLQ へ行くわけではない”点が狙われます。

実務では、DLQ を有効化しても“誰がどう再処理するか”が決まっていないと負債化します。リカバリ責務・SLO・トピック/ACL/保持・監視・容量見積りをセットで設計してください。

errors.tolerance=all + errors.deadletterqueue.topic.name で DLQ 有効化
errors.retry.timeout / errors.retry.delay.max.ms は再試行ウィンドウを制御（Retriable のみ）
DLQ は別トピックであり順序非保証・重複再処理前提（シンクは冪等に）
外部システム書き込み失敗はコネクタ実装依存で DLQ 非対応の場合がある
DLQ トピックは事前作成でパーティション数・保持期間・RF を明示
ヘッダ付与で調査効率を上げる（元トピック/パーティション/オフセットなど）

問題で確認

CCDAK

問題 1

Kafka Connect の Sink コネクタで、特定レコードの変換エラーが発生しても処理を止めず、失敗レコードを後で調査・再処理できるようにしたい。最小限必要な設定の組み合わせはどれか？

errors.tolerance=none と errors.log.enable=true
errors.tolerance=all と errors.deadletterqueue.topic.name の指定
errors.retry.timeout のみを大きく設定する
コネクタの tasks.max を増やす

正解: B

レコード単位の失敗を許容して DLQ に送るには、errors.tolerance=all と errors.deadletterqueue.topic.name の設定が必要。ログ有効化や再試行時間延長、並列度増加だけでは失敗レコードの隔離は実現しない。

よくある質問

DLQ に送られたレコードの順序は元トピックと一致するか？

一致は保証されません。DLQ は別トピックであり、複数タスクから並行書き込みされるため、元の順序や相対的な位置は保持されません。順序が必要な再処理は、キー単位の直列化など別途工夫が必要です。

外部システムの一時障害（例: DB 接続切断）は DLQ に送られるか？

一般に送られません。多くのケースでコネクタは RetriableException を投げ、errors.retry.* に従って再試行されます。非再試行のレコード固有エラーや、コネクタ実装がエラーレポート対応している場合のみ DLQ へ送られることがあります。

DLQ トピックはどのように設計すべきか？

事前作成でパーティション数とレプリケーション係数を明示し、保持期間は調査・再処理の SLO に合わせて十分に確保します。通常はログコンパクションを無効にし、ACL を強化して閲覧・再投入権限を分離します。

この記事で学んだ内容を問題で確認しましょう

16,000問以上の問題で実力チェック

無料で問題を解いてみる

この記事の著者

NicheeLab編集部

データエンジニアリング・クラウド資格の専門家。Databricks・Snowflake等の認定資格を保有し、実務経験に基づいた問題作成・解説を行っています。NicheeLab運営。

Kafka Connect の Dead Letter Queue 実践ガイド: 失敗メッセージのリカバリ設計