Jika rilis Spring Boot menyebabkan error rate naik, latensi memburuk, readiness gagal, atau resource server jenuh, tim tidak boleh berdebat terlalu lama antara memperbaiki di tempat atau mundur ke versi stabil. Dalam banyak kasus production, rollback cepat yang terukur lebih aman daripada mencoba patch darurat saat sistem sedang tidak sehat.

Artikel ini adalah panduan praktis runbook rollback rilis gagal dengan Micrometer untuk tim backend dan DevOps. Fokusnya adalah cara membaca sinyal utama dari Micrometer dan Actuator, kapan rollback perlu dilakukan, bagaimana melakukan rollback berbasis artefak atau container tag, bagaimana memvalidasi hasil rollback, dan kapan perlu menerapkan deploy freeze agar masalah tidak melebar.

Apa tujuan runbook rollback?

Runbook rollback bukan sekadar daftar perintah. Tujuannya adalah membuat respons insiden menjadi cepat, konsisten, dan rendah ambiguitas. Saat produksi bermasalah, waktu biasanya habis untuk mencari tahu siapa yang berwenang, metrik mana yang harus dilihat, dan versi mana yang aman untuk dipulihkan. Runbook yang baik mengurangi keputusan improvisasi di saat kritis.

Untuk konteks rilis Spring Boot, runbook rollback minimal harus menjawab pertanyaan berikut:

  • Kapan rollback dilakukan?
  • Siapa yang mengambil keputusan dan mengeksekusi?
  • Metrik apa yang menjadi sinyal utama?
  • Versi stabil terakhir yang akan dipakai apa?
  • Bagaimana memverifikasi rollback berhasil?
  • Kapan deploy berikutnya harus dibekukan?

Struktur runbook insiden yang disarankan

1. Trigger insiden

Definisikan pemicu yang jelas agar rollback tidak dilakukan hanya berdasarkan perasaan. Trigger umum:

  • Error rate HTTP 5xx naik tajam setelah deploy.
  • Latency p95/p99 memburuk signifikan dibanding baseline.
  • Readiness probe gagal pada banyak instance.
  • Saturation meningkat, misalnya thread pool, connection pool, CPU, atau memory pressure.
  • Alarm dari dashboard atau alerting berbunyi dalam window waktu dekat setelah rilis.

2. Peran saat insiden

  • Incident commander: memutuskan langkah dan menjaga fokus tim.
  • Operator deploy: menjalankan rollback.
  • Observer: memantau metrik, log, dan dampak bisnis.
  • Recorder: mencatat timeline singkat untuk postmortem.

3. Sumber kebenaran operasional

Runbook harus menyebutkan secara eksplisit lokasi berikut:

  • Dashboard observability untuk metrik Micrometer.
  • Endpoint Actuator yang diizinkan untuk diagnosis.
  • Registry artefak atau image container.
  • Sistem CI/CD atau tool deploy.
  • Log agregasi untuk korelasi error.

4. Jalur keputusan

Keputusan yang paling sering memakan waktu adalah: tunggu beberapa menit lagi atau rollback sekarang? Karena itu, tentukan aturan sederhana:

  • Jika gejala muncul segera setelah deploy dan memburuk, prioritaskan rollback.
  • Jika hanya satu instance bermasalah dan versi lama juga terdampak, investigasi infrastruktur lebih dulu.
  • Jika error bersifat data-dependent atau terkait migrasi skema, rollback aplikasi saja mungkin tidak cukup.

Catatan: Runbook harus membedakan antara kegagalan aplikasi, kegagalan dependensi, dan perubahan data yang tidak kompatibel. Rollback kode tidak selalu menyelesaikan rollback data.

Sinyal utama dari Micrometer dan Actuator yang wajib dipantau

Pada situasi rilis gagal, jangan membuka semua metrik sekaligus. Fokus pada empat sinyal inti: error rate, latency, saturation, dan readiness. Ini cukup untuk mengambil keputusan awal dengan cepat.

