Modul 06 — Ketika Terjadi Masalah | Kursus EUDR Forest Analyzer

Diagnosis Kegagalan Umum Langkah demi Langkah

Setiap sistem pasti mengalami kegagalan. Perbedaan antara sistem yang baik dan sistem yang rapuh adalah seberapa cepat Anda dapat menemukan dan memperbaiki masalahnya. Telusuri lima mode kegagalan paling umum di Forest Analyzer, pelajari gejala, akar penyebab, dan perbaikan untuk masing-masing.

Langkah 1

Kegagalan Autentikasi GEE

Ini adalah error paling umum. Jika GEE_SERVICE_ACCOUNT_KEY_FILE tidak ada atau kredensial telah kedaluwarsa, semua analisis gagal. Tidak ada bagian lain dalam pipeline yang dapat mengkompensasi — analyzer memunculkan:

"Forest analysis requires Google Earth Engine for accurate data."

Titik kegagalan tunggal ini memengaruhi perhitungan cakupan hutan, peringatan GLAD, peringatan RADD, analisis NDVI, citra satelit, dan klasifikasi tutupan lahan. Semua yang bergantung pada GEE berhenti bekerja sekaligus.

Daftar periksa debugging:

Periksa .env — apakah GEE_SERVICE_ACCOUNT=true sudah diatur?
Apakah file kunci di GEE_SERVICE_ACCOUNT_KEY_FILE benar-benar ada di disk?
Buka file kunci — apakah JSON-nya valid? (Unduhan yang terpotong adalah penyebab umum.)
Apakah service account telah diberi akses ke proyek GEE yang ditentukan di GEE_PROJECT_ID?
Periksa log startup untuk "Provider initialized successfully" vs "Provider initialization failed".

Teratasi ketika: Log startup backend menampilkan "Provider initialized successfully" dan analisis uji coba selesai tanpa pesan error GEE.

Langkah 2

Kehabisan Pool Koneksi Database

Sistem memelihara pool berisi 15 koneksi database. Ketika semuanya sedang digunakan, permintaan baru beralih ke koneksi langsung yang lebih lambat. Anda akan melihat ini di log:

"Connection pool exhausted, creating direct connection."

Ini bukan crash total — ini adalah degradasi halus. Tetapi ini menandakan bahwa sistem menerima beban lebih dari yang diharapkan, atau ada kebocoran koneksi.

Daftar periksa debugging:

Periksa pengaturan DB_POOL_SIZE dan DB_MAX_OVERFLOW di .env.
Cari kebocoran koneksi — jalur kode di mana koneksi diambil tetapi tidak pernah dikembalikan ke pool.
Periksa apakah analisis berjalan sangat lama, menahan koneksi tetap terbuka.
Pantau jumlah permintaan bersamaan — lonjakan lalu lintas mungkin hanya melebihi kapasitas.

Teratasi ketika: Pesan log "pool exhausted" berhenti muncul pada beban normal. Menaikkan DB_POOL_SIZE atau memperbaiki kebocoran koneksi menyelesaikan masalah.

Langkah 3

Analisis Macet

Sebuah analisis tetap berstatus PROCESSING selama lebih dari 30 menit. Ini biasanya berarti permintaan GEE timeout atau proses worker crash di tengah analisis.

Sistem memiliki watchdog bawaan: job latar belakang stuck_analysis_fixer berjalan setiap 2 menit. Ia menemukan analisis yang macet di status PROCESSING lebih dari 30 menit dan meresetnya ke PENDING untuk percobaan ulang otomatis. Setelah 3 kali percobaan ulang gagal, analisis ditandai sebagai ERROR.

Daftar periksa debugging:

Query tabel antrian: SELECT status, retry_count, error_message FROM analysis_queue WHERE id = '...'
Periksa log worker — apakah worker crash atau kehilangan koneksi GEE?
Verifikasi GEE merespons (log startup atau permintaan uji coba manual).
Jika retry_count sudah mencapai 3, fixer telah menyerah. Investigasi manual diperlukan.

Teratasi ketika: Analisis berhasil diselesaikan pada percobaan ulang, atau Anda mengidentifikasi dan menyelesaikan masalah GEE/jaringan yang mendasarinya lalu mencoba ulang secara manual melalui POST /api/queue/retry/{queue_id}.

Langkah 4

Error ImageCollection vs Image

Anda melihat error GEE ini di log:

"Image.load: Asset 'X' is not an Image."

Penyebab: Dua dataset kunci adalah ImageCollection, bukan Image tunggal:

Peringatan RADD: projects/radar-wur/raddalert/v1
ESA WorldCover: ESA/WorldCover/v200

Jika Anda mencoba memuat salah satunya dengan ee.Image("..."), GEE menolaknya karena aset tersebut berisi beberapa gambar, bukan satu.

