Ikhtisar dead-letter exchange - ApsaraMQ for RabbitMQ - Alibaba Cloud Documentation Center

Pesan terkadang gagal—konsumen menolaknya, upaya pengiriman ulang habis, atau waktu hidup (TTL) berakhir. Alih-alih kehilangan pesan tersebut, dead-letter exchange (DLX) menangkapnya dan mengarahkannya ke antrian khusus untuk pemeriksaan, pemrosesan ulang, atau peringatan.

Bagian berikut mencakup konsep utama, proses routing, metode konfigurasi, serta header pesan dead-letter untuk ApsaraMQ for RabbitMQ.

Konsep utama

Term	Definisi
Dead-letter exchange	Exchange yang menerima pesan dead-letter dan mengarahkannya ke antrian dead-letter berdasarkan binding key, routing key, dan atribut header. Tipe exchange standar apa pun — direct, fanout, topic, atau headers — dapat berfungsi sebagai dead-letter exchange.
Dead-letter routing key	Routing key yang digunakan untuk mengarahkan pesan dead-letter. Jika tidak ditentukan, pesan mempertahankan routing key aslinya.
Dead-letter message	Pesan yang diteruskan ke dead-letter exchange. Lihat Kapan pesan menjadi dead-letter untuk daftar lengkap pemicunya.
Dead-letter queue	Antrian yang di-bind ke dead-letter exchange dan menyimpan pesan dead-letter.

Kapan pesan menjadi dead-letter

Pesan dikirim ke dead-letter exchange ketika salah satu kondisi berikut terjadi:

Negative acknowledgment — Konsumen memanggil basic.reject atau basic.nack dengan parameter requeue diatur ke false.
Retry exhaustion — Pesan gagal dikonsumsi setelah 16 kali percobaan ulang. Untuk detailnya, lihat Consumption retry policies.
TTL expiration — Pesan berada di antrian lebih lama dari TTL yang dikonfigurasi. Untuk detailnya, lihat Message TTL.

Cara kerja

Produsen memublikasikan pesan ke exchange.
Exchange mengarahkan pesan ke antrian.
Konsumen mengambil pesan dari antrian.
Pesan menjadi dead-letter—melalui negative acknowledgment, setelah 16 kali percobaan ulang gagal, atau ketika TTL-nya berakhir.
Antrian meneruskan pesan dead-letter ke exchange yang ditentukan oleh x-dead-letter-exchange, menggunakan routing key yang ditentukan oleh x-dead-letter-routing-key.
Dead-letter exchange mengarahkan pesan ke antrian dead-letter yang di-bind.

Catatan penggunaan

Persyaratan vhost yang sama — Dead-letter exchange dan antrian yang di-bind-nya harus berada dalam vhost yang sama. Routing dead-letter lintas-vhost tidak didukung.
Binding DLX yang tidak dapat diubah — Setelah antrian dibuat dengan dead-letter exchange, konfigurasi DLX tidak dapat diubah. Hapus antrian tersebut dan buat yang baru dengan konfigurasi yang diperbarui.
Tidak ada DLX yang dikonfigurasi — Jika antrian tidak memiliki dead-letter exchange yang dikonfigurasi, pesan akan dihapus secara permanen setelah jumlah maksimum upaya pengiriman (16 secara default) terlampaui. Jika dead-letter exchange dikonfigurasi, pesan akan diarahkan ke antrian dead-letter yang sesuai.

Konfigurasi dead-letter exchange

Siapkan dead-letter exchange melalui Konsol ApsaraMQ for RabbitMQ, API CreateQueue, atau SDK client.

Konsol

Konfigurasikan dead-letter exchange saat membuat antrian di Konsol.

Masuk ke Konsol ApsaraMQ for RabbitMQ.
Pada halaman Overview, di bagian Resource Distribution, pilih wilayah.
Pada halaman Instances, klik nama instans target.
Di panel navigasi sebelah kiri, klik Queues.
Pada halaman Queues, pilih vhost dari daftar drop-down Change di samping vhost, lalu klik Create Queue.
Di panel Create Queue, atur parameter berikut, lalu klik OK.