Error rate

Micrometer umumnya mengekspos metrik HTTP server yang dapat dipakai untuk melihat lonjakan 5xx atau 4xx tidak normal. Error rate tinggi pasca deploy sering menjadi indikator paling kuat bahwa regresi ada di layer aplikasi atau integrasi.

Yang perlu diperhatikan:

  • Apakah 5xx naik tepat setelah rilis?
  • Apakah error terkonsentrasi pada endpoint tertentu?
  • Apakah semua pod/instance terdampak atau hanya sebagian?

Latency

Error rate tidak selalu naik saat aplikasi rusak. Kadang aplikasi tetap merespons, tetapi menjadi sangat lambat akibat query memburuk, deadlock ringan, retry beruntun, atau pool menunggu. Karena itu lihat latency p95 atau p99, bukan hanya rata-rata.

Perhatikan juga:

  • Latency naik bersamaan dengan throughput normal.
  • Timeout di upstream atau client meningkat.
  • Antrian internal bertambah sebelum error muncul.

Saturation

Saturation menjawab apakah aplikasi mulai kehabisan kapasitas operasional. Dalam konteks Spring Boot, sinyal yang berguna biasanya:

  • Penggunaan connection pool database.
  • Thread pool executor yang penuh.
  • CPU tinggi berkepanjangan.
  • Garbage collection yang mulai memengaruhi respons.

Saturation penting karena rollback mungkin tertunda jika sistem sudah terlalu sibuk. Jika rollback butuh pull image atau restart instance, resource yang sempit bisa memperlambat pemulihan.

Readiness

Readiness menentukan apakah instance layak menerima trafik. Banyak insiden menjadi lebih parah karena aplikasi technically up tetapi sebenarnya tidak siap: koneksi ke database belum stabil, cache primer gagal, atau dependency kritis belum tersedia.

Dengan Spring Boot Actuator, readiness sebaiknya diperlakukan sebagai sinyal operasional, bukan formalitas. Jika banyak instance gagal readiness setelah deploy, rollback sering lebih tepat daripada menunggu lama.

Contoh konfigurasi Spring Boot Actuator dan Micrometer

Berikut contoh konfigurasi yang relevan untuk eksposur endpoint health, metrics, dan probe. Sesuaikan endpoint yang dibuka dengan kebijakan keamanan internal.

management.endpoints.web.exposure.include=health,info,metrics,prometheus
management.endpoint.health.show-details=when_authorized
management.endpoint.health.probes.enabled=true
management.health.readinessstate.enabled=true
management.health.livenessstate.enabled=true
management.metrics.tags.application=my-service

Jika menggunakan Prometheus untuk scraping metrik Micrometer:

management.prometheus.metrics.export.enabled=true

Contoh endpoint yang biasanya dipakai saat insiden:

  • /actuator/health
  • /actuator/health/readiness
  • /actuator/metrics
  • /actuator/prometheus

Untuk menambah health indicator sederhana yang memverifikasi dependensi penting, misalnya koneksi ke layanan internal atau status komponen kritis, Anda bisa membuat indikator sendiri. Gunakan hanya untuk dependensi yang benar-benar memengaruhi kesiapan menerima trafik.

import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.HealthIndicator;
import org.springframework.stereotype.Component;

@Component
public class CriticalDependencyHealthIndicator implements HealthIndicator {
    @Override
    public Health health() {
        boolean dependencyOk = checkCriticalDependency();
        if (dependencyOk) {
            return Health.up().withDetail("dependency", "reachable").build();
        }
        return Health.down().withDetail("dependency", "unreachable").build();
    }

    private boolean checkCriticalDependency() {
        // Implementasi harus cepat dan tidak mahal.
        // Hindari query berat atau panggilan jaringan yang memperlambat health check.
        return true;
    }
}