Perbaikan: Gunakan ee.ImageCollection("...").first() untuk WorldCover, atau filter dan komposit untuk RADD:

# RADD: filter berdasarkan tanggal, pilih band Alert, lalu komposit
radd = ee.ImageCollection("projects/radar-wur/raddalert/v1")  \
    .filterBounds(geometry)  \
    .filterDate(start_date, end_date)  \
    .select('Alert').max()

# WorldCover: ambil gambar pertama (dan biasanya satu-satunya)
worldcover = ee.ImageCollection("ESA/WorldCover/v200").first()

Teratasi ketika: Error "Asset is not an Image" menghilang dan analisis mengembalikan data peringatan/tutupan lahan yang valid.

Langkah 5

Email Tidak Terkirim

Seorang pengguna mendaftar tetapi tidak pernah menerima email aktivasi. Atau analisis selesai tetapi email notifikasi tidak sampai. Ini sering kali masalah konfigurasi, bukan bug kode.

Daftar periksa debugging:

Periksa folder spam/junk pengguna terlebih dahulu — email otomatis sering masuk ke sana.
Verifikasi kredensial SMTP di .env: SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASSWORD.
Jika menggunakan Gmail, SMTP_PASSWORD harus berupa password khusus aplikasi, bukan password akun. Gmail memblokir login dari "aplikasi yang kurang aman" secara default.
Periksa log email_service di backend untuk error pengiriman atau timeout koneksi.
Uji dengan POST /api/auth/resend-activation untuk memicu email baru dan amati lognya.

Teratasi ketika: Endpoint resend-activation mengembalikan sukses dan pengguna menerima email dalam beberapa menit.

Resep Debugging

Prosedur cepat dan terarah untuk memeriksa aspek-aspek spesifik kesehatan sistem.

Cara memeriksa apakah queue worker berjalan

Queue worker dimulai secara otomatis dalam fungsi startup_event() ketika server backend diluncurkan. Cari baris ini di log backend:

"Queue worker started"

Jika server di-restart, worker ikut restart bersamanya — tidak ada proses terpisah yang perlu dikelola. Jika baris log tersebut tidak ada, worker gagal dimulai. Periksa error import atau masalah konfigurasi di analysis_queue_worker.py.

Cara mencoba ulang analisis yang gagal secara manual

Kirim permintaan POST ke endpoint retry:

POST /api/queue/retry/{queue_id}

Ini mereset status job dari FAILED atau ERROR kembali ke PENDING dan menambah hitungan percobaan ulang. Queue worker akan mengambilnya pada siklus polling berikutnya. Gunakan GET /api/queue/status/{queue_id} untuk memantau progresnya setelah itu.

Cara memeriksa konektivitas GEE

Lihat log startup backend untuk pesan inisialisasi provider:

# Berhasil:
"Provider initialized successfully"

# Gagal:
"Provider initialization failed"

Jika provider gagal diinisialisasi, semua fitur yang bergantung pada GEE (analisis hutan, peringatan, citra, NDVI, tutupan lahan) tidak akan tersedia. Periksa path GEE_SERVICE_ACCOUNT_KEY_FILE dan kredensialnya.

Cara menemukan mengapa analisis tertentu gagal

Panggil endpoint status: GET /api/queue/status/{queue_id}. Responsnya menyertakan field error_message dengan alasan kegagalan.
Untuk detail lebih lanjut, query database secara langsung: SELECT id, status, error_message, retry_count, updated_at FROM analysis_queue WHERE id = 'xxx'
Cocokkan timestamp updated_at dengan log backend untuk stack trace lengkap.

Cara menambah batas koneksi database

Atur nilai-nilai ini di file .env Anda:

DB_POOL_SIZE=10
DB_MAX_OVERFLOW=20

Ini memberi Anda 10 koneksi pool ditambah hingga 20 koneksi overflow (total 30). Pastikan juga max_connections PostgreSQL di sisi server cukup tinggi untuk mengakomodasi ini — default biasanya 100, yang seharusnya cukup untuk sebagian besar deployment.

Pola Ketahanan

Bagaimana Forest Analyzer menangani kegagalan secara terencana, bukan secara kebetulan.

Self-Healing dengan Stuck Analysis Fixer

🔄

Pola Watchdog

Sebuah thread latar belakang aktif setiap 2 menit dan meng-query database untuk analisis yang macet di status PROCESSING lebih dari 30 menit. Ketika menemukannya, ia mereset status ke PENDING sehingga queue worker mencoba ulang secara otomatis. Setelah 3 kali percobaan ulang gagal, analisis ditandai sebagai ERROR — pada titik itu, masalahnya persisten dan memerlukan investigasi manusia.

