STARA INSIGHTS · AEO
Cara Membedakan Error 502 dan 504 di Apache APISIX
Bedakan error 502 dan 504 di Apache APISIX dengan log, waktu respons, status upstream, dan checklist investigasi sebelum mengubah timeout.
Ketika API mengembalikan 502 atau 504 melalui Apache APISIX, mulai dengan mengidentifikasi titik kegagalan dan waktu yang dihabiskan pada setiap bagian perjalanan request. 502 umumnya berarti gateway menerima respons upstream yang tidak valid; 504 berarti gateway tidak menerima respons upstream tepat waktu. Keduanya adalah petunjuk awal, bukan diagnosis akar masalah. Cocokkan log gateway dengan log aplikasi, jaringan, dan metrik pada rentang waktu yang sama sebelum mengubah konfigurasi.
Apa perbedaan 502 dan 504?
Menurut MDN tentang 502, status ini menunjukkan gateway atau proxy menerima respons upstream yang tidak valid. Sebaliknya, 504 menunjukkan respons yang diperlukan tidak diterima tepat waktu. Namun jalur produksi dapat memiliki beberapa proxy, load balancer, dan layanan; kode yang dilihat klien saja tidak selalu menunjukkan komponen mana yang pertama kali gagal.
Karena itu, catat status pada setiap hop dan pastikan dari mana respons berasal. Backend juga bisa mengembalikan respons error yang valid, sehingga penting membedakan error yang diteruskan dari error yang dihasilkan dalam perjalanan request.
Mulai dari satu request yang gagal
Ambil contoh request yang gagal dan satu request berhasil pada route yang sama. Catat waktu beserta zona waktunya, route, metode HTTP, status klien, identifier korelasi jika ada, dan target upstream yang dipilih. Hindari memasukkan token, kredensial, atau isi request sensitif ke tiket dan log.
Bandingkan waktu total request dengan waktu komunikasi upstream yang tersedia dalam konfigurasi observability Anda. Jika waktu total tinggi sementara waktu upstream rendah, telusuri pula antrean, tahap sebelum upstream, transfer data, dan hop lain. Jika waktu upstream tinggi, periksa aplikasi dan dependency-nya. Ini hipotesis investigasi: definisi metrik dan titik pengukurannya perlu dicek agar tidak salah menyimpulkan.
Dokumentasi plugin Prometheus APISIX menjelaskan metrik dan label yang tersedia. Periksa versi, konfigurasi plugin, serta cakupan metrik di lingkungan Anda sebelum mengandalkan nama atau satuannya. Kelompokkan error berdasarkan route dan upstream, lalu bandingkan laju request, latensi, dan perubahan jumlah error pada periode insiden.
Telusuri jalur 502
Mulailah dari error log gateway dan status upstream. Contoh yang perlu diuji meliputi koneksi ditolak, koneksi terputus, target atau port keliru, kegagalan TLS, serta respons yang tidak dapat diproses. Periksa apakah masalah terjadi pada semua node atau hanya satu node; bandingkan juga dengan perubahan deployment dan konfigurasi terbaru. Kemungkinan ini bukan daftar penyebab yang pasti untuk setiap 502.
Dokumentasi Debug Function APISIX menjelaskan header diagnostik X-APISIX-Upstream-Status pada mode dan contoh yang didokumentasikan. Header tersebut dapat membantu menelusuri sumber status dan percobaan upstream, tetapi ketersediaan dan interpretasinya harus diverifikasi pada versi serta konfigurasi yang digunakan. Jangan mengaktifkan kemampuan debug secara luas tanpa mempertimbangkan informasi yang terekspos.
Periksa pula daftar node dan health check. Node yang terlihat sehat dari satu lokasi belum tentu dapat dijangkau dari gateway melalui jalur jaringan yang sama. Lakukan pengujian dari lingkungan yang memiliki izin dan jalur yang sesuai, tanpa mengekspos endpoint internal ke publik.
Telusuri jalur 504
Temukan batas waktu yang benar-benar tercapai: klien, load balancer, gateway, atau komponen lain. Dokumentasi Admin API APISIX menjelaskan pengaturan timeout upstream untuk koneksi, pengiriman, dan pembacaan. Nilai dan perilaku aktual perlu diperiksa pada versi dan konfigurasi deployment; jangan menganggap satu angka sebagai batas total seluruh proses.
Selanjutnya periksa log aplikasi dan dependency pada request yang sama: waktu antrean, eksekusi, koneksi database, panggilan layanan lain, dan kapasitas worker. Jika aplikasi belum menerima request, fokuskan pemeriksaan pada jalur sebelum aplikasi. Jika aplikasi masih memproses setelah gateway berhenti menunggu, pastikan dampak operasinya diketahui sebelum mengulang request.
Menaikkan timeout bisa memberi ruang bagi operasi yang memang sah dan lambat, tetapi juga membuat koneksi menunggu lebih lama dan menyembunyikan bottleneck. Turunkan atau naikkan hanya setelah kebutuhan bisnis, kapasitas, dan batas pada seluruh hop dipahami. Untuk pekerjaan yang durasinya tidak dapat diprediksi, pertimbangkan proses asynchronous dengan status yang dapat diperiksa, jika sesuai kontrak aplikasi.
Ilustrasi: respons terlambat pada transaksi
Sebagai ilustrasi, sebuah layanan menerima permintaan pembuatan transaksi. Gateway berhenti menunggu dan mengembalikan 504, tetapi aplikasi menyelesaikan transaksi beberapa saat kemudian. Pengguna menekan tombol ulang dan transaksi kedua berisiko terbentuk. Sebaliknya, 504 juga dapat terjadi sebelum operasi dimulai; status itu sendiri tidak membuktikan hasil transaksi.
Sebelum retry, periksa status menggunakan identitas transaksi dan rancang idempotency pada operasi yang mengubah data. Untuk konteks desain retry, baca panduan timeout, retry, dan idempotency. Hindari retry otomatis tanpa batas karena dapat menambah beban pada sistem yang sedang bermasalah.
Checklist investigasi untuk tim
- Tentukan dampak: route, konsumen, rentang waktu, proporsi gagal, dan perubahan terbaru.
- Cocokkan ID korelasi, timestamp, status, node, dan percobaan upstream antarlog.
- Bandingkan request gagal dengan request berhasil; lihat distribusi latensi, bukan hanya rata-rata.
- Periksa konektivitas, TLS, health check, kapasitas, antrean, serta dependency sesuai bukti.
- Petakan timeout setiap hop dan identifikasi batas yang tercapai.
- Pastikan operasi aman diulang dan tetapkan batas retry sesuai kontrak layanan.
- Uji perubahan pada lingkungan yang aman, pantau dampaknya, dan siapkan rollback.
Untuk perubahan konfigurasi gateway, gunakan juga checklist pengujian dan rollback.
FAQ
Apakah 502 selalu berarti aplikasi upstream mati?
Tidak. Kode tersebut tidak cukup untuk memastikan penyebabnya. Periksa asal respons, koneksi, konfigurasi, dan log aplikasi untuk membedakan node yang tidak tersedia dari masalah lain.
Apakah menaikkan timeout pasti menyelesaikan 504?
Tidak. Itu dapat membantu bila batasnya terlalu pendek untuk pekerjaan yang memang wajar, tetapi tidak memperbaiki antrean, dependency lambat, atau kapasitas yang tidak cukup. Ukur titik keterlambatan terlebih dahulu.
Metrik apa yang sebaiknya dilihat lebih dulu?
Mulai dari jumlah dan proporsi 502/504 per route, latensi request dan upstream, serta node yang terdampak. Cocokkan dengan log dan metrik aplikasi pada waktu yang sama. Pastikan definisi metrik sesuai versi dan konfigurasi Anda.
Apakah request yang berakhir 504 aman langsung diulang?
Belum tentu. Upstream mungkin sudah memprosesnya. Periksa status operasi dan gunakan mekanisme idempotency untuk operasi yang memiliki efek samping.
Langkah berikutnya
Jika tim Anda membutuhkan bantuan meninjau alur API, dependency, dan pendekatan integrasi, pelajari layanan API & System Integration StaraSolution. Penanganan akhir tetap perlu disesuaikan dengan arsitektur, versi APISIX, dan bukti dari lingkungan Anda.