Debug API timeout pada pipeline citra medis jarang disebabkan oleh satu bug tunggal. Dalam praktiknya, timeout biasanya muncul dari kombinasi masalah: payload biner terlalu besar, pekerjaan berat dijalankan sinkron di request path, query metadata lambat, dan antrean worker yang mulai jenuh. Ketika endpoint upload atau inferensi ikut terkena dampak, gejalanya terlihat jelas: latency melonjak, request menumpuk, CPU worker tinggi, dan gateway mulai mengembalikan 504 atau timeout dari sisi client.

Studi kasus ini terinspirasi dari konteks pipeline ultrasound imaging of the brain, tetapi fokus artikel ini sepenuhnya pada rekayasa backend. Tujuannya bukan membahas domain medis, melainkan menjelaskan bagaimana mendiagnosis bottleneck API secara sistematis, menemukan akar masalah yang realistis, lalu merancang perbaikan yang aman untuk sistem produksi.

Gambaran sistem dan gejala awal

Bayangkan sebuah backend menerima dua alur utama:

  • Endpoint upload untuk menerima citra atau frame hasil akuisisi.
  • Endpoint inferensi untuk memulai pemrosesan model atau pipeline analitik lanjutan.

Pada tahap awal, semuanya tampak sederhana: client mengirim file, backend menyimpan data, menulis metadata ke database, lalu meneruskan pekerjaan ke komponen inferensi. Masalah muncul ketika ukuran payload membesar, trafik naik, dan pekerjaan CPU- atau I/O-intensive tetap dilakukan di jalur request sinkron.

Gejala yang biasanya terlihat

  • P95/P99 latency endpoint upload atau inferensi naik tajam.
  • Request aktif menumpuk di application server.
  • Worker selalu sibuk, tetapi throughput tidak naik signifikan.
  • Timeout terjadi di load balancer, reverse proxy, atau client SDK.
  • Antrian job bertambah panjang walaupun autoscaling sudah aktif.
  • Database terlihat normal di rata-rata, tetapi query tertentu lambat dan sporadis.

Pola ini penting: saat request path memuat terlalu banyak pekerjaan sinkron, bottleneck di satu komponen akan memblokir komponen lain. Endpoint upload bisa timeout bukan karena penyimpanan gagal, melainkan karena proses serialisasi, validasi, atau penulisan metadata ikut menahan response terlalu lama.

Root cause yang sering tersembunyi

Pada pipeline citra medis, data yang diproses sering berupa file biner besar atau banyak frame yang dikirim berurutan. Berikut beberapa akar masalah yang masuk akal dan sering muncul bersama-sama.

1. Payload biner besar melewati API secara langsung

Jika client mengirim file besar langsung ke application server, ada beberapa biaya yang tidak selalu terlihat:

  • Proses read request body memakan memori dan waktu I/O.
  • Middleware logging atau observability bisa tanpa sengaja menyalin payload.
  • Proses validasi atau transformasi buffer dapat menggandakan konsumsi memori.
  • Jika data diteruskan lagi ke service lain lewat HTTP, terjadi double transfer.

Masalahnya bukan hanya bandwidth. Setiap penyalinan payload besar di memori bisa memperlambat worker dan memicu garbage collection lebih agresif pada runtime tertentu.

2. Serialisasi berlebih

Kesalahan umum adalah menyimpan metadata dan payload dalam struktur JSON besar, lalu:

  • melakukan encode/decode berulang,
  • menulis field yang sebenarnya tidak dibutuhkan di jalur sinkron,
  • mencatat payload ke log untuk keperluan debug.

Serialisasi berlebih sering tidak terlihat dalam dashboard level tinggi, tetapi bisa sangat mahal pada request dengan ukuran besar. Ini terutama buruk jika body diubah beberapa kali antar layer aplikasi.

3. Query metadata tidak terindeks

Upload atau inferensi sering butuh metadata: studi milik siapa, sesi mana yang aktif, versi model apa yang dipakai, atau status artefak sebelumnya. Jika query ini menggunakan kolom seperti study_id, session_id, created_at, atau kombinasi beberapa filter tanpa indeks yang sesuai, waktu query akan memburuk saat volume data tumbuh.

Yang berbahaya, query metadata kadang hanya memakan ratusan milidetik per request. Angka ini tampak kecil, tetapi pada sistem dengan banyak langkah sinkron, penundaan kecil yang berulang bisa cukup untuk mendorong total waktu respon melewati batas timeout.

4. Antrean sinkron di jalur request

Desain yang tampak rapi bisa jadi bermasalah jika endpoint upload langsung:

  1. menerima file,
  2. menyimpan file,
  3. menulis metadata,
  4. menghasilkan thumbnail atau praproses,
  5. mengantrikan inferensi,
  6. menunggu hasil awal sebelum membalas response.

Begitu satu langkah melambat, semua request aktif ikut menunggu. Ini bukan hanya soal performa rata-rata, tetapi soal head-of-line blocking: pekerjaan berat di satu request mengurangi kapasitas worker untuk request lain.

Langkah investigasi yang efektif

Saat menghadapi API timeout, tebakan tidak cukup. Anda perlu bukti dari log, trace, profil aplikasi, database, dan metrik antrean. Urutan di bawah ini membantu mempersempit masalah dengan cepat.

1. Tambahkan correlation ID end-to-end

Setiap request harus memiliki ID unik yang diteruskan ke seluruh hop: API gateway, app server, queue producer, worker, object storage client, dan database log jika memungkinkan. Tanpa correlation ID, Anda hanya melihat potongan gejala yang terpisah.

Contoh log yang berguna:

{