Ini adalah pola watchdog: monitor independen yang menangkap masalah yang tidak dapat dideteksi oleh sistem utama tentang dirinya sendiri. Queue worker tidak tahu bahwa ia crash — tetapi stuck analysis fixer menyadari bahwa pekerjaan tidak pernah selesai.

Degradasi Halus

Beberapa subsistem dirancang untuk gagal secara independen tanpa menjatuhkan seluruh aplikasi:

Fallback connection pool: Ketika pool habis, sistem membuat koneksi langsung (lebih lambat) alih-alih menolak permintaan secara langsung.
Hasil kosong dari provider: Ketika provider GEE gagal mengambil citra satelit atau data peringatan, ia mengembalikan objek hasil kosong alih-alih memunculkan exception. Laporan PDF tetap dihasilkan — hanya melewatkan bagian yang datanya hilang.
Alert scheduler opsional: Jika alert scheduler gagal dimulai, sisa sistem tetap berjalan normal. Pengguna kehilangan pemeriksaan peringatan berkala, tetapi analisis sesuai permintaan tetap berfungsi.
Pengiriman email: Jika SMTP salah konfigurasi, hasil analisis tetap disimpan ke database. Pengguna dapat mengambilnya dari API meskipun email notifikasi tidak pernah sampai.

Setiap subsistem gagal secara independen lebih baik daripada seluruh sistem crash. Sistem lebih memilih hasil parsial daripada tidak ada hasil sama sekali.

Pola Pikir Debugging: Ikuti Jalur Data

Ketika sesuatu rusak, telusuri jalur data melalui sistem:

Browser → API endpoint → Service → Layanan eksternal → Database → Respons

Kerusakan hampir selalu terjadi di batas — di mana satu sistem berkomunikasi dengan sistem lain. Batas-batas ini adalah tempat kredensial kedaluwarsa, jaringan timeout, dan format data tidak cocok.

Tiga kategori kegagalan paling umum:

Kredensial kedaluwarsa: Kunci service account GEE, token JWT, password SMTP. Perbaikannya selalu di .env atau file kunci.
Timeout jaringan: Permintaan GEE melalui koneksi lambat, query database pada geometri besar. Perbaikannya biasanya menambah timeout atau mengurangi ukuran payload.
Ketidakcocokan format data: ImageCollection vs Image, GeoJSON tidak valid, field null yang tidak diharapkan. Perbaikannya ada di kode yang menyiapkan atau mengonsumsi data.

Uji Pemahaman Anda

Pertanyaan 1

Seorang pengguna melaporkan analisis mereka telah "memproses" selama 2 jam. Apa penjelasan yang paling mungkin?

Pertanyaan 2

Laporan PDF berhasil dihasilkan tetapi tidak berisi citra satelit. Data analisis itu sendiri benar. Apa yang akan Anda periksa?

Pertanyaan 3

Anda melihat "Expected a homogeneous image collection" di log GEE. Apa perbaikannya?

Referensi Pemecahan Masalah

Error Umum

Error	Penyebab	Perbaikan
`Forest analysis requires GEE`	Kredensial GEE hilang atau tidak valid	Periksa `GEE_SERVICE_ACCOUNT_KEY_FILE` di `.env`
`Connection pool exhausted`	Terlalu banyak permintaan bersamaan	Naikkan `DB_POOL_SIZE` / `DB_MAX_OVERFLOW`
`Image.load: Asset is not an Image`	Memuat ImageCollection sebagai Image	Gunakan `.first()` atau filter + `.max()`
`Expected homogeneous collection`	Tipe gambar campuran di RADD	`.select('Alert')` sebelum `.max()`
`Invalid email or password`	Akun belum diaktivasi	Periksa email aktivasi / kirim ulang
`Activation link expired`	Token lebih dari 24 jam	Kirim ulang email aktivasi

Layanan Latar Belakang

Layanan	Interval	Tujuan
Alert Scheduler	24 jam (06:00 UTC)	Memeriksa plot yang berlangganan untuk peringatan deforestasi baru
Stuck Analysis Fixer	2 menit	Menyelamatkan analisis yang macet di status PROCESSING
Queue Worker	Polling berkelanjutan	Memproses job analisis yang tertunda

Titik Pemeriksaan Kesehatan

Apa	Cara Memeriksa
Database	`GET /api/docs` — jika Swagger UI dimuat, database sudah terhubung
Provider GEE	Periksa log startup untuk `"Provider initialized successfully"`
Queue Worker	Periksa log untuk `"Queue worker started"`
Email (SMTP)	Kirim uji coba melalui `POST /api/auth/resend-activation`
Alert Scheduler	Periksa log atau panggil `get_scheduler_status()`