すべてのプロダクト
Search

このプロダクト

    ApsaraMQ for RabbitMQ:デッドレターエクスチェンジ

    ドキュメントセンター

    ApsaraMQ for RabbitMQ:デッドレターエクスチェンジ

    最終更新日:Oct 01, 2026

    メッセージは、コンシューマーによる拒否、リトライ回数の上限超過、または Time-to-Live (TTL) の期限切れなどにより、処理に失敗することがあります。これらのメッセージが失われるのを防ぐため、デッドレターエクスチェンジ (DLX) はこれらのメッセージを捕捉し、調査、再処理、またはアラート通知のために専用のキューにルーティングします。

    以下のセクションでは、ApsaraMQ for RabbitMQ の主要な概念、ルーティングプロセス、設定方法、およびデッドレターメッセージのヘッダーについて説明します。

    基本概念

    用語定義
    デッドレターエクスチェンジデッドレターメッセージを受信し、バインディングキー、ルーティングキー、およびヘッダー属性に基づいてデッドレターキューにルーティングするエクスチェンジです。direct、fanout、topic、headers といった標準的なエクスチェンジタイプはいずれも、デッドレターエクスチェンジとして機能します。
    デッドレターのルーティングキーデッドレターメッセージのルーティングに使用されるルーティングキーです。指定しない場合、メッセージは元のルーティングキーを保持します。
    デッドレターメッセージデッドレターエクスチェンジに転送されるメッセージです。トリガーの完全なリストについては、「メッセージがデッドレター化されるタイミング」をご参照ください。
    デッドレターキューデッドレターエクスチェンジにバインドされ、デッドレターメッセージを格納するキューです。

    メッセージがデッドレター化されるタイミング

    以下のいずれかの状況が発生すると、メッセージはデッドレターエクスチェンジに送信されます：

    • 否定応答：コンシューマーが basic.reject または basic.nack を呼び出す際に、requeue を false に設定した場合。

    • リトライ回数の上限超過：16 回のリトライ試行後もメッセージの消費に失敗した場合。詳細については、「消費リトライポリシー」をご参照ください。

    • TTL の期限切れ：メッセージが設定されたメッセージ TTL を超えてキューに留まった場合。詳細については、「メッセージの TTL」をご参照ください。

    仕組み

    1. プロデューサーがエクスチェンジにメッセージを公開します。

    2. エクスチェンジがメッセージをキューにルーティングします。

    3. コンシューマーがキューからメッセージをプルします。

    4. 否定応答、16 回の失敗したリトライ試行、または TTL の期限切れにより、メッセージがデッドレター化されます。

    5. キューは、x-dead-letter-exchange で指定されたエクスチェンジに、x-dead-letter-routing-key で指定されたルーティングキーを使用してデッドレターメッセージを転送します。

    6. デッドレターエクスチェンジは、バインドされたデッドレターキューにメッセージをルーティングします。

    Dead-letter message routing flow

    注意事項

    • 同一 vhost の要件：デッドレターエクスチェンジとそれにバインドされたキューは、同じ vhost 内に存在する必要があります。vhost をまたいだデッドレターのルーティングはサポートされていません。

    • 不変の DLX バインディング：キューがデッドレターエクスチェンジと共に作成されると、その DLX 設定は変更できません。設定を更新するには、キューを削除し、新しい設定で再作成する必要があります。

    • DLX が未設定の場合：キューにデッドレターエクスチェンジが設定されていない場合、最大配信試行回数 (デフォルトでは 16 回) を超えるとメッセージは永久に削除されます。デッドレターエクスチェンジが設定されている場合、メッセージは対応するデッドレターキューにルーティングされます。

    デッドレターエクスチェンジの設定

    デッドレターエクスチェンジは、ApsaraMQ for RabbitMQ コンソール、CreateQueue API、またはクライアント SDK を通じて設定します。

    コンソール

    コンソールでキューを作成する際に、デッドレターエクスチェンジを設定します。

    1. ApsaraMQ for RabbitMQ コンソールにログインします。

    2. 概要 ページの リソース分布 セクションで、リージョンを選択します。

    3. インスタンスリスト ページで、ターゲットインスタンスの名前をクリックします。

    4. 左側のナビゲーションウィンドウで、キューリスト をクリックします。

    5. キューリスト ページで、この vHost の横にある 切り替え ドロップダウンリストから vhost を選択し、[キューの作成] をクリックします。

    6. [キューの作成] パネルで、次のパラメーターを設定し、[OK] をクリックします。

    パラメーター説明
    キュー名キューの名前です。英字、数字、ハイフン (-)、アンダースコア (_)、ピリオド (.)、シャープ記号 (#)、スラッシュ (/)、アットマーク (@) が使用できます。長さは 1～255 文字です。作成後は変更できません。プレフィックス amq. は予約済みのため使用できません。
    [自動削除]最後のコンシューマーが登録を解除した後にキューを自動的に削除するかどうかを指定します。有効な値は true、false です。
    詳細設定クリックして展開します。デッドレターエクスチェンジと関連設定を構成します：
    - DeadLetterExchangeこのキューからデッドレターメッセージを受信するエクスチェンジです。
    - DeadLetterRoutingKeyデッドレターメッセージのルーティングキーです。デッドレターエクスチェンジはこのキーを使用して、一致するデッドレターキューにメッセージをルーティングします。
    - MessageTTLメッセージの TTL (ミリ秒単位) です。この期間内に消費されなかったメッセージはデッドレターメッセージとなり、デッドレターエクスチェンジに転送されます。詳細については、「メッセージの TTL」をご参照ください。

    API

    CreateQueue 操作をデッドレターエクスチェンジのパラメーターと共に呼び出します。詳細については、「CreateQueue」をご参照ください。

    クライアント SDK

    キューを宣言する際に、キューの引数に x-dead-letter-exchange と x-dead-letter-routing-key を指定します。

    以下の Java の例では、some.exchange.name という名前の direct エクスチェンジをデッドレターエクスチェンジとして宣言し、demo-routing-key をデッドレターのルーティングキーとしています：

    channel.exchangeDeclare("some.exchange.name", "direct");

Map<String, Object> args = new HashMap<String, Object>();
args.put("x-dead-letter-exchange", "some.exchange.name");
args.put("x-dead-letter-routing-key", "demo-routing-key");

channel.queueDeclare("MyQueue", false, false, false, args);

    デッドレターメッセージのヘッダー

    メッセージがデッドレター化されると、ApsaraMQ for RabbitMQ はイベント履歴を追跡するためにメタデータヘッダーを追加します。

    サマリーヘッダー

    ヘッダー説明
    x-first-death-exchangeメッセージが最初にデッドレター化されたときに存在したエクスチェンジです。
    x-first-death-queueメッセージが最初にデッドレター化されたときに存在したキューです。
    x-first-death-reasonメッセージが最初にデッドレター化された理由です。
    x-death-totalメッセージがデッドレター化された合計回数です。

    x-death 配列

    x-death ヘッダーはエントリの配列で、各エントリは以下のフィールドを持つデッドレターイベントを記録します：

    フィールド説明
    reasonメッセージがデッドレター化された理由です。
    queueメッセージがデッドレター化されたときに存在したキューです。
    exchangeメッセージがデッドレター化される前に公開されたエクスチェンジです。
    routing-keysデッドレター化された時点でのメッセージのルーティングキーです。
    countこの理由でこのキューからメッセージがデッドレター化された回数です。
    timeメッセージがデッドレター化された日時です。

    デッドレターの理由の値

    値トリガー
    expiredメッセージの TTL が期限切れになりました。
    nackメッセージが requeue を false に設定して否定応答されました。
    rejectメッセージが requeue を false に設定して拒否されました。
    Consumption limit exceeded16 回のリトライ試行後もメッセージの処理に失敗しました。

    デッドレターキューの TTL の有効化

    デフォルトでは、デッドレターキュー内のメッセージは、キューに TTL が設定されていても期限切れになりません。インスタンスレベルで TTL 機能を有効にすると、デッドレターメッセージがキューの TTL 設定に従うようになります。デッドレターメッセージの TTL が期限切れになると、次に設定されているデッドレターエクスチェンジに転送されます。

    サポートされるインスタンスタイプ

    デッドレターキューの TTL 機能は、以下のインスタンスタイプで利用できます：

    • Serverless

    • Enterprise Edition (サブスクリプション)

    • Platinum Edition (サブスクリプション)

    操作手順

    1. ApsaraMQ for RabbitMQ コンソールのインスタンスリストページで、ターゲットインスタンスの名前をクリックします。

    2. インスタンス詳細 ページで、インスタンス制限 タブをクリックします。

    3. デッドレターキューの TTL 機能をサポートしますか の横にある 有効化 をクリックします。

    重要

    • デッドレターのルーティングループを作成しないようにしてください。例えば、キュー A のデッドレターキューがキュー B で、キュー B のデッドレターキューがキュー A の場合、メッセージは無限にループします。ApsaraMQ for RabbitMQ がこのようなループを検出し、拒否イベントがない場合、ループを停止させるために影響を受けるメッセージの TTL を自動的に無効にします。

    • デッドレターメッセージは、キュー間で最大 16 回ルーティングできます。この制限に達すると、影響を受けるメッセージの TTL は無効になります。

    次のステップ