Debug Insiden VPS Produksi dengan Claude Code

Situsnya hidup, deploy melaporkan sukses, dan halaman di browser tertinggal dua versi. Tidak ada yang salah di log aplikasi, karena memang tidak ada yang salah di aplikasinya. Insiden itu selesai dalam dua puluh menit dengan bantuan agen dan akan memakan satu jam kalau saya sendirian, tetapi ia juga menunjukkan persis di mana melepas agen di mesin produksi bisa berakhir buruk.

Ini metode kerja yang akhirnya saya pakai: apa yang sebaiknya dilakukan agen saat insiden, apa yang harus dicegah, dan urutan bukti yang menjaga kami berdua tetap jujur.

Di mana agen benar-benar membantu

Penanganan insiden sebagian besar adalah pengumpulan bukti di bawah tekanan waktu, dan itu cocok bagi sesuatu yang bisa menjalankan sepuluh perintah sementara Anda memikirkan yang kesebelas.

• Keluasan. Ia memeriksa container, ikatan port, tabel proses, disk, dan masa berlaku sertifikat dalam waktu yang Anda butuhkan untuk mengingat item ketiganya.
• Daya ingat. Ia membaca workflow deploy, konfigurasi reverse proxy, dan berkas compose sekaligus, dan di sanalah kontradiksinya biasanya bersembunyi.
• Narasi. Diminta menyatakan hipotesis sebelum bertindak, ia menghasilkan jejak tertulis yang menjadi postmortem secara cuma-cuma.

Yang tidak ia kuasai adalah mengetahui kapan dirinya keliru. Hipotesis keliru yang percaya diri ditambah akses shell adalah cara insiden kecil menjadi besar, dan karena itulah pagar pengaman di bawah ini bukan opsional.

Aturan satu: berhenti bertanya kepada CDN

Kalau sebuah situs berada di belakang CDN atau proxy cache, hal pertama yang harus dipastikan adalah lapisan mana yang menjawab. Respons dari edge memberi tahu apa yang diingat edge, bukan apa yang sedang dilakukan aplikasi, dan berjam-jam bisa hilang untuk men-debug kode yang sudah benar.

# Rule one of debugging a site behind a CDN: stop asking the CDN.
curl -sI https://www.example.com/ | head -20            # what the world sees
curl -sI --resolve www.example.com:443:127.0.0.1 \
     https://www.example.com/ | head -20                 # what the origin says

# If those disagree, the bug is in the cache layer and no amount of
# reading application code will find it.

# Same discipline for the redirect chain, which hides a surprising
# number of "the site is down" reports.
curl -sIL http://example.com/ | grep -E '^(HTTP|location:)'

Disiplin yang sama berlaku untuk rantai redirect dan nama host. Aturan yang mengarahkan domain telanjang ke host www, atau aplikasi yang hanya mendengarkan salah satunya, menghasilkan gejala yang tampak seperti gangguan padahal sebenarnya konfigurasi. Menelusuri rantainya secara eksplisit mengubah misteri menjadi satu baris keluaran.

Insidennya: deploy yang sukses dan tidak mengubah apa pun

Inilah kasus yang paling banyak mengajari saya, disusun ulang dari perintah-perintah yang benar-benar penting. Aplikasinya berjalan di container, pipeline deploy-nya hijau, dan konten yang disajikan basi.

# The incident: a deploy "succeeded", the site kept serving old content.
# The evidence that mattered, in the order it was gathered:

docker compose ps                    # container up, restarts: 0
docker compose logs --tail=100 web   # no errors, no recent boot line
ss -tlnp | grep :3000                # PID owning the port is the OLD process
curl -s localhost:3000/ | grep -o 'build-[a-z0-9]*'   # old build id

# Root cause: the new process failed to bind because the previous one had
# never exited. The deploy script only checked that its own command
# returned zero, so it reported success while nothing had changed.

Pelajarannya berlaku jauh melampaui tumpukan teknologi ini. Skrip deploy yang hanya memeriksa exit code-nya sendiri sedang mengukur hal yang salah: yang penting adalah apakah proses yang berjalan adalah proses yang baru. Sejak itu setiap deploy saya diakhiri dengan menegaskan bahwa pengenal build yang disajikan lewat HTTP cocok dengan yang baru saja dibangun — pemeriksaan dua baris yang akan mengubah insiden ini menjadi pipeline yang gagal.

Empat kebiasaan bukti yang layak ditegakkan

Ini instruksi yang saya simpan di berkas memori proyek agar berlaku di setiap sesi insiden tanpa perlu diketik ulang.