Catatan penting: Jangan memasukkan terlalu banyak pemeriksaan mahal ke readiness. Health check yang lambat atau rapuh bisa menjadi sumber masalah baru saat deploy.

Verifikasi sebelum rollback: jangan terlalu cepat, tapi jangan terlalu lama

Rollback cepat itu baik, tetapi rollback yang salah sasaran hanya menambah gangguan. Lakukan verifikasi singkat, idealnya dalam beberapa menit pertama setelah alarm berbunyi.

Checklist verifikasi sebelum rollback

  1. Korelasi waktu: apakah degradasi dimulai tepat setelah rilis?
  2. Scope dampak: semua instance versi baru terdampak atau hanya satu node?
  3. Bandingkan versi: apakah instance versi lama tetap sehat?
  4. Periksa readiness: apakah instance baru gagal siap menerima trafik?
  5. Cek log error utama: exception dominan, timeout, koneksi database, serialisasi, atau dependency?
  6. Cek perubahan non-kode: konfigurasi, secret, environment variable, atau migrasi database yang ikut berubah.
  7. Validasi artefak target rollback: versi stabil terakhir memang tersedia dan pernah lulus production.

Jika hasil verifikasi menunjukkan regresi jelas setelah deploy, jangan menunda rollback hanya untuk mencari akar masalah lengkap. Akar masalah bisa dibahas setelah layanan stabil.

Kapan rollback tidak langsung menyelesaikan masalah?

  • Rilis menyertakan perubahan skema database yang tidak kompatibel ke belakang.
  • Konfigurasi production berubah bersamaan dengan deploy aplikasi.
  • Dependency eksternal sedang outage.
  • Masalah dipicu beban trafik, bukan versi aplikasi.

Pada kasus ini, rollback tetap mungkin perlu dilakukan, tetapi ekspektasinya harus realistis: rollback aplikasi belum tentu memulihkan layanan sepenuhnya.

Langkah rollback berbasis artefak atau container tag

Prinsip utamanya sederhana: rollback ke artefak yang sudah diketahui stabil, bukan membangun ulang dari branch lama saat insiden berlangsung. Build ulang berisiko menghasilkan artefak berbeda karena dependency, environment CI, atau perubahan pipeline.

Pendekatan 1: rollback berbasis artefak

Jika deployment menggunakan berkas JAR atau paket release, simpan identitas artefak yang dirilis, misalnya versi build atau commit yang terasosiasi dengan release.

Contoh alur umum:

  1. Identifikasi versi stabil terakhir dari catatan release.
  2. Ambil artefak dari registry atau storage internal.
  3. Deploy ulang artefak tersebut ke environment production.
  4. Monitor readiness dan metrik inti segera setelah service kembali up.

Contoh pseudo-command yang umum secara konsep:

# contoh konseptual, sesuaikan dengan tool internal
releasectl deploy --service my-service --artifact my-service-1.2.3.jar

Pendekatan 2: rollback berbasis container tag

Pada sistem berbasis container, rollback biasanya lebih cepat jika tag image stabil sudah tercatat dan masih tersedia di registry.

Contoh alur umum:

  1. Temukan tag image rilis stabil terakhir.
  2. Update manifest atau parameter deploy agar kembali ke tag tersebut.
  3. Jalankan redeploy.
  4. Pastikan pod atau instance baru lulus readiness sebelum dianggap pulih.

Contoh pseudo-command:

# contoh konseptual, sesuaikan dengan orchestrator dan pipeline
releasectl rollback --service my-service --image registry.example.com/my-service:1.2.3

Praktik penting saat rollback

  • Gunakan tag immutable jika memungkinkan. Hindari tag yang dapat dipindahkan seperti latest.
  • Catat mapping antara commit, build, dan image tag.
  • Simpan release notes singkat yang menyebut perubahan konfigurasi dan migrasi.
  • Pastikan rollback tidak memicu perubahan tambahan yang tidak relevan.

