Immich v3.0.0 memperkenalkan arsitektur worker lebih modular, tetapi beberapa tim mengalami peningkatan latency upload foto karena bottleneck backend. Artikel ini langsung menjelaskan bagaimana menemukan akar masalah latency upload, mulai dari gejala nyata hingga perbaikan praktis tanpa asumsi berlebihan.

Langkah pertama adalah memahami bahwa peningkatan waktu upload tidak selalu berarti masalah jaringan klien: dalam kasus yang diobservasi, bagian backend yang mengantre task penyimpanan dan proses thumbnail tertinggal dibanding throughput pengguna, sehingga upload ter-block selama beberapa detik.

Gejala dan observasi awal

Gejala paling nyata adalah laporan pengguna bahwa file 15–20 MB membutuhkan 6–8 detik untuk selesai, sementara versi sebelumnya stabil di bawah 3 detik. Tim monitoring Immich membawa metrik berikut:

  • Request latency backend meningkat dari rata-rata 850 ms menjadi 2.4 detik.
  • Queue length di Redis Task Queue naik spesifik selama jam sibuk, menunggu worker thumbnail.
  • IOPS storage tetap biasa, menunjukkan upload file ditahan di layer worker bukan storage endpoint.

Analisis awal memerlukan akses ke log backend, misalnya dengan perintah docker compose logs backend --since 10m untuk container lokal atau menggunakan journalctl -u immich-backend.service untuk deployment systemd.

Menelusuri bottleneck upload

1. Menganalisis log dan traces

Perhatikan log yang menandai pemrosesan upload:

2024-09-10T10:23:45.123Z [info] Received upload request for media abc123
2024-09-10T10:23:45.130Z [info] Scheduling task to encode thumbnails
2024-09-10T10:23:47.017Z [info] Thumbnail task finished
2024-09-10T10:23:47.019Z [info] Upload completed

Jeda lebih dari 1.8 detik antara penjadwalan dan selesainya task thumbnail menunjukkan worker belum mengeksekusi segera. Kombinasi log dan tracing, misalnya menggunakan OpenTelemetry, memperlihatkan bahwa worker `immich-thumbnail-queue` menerima job secara batch saat Redis queue kembali kosong.

2. Mengukur kapasitas worker dan queue

Periksa konfigurasi queue di immich-backend/src/config/queue.ts. Versi 3.0.0 memisahkan queue untuk upload dan thumbnail:

const queueConfig = {
  thumbnail: {
    concurrency: parseInt(process.env.THUMBNAIL_WORKERS || '2'),
    defaultJobOptions: { attempts: 3, backoff: { type: 'exponential', delay: 2000 } }
  },
  upload: { concurrency: parseInt(process.env.UPLOAD_WORKERS || '4') }
};

Kritikal bahwa nilai THUMBNAIL_WORKERS disesuaikan dengan beban. Observasi menunjukkan nilai default 2 tidak memadai untuk throughput tinggi; worker mengantri di Redis lebih lama daripada durasi upload payload.

Root cause: konfigurasi storage dan queue worker

Analisis berikut menjelaskan akar masalah:

  1. Staging storage Immich menggunakan disk rotational yang bisa menahan durasi write, tetapi tidak signifikan dibanding jangka waktu job antrian.
  2. Queue thumbnail menumpuk karena concurrency rendah, sementara job upload menangani commit metadata hanya setelah thumbnail selesai.
  3. Redis queue tidak memetakan job ke worker tambahan ketika backlog muncul karena fitur autoscaling belum aktif.

Dengan release v3.0.0, pipeline upload bergantung pada queue worker terpisah karena thumbnail generation dipisah dari upload core, sehingga semua delay queue memblokir end-to-end upload.

Langkah perbaikan praktis

  1. Tambah worker thumbnail di deployment. Sesuaikan environment variable:
THUMBNAIL_WORKERS=5
UPLOAD_WORKERS=4

Perubahan harus dilakukan di file Compose atau deployment manifest agar queue thumbnail mendapatkan worker lebih banyak.

  1. Monitor backoff job dengan immich-thumbnail-queue. Jika job mencoba kembali berkali-kali, itu berarti resource storage tidak responsif atau job thumbnail gagal. Gunakan curl http://localhost:2283/jobs (endpoints internal monitor) untuk melihat status queue.
  2. Perbaiki konfigurasi storage chunk menyesuaikan MAX_UPLOAD_PART_SIZE di backend config jika perlu. Nilai terlalu kecil menyebabkan lebih banyak job chunk yang harus diproses oleh thumb worker.
  3. Perkuat observabilitas dengan memanfaatkan metrics eksport seperti upload_job_duration_seconds dan queue_wait_seconds pada Prometheus supaya bottleneck dimonitor real-time.

Checklist verifikasi sebelum merge

  • Load test ringan: Jalankan skrip upload paralel (misalnya menggunakan artillery quick --count 20 --duration 60) dan pantau queue length.
  • Periksa Redis queue length: redis-cli LLEN immich:queue:thumbnail harus stabil di bawah toleransi (misalnya <50).
  • Monitor latency: Grafana mencatat 95th percentile latency upload turun ke bawah 1.5 detik.
  • Audit logs: Pastikan tidak ada retry timeout dari worker thumbnail di log backend selama window test.
  • Rollback plan: Siapkan konfigurasi worker sebelumnya bila needed.

Penutup

Debugging bottleneck upload di Immich v3.0.0 memberi pelajaran bahwa pemisahan queue worker meningkatkan kompleksitas operasional. Pendekatan observabilitas, pengecekan log, dan optimasi konfigurasi queue menawarkan jalur perbaikan yang dapat diotomasi dalam pipeline CI/CD. Dengan checklist verifikasi di atas, tim dapat memastikan upload tetap responsif sebelum merge perubahan.