• Nyatakan hipotesis sebelum menjalankan apa pun yang mengubah keadaan, dan sebutkan observasi yang akan menggugurkannya.
• Rekam sebelum mengubah. Salin log, daftar proses, dan konfigurasi ke direktori kerja lebih dulu, karena perintah berikutnya bisa menghapusnya.
• Verifikasi di lapisan yang Anda curigai, bukan di lapisan yang nyaman. Curl origin-nya, kueri basis datanya langsung, baca berkas di server alih-alih di repositori.
• Curigai perkakas yang menjadi perantara. Wrapper yang menulis ulang perintah, atau checkout lokal yang mirip dengan yang remote, bisa diam-diam melaporkan keadaan sistem yang salah — kesalahan yang pernah saya buat dan kini saya periksa secara eksplisit.

Kebiasaan terakhir itu layak dieja karena pernah menghasilkan kesimpulan palsu bagi saya: keluaran yang tampak menggambarkan repositori remote ternyata menggambarkan yang lokal, dan saya memercayai sebuah merge yang sebenarnya tidak pernah terjadi.

Hook adalah mekanisme pengaman yang sesungguhnya

Dialog izin melindungi Anda selama Anda membacanya. Saat insiden tak seorang pun membacanya, dan justru saat itulah Anda menginginkan aturan yang tidak bisa dibujuk. Hook PreToolUse yang memeriksa perintah lalu menolak sedikit daftar operasi yang tak bisa dibatalkan adalah asuransi termurah yang tersedia.

// A PreToolUse hook is the difference between an assistant that can
// investigate production and one that can break it. This one refuses
// the small set of commands nobody should run during an incident.
#!/bin/bash
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command')

if echo "$cmd" | grep -Eq 'rm -rf /|docker system prune|DROP TABLE|truncate '; then
  echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse",
    "permissionDecision":"deny",
    "permissionDecisionReason":"destructive command blocked during incident"}}'
  exit 0
fi
echo '{}'

Pasangkan dengan mode izin yang dipilih sengaja untuk sesi itu. Investigasi berjalan hanya-baca; begitu perbaikannya disepakati, itu menjadi sesi terpisah yang lebih sempit dengan perubahan yang ditinjau manusia sebelum dijalankan. Mencampur investigasi dan remediasi dalam satu sesi longgar adalah persiapan untuk insiden kedua.

Lingkar penanganan insiden yang bekerja

Enam langkah, dalam urutan ini, setiap kali.

1. Tetapkan gejalanya secara presisi, dari luar sistem: URL mana, respons apa, mulai jam berapa.
2. Bandingkan edge dan origin. Kalau berbeda, berhenti dan kerjakan lapisan cache-nya.
3. Pastikan apa yang benar-benar berjalan: image, pengenal build, proses, pemilik port.
4. Baca tiga konfigurasi yang menentukan jalurnya — proxy, container, aplikasi — bersamaan, bukan satu per satu.
5. Nyatakan hipotesisnya, buat perubahan sekecil mungkin yang mengujinya, lalu verifikasi di origin.
6. Tuliskan temuannya sebelum adrenalinnya reda, lalu ubah menjadi sebuah pemeriksaan otomatis.

Langkah keenam itulah yang berbunga. Hampir setiap insiden yang saya alami dua kali adalah insiden yang kejadian pertamanya menghasilkan perbaikan tanpa pemeriksaan, dan perbaikan tanpa pemeriksaan adalah ingatan yang punya masa kedaluwarsa.

Mengubah temuan menjadi pagar pengaman

Keluaran sebuah insiden seharusnya paling tidak satu penegasan otomatis, bukan hanya satu paragraf. Insiden deploy basi menjadi pemeriksaan pengenal build setelah deploy. Insiden cache menjadi permintaan sintetis yang melewati edge. Insiden disk penuh menjadi ambang alarm yang berbunyi sebelum layanannya berbunyi.

Di sinilah agen justru layak berperan setelah insiden alih-alih saat insiden: menulis pemeriksaannya, alarmnya, dan entri runbook-nya adalah persis pekerjaan membosankan dan terspesifikasi jelas yang ia kerjakan dengan andal, tepat pada momen ketika Anda terlalu lelah mengerjakannya dengan baik.

Agen AI memangkas separuh pengumpulan bukti dari sebuah insiden secara dramatis dan menambah risiko pada separuh tindakannya. Pisahkan kedua separuh itu — investigasi hanya-baca dengan perintah merusak diblokir, lalu perubahan yang disengaja dan ditinjau — dan Anda mendapat kecepatannya tanpa membeli gangguan kedua.