Kesalahan umum: melakukan rollback dengan membangun ulang commit lama. Secara operasional ini lambat dan bisa menghasilkan perilaku berbeda dari rilis yang dulu stabil.

Validasi pasca-rollback

Rollback selesai bukan berarti insiden selesai. Tim harus membuktikan bahwa sistem benar-benar kembali ke kondisi aman.

Checklist validasi pasca-rollback

  1. Readiness pulih: seluruh instance utama lulus readiness.
  2. Error rate turun: 5xx kembali mendekati baseline.
  3. Latency membaik: p95/p99 bergerak turun, bukan hanya sesaat.
  4. Saturation mereda: thread pool, connection pool, CPU, dan memory kembali wajar.
  5. Fungsi bisnis kritis berhasil diuji cepat, misalnya login, create order, atau endpoint utama.
  6. Log error baru tidak menunjukkan pola kegagalan yang sama.
  7. Alert berhenti menembak atau severity turun.

Jika rollback sukses tetapi metrik masih buruk, kemungkinan penyebabnya bukan hanya versi aplikasi. Lanjutkan investigasi ke konfigurasi, data, dependensi, atau kapasitas infrastruktur.

Kapan perlu freeze deploy?

Deploy freeze perlu diterapkan ketika perubahan tambahan justru berisiko mengaburkan diagnosis atau memperparah gangguan. Freeze bukan langkah berlebihan; ini mekanisme untuk menahan variabel baru sampai sistem stabil.

Indikasi kuat untuk freeze deploy

  • Sudah terjadi rollback tetapi akar masalah belum jelas.
  • Beberapa layanan terkait menunjukkan gejala serupa setelah rangkaian rilis.
  • Tim sedang menangani insiden aktif dengan dampak bisnis tinggi.
  • Terdapat perubahan konfigurasi atau migrasi yang belum diverifikasi.

Kapan freeze bisa dicabut?

  • Layanan sudah stabil dalam window observasi yang disepakati.
  • Metrik utama kembali ke baseline operasional.
  • Penyebab sementara sudah dipahami minimal pada level hipotesis kuat.
  • Tindakan pencegahan langsung sudah diterapkan, misalnya menonaktifkan feature flag bermasalah atau memperbaiki release gate.

Checklist operasional singkat saat rilis gagal

Checklist 10 menit pertama

  • Konfirmasi waktu deploy terakhir.
  • Buka dashboard error rate, latency, saturation, readiness.
  • Bandingkan instance versi baru vs versi lama.
  • Cek log exception dominan.
  • Tentukan apakah rollback memenuhi kriteria.
  • Verifikasi artefak atau tag rollback tersedia.
  • Tunjuk satu operator untuk eksekusi rollback.

Checklist saat rollback berjalan

  • Umumkan versi yang akan dipulihkan.
  • Pastikan tidak ada deploy lain yang berjalan bersamaan.
  • Monitor readiness setiap instance yang kembali naik.
  • Catat timestamp rollback dimulai dan selesai.

Checklist setelah rollback

  • Validasi endpoint bisnis kritis.
  • Pastikan alarm mereda.
  • Kumpulkan timeline singkat.
  • Putuskan apakah deploy freeze diperlukan.
  • Buat tiket investigasi lanjutan.

Pencegahan agar rollback lebih jarang dibutuhkan

Rollback tetap perlu disiapkan, tetapi kualitas operasional yang baik bertujuan mengurangi frekuensi penggunaannya. Beberapa tindakan pencegahan berikut paling realistis diterapkan pada tim Spring Boot tanpa menambah kompleksitas berlebihan.

1. Feature flag

Jika perubahan perilaku bisnis dapat dipisahkan dari deploy teknis, feature flag memberi opsi mematikan fitur tanpa merilis ulang. Ini sangat berguna untuk perubahan yang berisiko tetapi tidak menyentuh kontrak sistem inti.