Parameter	Deskripsi
Queue Name	Nama antrian. Mendukung huruf, angka, tanda hubung (`-`), garis bawah (`_`), titik (`.`), tanda pagar (`#`), garis miring maju (`/`), dan tanda @ (`@`). Panjang: 1 hingga 255 karakter. Tidak dapat diubah setelah dibuat. Awalan `amq.` dicadangkan dan tidak dapat digunakan.
Auto Delete	Apakah antrian akan dihapus secara otomatis setelah konsumen terakhir berhenti berlangganan. Nilai yang valid: `true`, `false`.
Advanced Settings	Klik untuk membuka. Konfigurasikan dead-letter exchange dan pengaturan terkait:
- DeadLetterExchange	Exchange yang menerima pesan dead-letter dari antrian ini.
- DeadLetterRoutingKey	Routing key untuk pesan dead-letter. Dead-letter exchange menggunakan kunci ini untuk mengarahkan pesan ke antrian dead-letter yang sesuai.
- MessageTTL	TTL pesan dalam milidetik. Pesan yang tidak dikonsumsi dalam periode ini akan menjadi pesan dead-letter dan diteruskan ke dead-letter exchange. Untuk detailnya, lihat Message TTL.

API

Panggil operasi CreateQueue dengan parameter dead-letter exchange. Untuk detailnya, lihat CreateQueue.

Client SDK

Tentukan x-dead-letter-exchange dan x-dead-letter-routing-key dalam argumen antrian saat mendeklarasikan antrian.

Contoh Java berikut mendeklarasikan exchange direct bernama some.exchange.name sebagai dead-letter exchange dengan demo-routing-key sebagai dead-letter 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);

Header pesan dead-letter

Saat pesan menjadi dead-letter, ApsaraMQ for RabbitMQ menambahkan header metadata untuk melacak riwayat event tersebut.

Header ringkasan

Header	Deskripsi
`x-first-death-exchange`	Exchange tempat pesan berada saat pertama kali menjadi dead-letter.
`x-first-death-queue`	Antrian tempat pesan berada saat pertama kali menjadi dead-letter.
`x-first-death-reason`	Alasan pesan pertama kali menjadi dead-letter.
`x-death-total`	Jumlah total kali pesan menjadi dead-letter.

Array x-death

Header x-death adalah array entri, masing-masing mencatat event dead-letter dengan bidang-bidang berikut:

Bidang	Deskripsi
`reason`	Mengapa pesan menjadi dead-letter.
`queue`	Antrian tempat pesan berada saat menjadi dead-letter.
`exchange`	Exchange tempat pesan dipublikasikan sebelum menjadi dead-letter.
`routing-keys`	Routing key pesan pada saat menjadi dead-letter.
`count`	Berapa kali pesan menjadi dead-letter dari antrian ini karena alasan ini.
`time`	Kapan pesan menjadi dead-letter.

Nilai alasan dead-letter

Nilai	Pemicu
`expired`	TTL pesan berakhir.
`nack`	Pesan di-negative acknowledge dengan `requeue` diatur ke `false`.
`reject`	Pesan ditolak dengan `requeue` diatur ke `false`.
`Consumption limit exceeded`	Pesan gagal setelah 16 kali percobaan ulang.

Aktifkan TTL untuk antrian dead-letter

Secara default, pesan dalam antrian dead-letter tidak kedaluwarsa, meskipun antrian tersebut memiliki TTL yang dikonfigurasi. Aktifkan fitur TTL di tingkat instans agar pesan dead-letter mengikuti pengaturan TTL antrian. Saat TTL pesan dead-letter berakhir, pesan tersebut akan diteruskan ke dead-letter exchange berikutnya yang dikonfigurasi.

Tipe instans yang didukung

Fitur TTL untuk antrian dead-letter tersedia pada tipe instans berikut:

Serverless
Enterprise Edition (Subscription)
Platinum Edition (Subscription)

Prosedur

Pada halaman Instances di Konsol ApsaraMQ for RabbitMQ, klik nama instans target.
Pada halaman Instance Details, klik tab Limits.
Klik Activate di samping TTL Feature Supported.

Penting

Hindari membuat loop routing dead-letter. Misalnya, jika antrian dead-letter Antrian A adalah Antrian B dan antrian dead-letter Antrian B adalah Antrian A, pesan akan berputar tanpa henti. Jika ApsaraMQ for RabbitMQ mendeteksi loop semacam ini tanpa event penolakan, sistem secara otomatis menonaktifkan TTL untuk pesan yang terpengaruh guna menghentikan loop tersebut.
Pesan dead-letter dapat diarahkan antar-antrian maksimal 16 kali. Setelah mencapai batas ini, TTL dinonaktifkan untuk pesan yang terpengaruh.

Langkah selanjutnya

Manage exchanges — Hapus dead-letter exchange atau bind antrian dead-letter ke dead-letter exchange.
Message TTL — Atur waktu kedaluwarsa pada pesan.
Consumption retry policies — Konfigurasikan perilaku pengulangan sebelum pesan menjadi dead-letter.