Trade-off-nya: feature flag menambah kompleksitas logika dan perlu dikelola agar tidak menjadi utang teknis.

2. Health indicator yang relevan

Tambahkan health indicator hanya untuk dependensi yang benar-benar menentukan kesiapan layanan. Ini membantu mencegah instance bermasalah menerima trafik terlalu dini.

Kesalahan umum adalah membuat health indicator terlalu agresif atau mahal sehingga menimbulkan false negative.

3. Release gate

Release gate adalah pemeriksaan wajib sebelum production atau sebelum menyelesaikan rollout, misalnya:

  • Smoke test endpoint kritis.
  • Validasi konfigurasi wajib tersedia.
  • Pemeriksaan migrasi database sudah sesuai urutan.
  • Dashboard metrik dasar sudah hijau selama beberapa menit pertama.

Release gate tidak harus rumit. Yang penting adalah memblokir rilis yang jelas-jelas belum siap.

4. Catatan rilis yang operasional

Release notes sebaiknya tidak hanya berisi daftar fitur. Tambahkan informasi operasional:

  • Perubahan konfigurasi.
  • Perubahan skema atau migrasi.
  • Dependensi baru.
  • Endpoint atau job yang terdampak.
  • Langkah rollback khusus jika ada.

5. Baseline observability yang konsisten

Dashboard dan alert harus konsisten lintas layanan agar tim tidak belajar ulang saat insiden. Minimal setiap layanan Spring Boot punya panel untuk error rate, latency, saturation, dan readiness.

Debugging tips saat rollback tidak berjalan mulus

  • Rollback sukses tetapi readiness tetap gagal: cek secret, environment variable, konektivitas dependency, dan health indicator kustom.
  • Error turun tapi latency tetap tinggi: periksa antrean pekerjaan, koneksi database, cache warm-up, dan thread pool.
  • Hanya sebagian instance pulih: bandingkan node atau host yang gagal, bisa jadi masalah infrastruktur lokal.
  • Versi lama juga rusak: curigai perubahan data, dependency outage, atau konfigurasi global.
  • Metrik tidak cukup jelas: korelasikan dengan log agregat dan timestamp deploy secara presisi.

Template postmortem singkat

Postmortem tidak harus panjang. Untuk insiden rollback rilis gagal, format singkat berikut sudah cukup berguna:

Judul insiden:
Layanan:
Tanggal/waktu:
Dampak bisnis:

Timeline:
- HH:MM deploy versi X
- HH:MM error rate naik
- HH:MM keputusan rollback
- HH:MM rollback selesai
- HH:MM metrik kembali stabil

Gejala utama:
- Error rate:
- Latency:
- Readiness:
- Saturation:

Akar masalah sementara / final:

Mengapa lolos ke production:

Apa yang berjalan baik saat respons insiden:

Apa yang perlu diperbaiki:
- Runbook:
- Observability:
- Release gate:
- Testing:
- Konfigurasi:

Action items:
- [owner] [aksi] [target waktu]

Tujuan postmortem singkat ini adalah memastikan insiden menghasilkan perbaikan nyata, bukan sekadar dokumentasi formal.

Penutup

Spring Boot: Runbook Rollback Rilis Gagal dengan Micrometer pada dasarnya adalah disiplin operasional: tentukan sinyal yang benar, ambil keputusan cepat, rollback ke artefak yang sudah tervalidasi, lalu pastikan pemulihan terbukti lewat metrik dan health check. Micrometer dan Actuator memberi fondasi observability yang cukup kuat, asalkan tim menyepakati metrik inti, checklist, dan jalur eskalasi yang jelas.

Jika tim Anda sering ragu saat production mulai merah setelah deploy, perbaikan terbesar biasanya bukan pada tool baru, melainkan pada runbook yang lebih konkret, release gate yang lebih ketat, dan catatan rilis yang lebih operasional.