Pengujian Canary API: Deteksi Rilis Bermasalah Sebelum Pengguna Merasakannya

Anda menggabungkan PR. CI berwarna hijau. Proses deploy selesai tanpa satu pun error di log. Dua puluh menit kemudian, tiket dukungan mulai berdatangan: sebuah endpoint pembayaran mengembalikan kode 500 untuk sebagian pelanggan, dan Anda tidak tahu mengapa karena tidak ada yang gagal dalam pipeline.

Inilah celah yang ditutup oleh pengujian canary. Uji unit dan uji integrasi memeriksa kode Anda terhadap apa yang Anda harapkan. Keduanya tidak dapat memeriksa kode Anda terhadap dunia nyata: lalu lintas produksi, basis data sebenarnya, API pihak ketiga yang diam-diam mengubah batas kecepatannya pada hari Selasa lalu. Pengujian canary mendorong rilis baru ke sebagian kecil lalu lintas nyata terlebih dahulu, mengamati perilakunya, dan hanya memperluas peluncuran setelah sinyal terlihat sehat. Jika ada yang rusak, itu akan rusak untuk 2% pengguna selama dua menit, bukan 100% pengguna selama satu jam.

Khusus untuk API, Anda bisa melakukan lebih baik daripada hanya mengamati dashboard dan berharap. Anda dapat menjalankan serangkaian uji nyata terhadap canary saat ia tayang, menegaskan kode status, skema respons, dan latensi, lalu mengizinkan peluncuran berdasarkan hasilnya. Itulah alur kerja yang dijelaskan panduan ini, dan kami akan menyatukannya secara menyeluruh dengan Apidog dan runner baris perintahnya sehingga seluruh proses ini berada di dalam pipeline CI/CD Anda yang sudah ada.

Apa sebenarnya pengujian canary itu

Nama ini berasal dari burung kenari di tambang batu bara. Para penambang membawa burung yang dikurung ke bawah tanah karena burung itu bereaksi terhadap gas beracun jauh sebelum manusia. Jika burung itu berhenti bernyanyi, Anda keluar. Rilis canary bekerja dengan cara yang sama: sampel kecil yang dapat dikorbankan mengambil risiko terlebih dahulu sehingga pengguna Anda yang lain tidak perlu mengalaminya.

Dalam praktiknya, penerapan canary berarti menjalankan dua versi layanan Anda secara bersamaan:

• Stabil: versi produksi saat ini, melayani sebagian besar lalu lintas.
• Canary: versi baru, melayani persentase kecil (seringkali 1% hingga 5% sebagai permulaan).

Load balancer, service mesh, atau ingress controller membagi lalu lintas di antara keduanya. Anda mengamati tingkat kesalahan (error rate), latensi, dan metrik bisnis canary dibandingkan dengan baseline stabil. Jika canary bertahan, Anda mengalihkan lebih banyak lalu lintas kepadanya secara bertahap hingga ia melayani 100% dan menjadi versi stabil yang baru. Jika memburuk, Anda mengarahkan semuanya kembali ke versi stabil dan rilis yang buruk tidak akan pernah mencapai sebagian besar audiens Anda.

Pengujian canary adalah bagian aktif dari putaran tersebut. Daripada menunggu lalu lintas organik untuk memunculkan bug, Anda meluncurkan serangkaian permintaan API yang disengaja ke canary dan memeriksa responsnya. Pemantauan pasif memberi tahu Anda bahwa ada yang salah setelah pengguna mengalaminya. Pengujian canary aktif memberi tahu Anda bahwa ada yang salah sebelum Anda memperluas radius dampak.

Pengujian canary vs. pengujian yang sudah Anda lakukan

Pengujian canary tidak menggantikan pengujian Anda yang lain. Ia berada di akhir rantai dan menangkap kelas kegagalan yang berbeda.

Alasan pengujian canary mendapatkan tempatnya: sebagian besar insiden produksi berasal dari hal-hal yang tidak dapat sepenuhnya direproduksi oleh lingkungan pra-produksi. Variabel lingkungan yang hilang. Pengaturan kumpulan koneksi yang kedaluwarsa. Indeks basis data yang ada di staging tetapi tidak di produksi. Dependensi hilir yang berperilaku berbeda di bawah otentikasi nyata. Kode Anda benar; lingkungan di sekitarnya tidak. Pengujian canary adalah pertama kalinya rilis baru Anda bertemu dengan lingkungan tersebut, dan Anda ingin menghadapinya dengan dua persen lalu lintas, bukan seluruhnya.

Jika Anda ingin konteks yang lebih luas tentang di mana ini cocok, panduan kami tentang cara mengotomatiskan uji API di CI/CD mencakup tahapan hulu, dan uji smoke vs uji regresi menjelaskan dua jenis uji yang paling diandalkan oleh canary.

Apa yang harus diukur pada canary

Canary hanya berguna jika Anda tahu seperti apa kondisi "sehat" itu. Pilih serangkaian sinyal kecil dan bandingkan canary dengan baseline stabil, bukan dengan angka mutlak. Tingkat kesalahan 1,2% mungkin normal untuk layanan Anda; yang penting adalah apakah canary secara signifikan lebih buruk daripada versi stabil saat ini.

Empat sinyal mencakup sebagian besar kasus:

1. Tingkat kesalahan (Error rate): bagian dari respons 5xx, dan seringkali 4xx yang seharusnya tidak terjadi, seperti lonjakan mendadak 401 setelah perubahan otentikasi. Ini adalah metrik terpenting.
2. Latensi: p95 dan p99, bukan rata-rata. Rata-rata menyembunyikan "ekor lambat" di mana pengguna nyata merasakan masalah. Canary yang 40ms lebih lambat pada p99 adalah peringatan bahkan jika rata-rata terlihat baik.
3. Kebenaran respons: apakah body masih cocok dengan skema? Respons 200 OK yang mengembalikan bentuk yang salah lebih buruk daripada 500, karena pemantauan tidak akan menyorotinya.
4. Sinyal bisnis: keberhasilan checkout, keberhasilan login, item yang ditambahkan ke keranjang. Ini menangkap regresi logika yang secara teknis merupakan respons HTTP yang "berhasil".

Tiga yang pertama dapat Anda tegaskan langsung dalam uji API. Itulah bagian yang akan kami otomatiskan.

Alur kerja pengujian canary, langkah demi langkah

Berikut adalah bentuk peluncuran canary yang dijaga oleh uji API otomatis. Setiap langkah adalah sesuatu yang dapat Anda jalankan dari pipeline.

1. Terapkan versi baru sebagai canary bersama dengan versi stabil.
2. Arahkan sebagian kecil lalu lintas (misalnya 5%) ke canary.
3. Jalankan serangkaian uji API otomatis terhadap endpoint canary.
4. Amati tingkat kesalahan dan latensi selama periode "bake" yang singkat.
5. Pintu gerbang: jika uji lulus dan metrik tetap dalam batas, alihkan lebih banyak lalu lintas. Jika tidak, lakukan rollback.
6. Ulangi peningkatan (5% menjadi 25% menjadi 50% menjadi 100%), uji ulang pada setiap langkah.
7. Promosikan canary menjadi stabil, hentikan versi lama.

Dua bagian yang patut Anda perhatikan adalah langkah 3 (rangkaian uji) dan langkah 5 (pintu gerbang). Lakukan keduanya dengan benar, dan sisanya adalah "plumbing" yang sudah disediakan platform Anda.

Membangun rangkaian uji di Apidog

Rangkaian uji adalah jantung dari pengujian canary, dan di sinilah sebagian besar tim mengabaikan detail. Sebuah "uji" canary yang hanya melakukan ping ke /health dan memeriksa 200 memberitahu Anda bahwa proses telah dimulai. Ini tidak memberitahu Anda apa pun tentang apakah endpoint Anda yang sebenarnya berfungsi.

Rangkaian canary yang sebenarnya melatih jalur-jalur yang penting: mengotentikasi, membaca, menulis, dan memverifikasi bentuk respons pada setiap langkah. Skenario uji Apidog memungkinkan Anda merangkai permintaan-permintaan tersebut, meneruskan data di antaranya, dan menegaskan hasilnya tanpa menulis kode penghubung.

Skenario canary yang solid untuk API e-commerce terlihat seperti ini:

• Langkah 1, otentikasi. POST /auth/login dengan akun uji. Tegaskan 200, ekstrak token dari respons ke dalam variabel.
• Langkah 2, baca. GET /products?limit=10 dengan token. Tegaskan 200, tegaskan bahwa respons adalah array, tegaskan setiap item memiliki id, name, dan price.
• Langkah 3, tulis. POST /cart dengan produk yang diketahui. Tegaskan 201, tegaskan bahwa total keranjang yang dikembalikan sesuai dengan nilai yang diharapkan.
• Langkah 4, verifikasi status. GET /cart. Tegaskan bahwa item yang baru saja Anda tambahkan ada.

Di Apidog, Anda membuat setiap permintaan sekali, lalu menambahkan penegasan secara visual. Untuk pemeriksaan skema, Anda dapat memvalidasi respons terhadap skema OpenAPI yang sudah Anda rancang, sehingga body respons yang menyimpang secara otomatis menggagalkan uji. Untuk penyerahan token otentikasi, Anda mengekstraknya dari respons langkah 1 dan mereferensikannya sebagai variabel di langkah-langkah selanjutnya. Tidak diperlukan scripting untuk kasus umum, dan Anda dapat menggunakan post-processor JavaScript saat Anda memerlukan logika kustom.

Manfaatnya adalah skenario yang sama ini berjalan dalam tiga cara dari satu definisi: secara manual saat Anda membangunnya, sesuai jadwal sebagai pemantauan sintetik setelah tayang, dan dari baris perintah di dalam pipeline canary Anda. Anda menulis penegasan sekali.

Menjalankan rangkaian uji dari baris perintah

Untuk mengizinkan penerapan, rangkaian uji harus berjalan tanpa GUI (headless) di CI. Apidog menyediakan CLI untuk tujuan ini. Instal di agen build Anda:

npm install -g apidog-cli

Ekspor data skenario uji Anda dari Apidog sebagai file berformat CLI, atau arahkan runner ke skenario berdasarkan ID menggunakan token akses, lalu jalankan:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t "$CANARY_SCENARIO_ID" \
  -e "$CANARY_ENV_ID" \
  -r cli,html,junit

Beberapa flag yang perlu diketahui untuk pekerjaan canary:

• -t, --test-scenario menjalankan skenario spesifik berdasarkan ID. Gunakan -f, --test-scenario-folder untuk menjalankan seluruh folder skenario.
• -e, --environment memilih lingkungan runtime. Arahkan ini ke lingkungan yang URL dasarnya adalah endpoint canary Anda, sehingga uji yang sama dapat mengenai canary, staging, atau produksi dengan menukar satu nilai.
• -r, --reporters mengontrol output. cli mencetak ke konsol, html menghasilkan laporan yang dapat dibagikan, dan junit mengeluarkan XML yang dapat diuraikan secara native oleh GitHub Actions, GitLab, Jenkins, dan sebagian besar dashboard CI untuk menampilkan lulus/gagal per uji.
• -d, --iteration-data menjalankan rangkaian uji sekali per baris file CSV atau JSON. Berguna untuk mengenai canary dengan beberapa profil pengguna atau ID produk dalam satu kali jalan.
• --upload-report mendorong ringkasan jalankan kembali ke Apidog sehingga tim dapat melihat riwayat canary di aplikasi.

CLI keluar dengan kode non-nol saat penegasan gagal. Kode keluar tersebut adalah seluruh mekanisme penjagaan: pipeline Anda sudah tahu cara berhenti pada langkah yang gagal, jadi uji canary yang gagal menghentikan peluncuran secara otomatis.

Untuk panduan lebih mendalam tentang menjalankan Apidog di pipeline, cara mengotomatiskan uji API di GitHub Actions dan panduan integrasi Jenkins membahas platform tersebut secara detail.

Menghubungkannya ke CI/CD

Berikut adalah contoh pekerjaan GitHub Actions yang disederhanakan yang menerapkan canary, mengujinya, dan hanya mempromosikannya setelah berhasil. Struktur ini dapat diterapkan ke GitLab CI, CircleCI, atau Jenkins dengan sedikit perubahan sintaks.

name: canary-release

on:
  push:
    branches: [main]

jobs:
  canary:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Deploy canary (5% traffic)
        run: ./deploy.sh --canary --weight 5

      - name: Install Apidog CLI
        run: npm install -g apidog-cli

      - name: Test the canary
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t "$CANARY_SCENARIO_ID" \
            -e "$CANARY_ENV_ID" \
            -r cli,junit
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
          CANARY_SCENARIO_ID: ${{ vars.CANARY_SCENARIO_ID }}
          CANARY_ENV_ID: ${{ vars.CANARY_ENV_ID }}

      - name: Bake and watch (2 min)
        run: sleep 120 && ./check-metrics.sh --service canary --max-error-rate 1.0

      - name: Promote canary to 100%
        run: ./deploy.sh --promote

      - name: Roll back on any failure
        if: failure()
        run: ./deploy.sh --rollback

Logika yang menjadikannya canary daripada penerapan biasa adalah urutannya. Canary mengambil sebagian lalu lintas sebelum uji berjalan, sehingga uji tersebut melatih rilis yang sudah melayani permintaan nyata. Langkah if: failure() adalah jaring pengaman: jika rangkaian uji keluar dengan kode non-nol, atau pemeriksaan metrik terpicu, pekerjaan gagal dan rollback berjalan sebelum lalu lintas pernah meningkat melewati 5%.

Pastikan CANARY_ENV_ID menunjuk ke lingkungan Apidog yang URL dasarnya menargetkan canary. Ketika Anda kemudian ingin menjalankan rangkaian uji yang sama sebagai uji smoke produksi pasca-deploy, Anda cukup mengganti ID lingkungan produksi dan tidak mengubah yang lain. Reusabilitas itu intinya: satu rangkaian uji, banyak tahapan.

Kesalahan umum yang membuat pengujian canary tidak berguna

• Menguji endpoint yang salah. Jika uji Anda mengenai URL publik yang di-load-balance, permintaan tersebut mungkin mendarat di instance stabil, bukan canary. Arahkan uji secara eksplisit ke canary, baik melalui header yang digunakan oleh mesh, nama host canary khusus, atau lingkungan yang URL dasarnya adalah alamat canary.
• Periode "bake" nol. Beberapa kegagalan hanya muncul di bawah beban yang berkelanjutan: kebocoran memori, kelelahan kumpulan koneksi, cache yang terisi penuh. Jalankan uji, lalu amati selama beberapa menit sebelum mempromosikan. Canary yang langsung lulus dan dipromosikan dalam sepuluh detik hampir tidak bisa disebut canary.
• Tidak ada rollback otomatis. Jika manusia harus menyadari kegagalan dan mengklik rollback, Anda telah mempertahankan bagian paling lambat dari respons insiden dalam siklus. Nilai utamanya adalah pipeline melakukan rollback dengan sendirinya. Hubungkan rollback ke kondisi kegagalan dan uji bahwa rollback berfungsi.
• Ambang batas absolut, bukan perbandingan. "Gagal jika tingkat kesalahan di atas 1%" akan rusak pada hari ketika tingkat kesalahan baseline Anda secara sah 1,5%. Bandingkan canary dengan versi stabil saat ini, dan picu pintu gerbang ketika canary secara signifikan lebih buruk, bukan ketika ia melampaui angka yang Anda pilih beberapa bulan yang lalu.
• Penegasan yang tipis. Respons 200 dengan body yang salah format akan lolos pemeriksaan kode status saja dan gagal bagi pengguna Anda. Tegaskan pada skema respons, bukan hanya kodenya. Di sinilah merancang kontrak API Anda terlebih dahulu dan memvalidasi respons terhadap skema memberikan manfaat langsung: uji canary Anda mewarisi kontrak secara gratis.

Seberapa luas seharusnya canary, dan untuk berapa lama?

Tidak ada jawaban universal, tetapi default yang dapat diterapkan untuk sebagian besar tim:

• Mulai dengan 5% lalu lintas. Cukup kecil untuk membatasi kerusakan, cukup besar untuk mendapatkan sinyal nyata dalam hitungan menit pada layanan yang sibuk. API dengan lalu lintas rendah mungkin memerlukan jendela yang lebih lama untuk mengumpulkan permintaan yang cukup.
• Meningkatkan secara bertahap: 5% menjadi 25% menjadi 50% menjadi 100%. Jalankan ulang rangkaian uji pada setiap langkah. Regresi yang tersembunyi pada 5% kadang-kadang muncul pada 50% ketika kumpulan koneksi jenuh.
• Periode "bake" setidaknya beberapa menit per langkah. Cukup lama agar kegagalan yang muncul perlahan dapat terungkap, cukup singkat sehingga Anda tidak menunda setiap rilis selama satu jam.

Layanan dengan lalu lintas tinggi dapat bergerak lebih cepat karena mereka mengumpulkan sinyal dengan cepat. API pembayaran yang menangani ribuan permintaan per detik memiliki data yang cukup untuk menilai canary dalam satu menit. API admin internal yang melihat beberapa permintaan per jam memerlukan periode "bake" yang lebih lama atau beban uji sintetik yang lebih berat untuk mencapai putusan.

Di mana pengujian canary cocok dalam strategi rilis Anda

Pengujian canary berpasangan secara alami dengan feature flag dan blue-green deployment, dan penting untuk memahami perbedaannya. Blue-green membalik semua lalu lintas dari satu lingkungan penuh ke lingkungan lain sekaligus; rollbacknya cepat, tetapi tidak ada eksposur bertahap. Feature flag mengaktifkan/menonaktifkan perilaku untuk pengguna tertentu tanpa penerapan ulang. Rilis canary secara bertahap mengalihkan lalu lintas nyata dan menjaga berdasarkan sinyal langsung.

Sebagian besar tim yang matang menggunakan ketiganya: blue-green untuk pertukaran infrastruktur, canary untuk peningkatan lalu lintas bertahap dengan pintu gerbang otomatis, dan feature flag untuk kontrol yang lebih granular setelah kode tayang. Benang merahnya adalah tidak satu pun dari mereka menghilangkan kebutuhan untuk menguji rilis terhadap produksi. Mereka mengontrol seberapa banyak audiens Anda yang terpapar saat Anda melakukannya.

Itulah inti sebenarnya. Pengujian canary bukanlah alat yang Anda beli; ini adalah disiplin: terapkan dalam skala kecil, uji rilis langsung dengan penegasan nyata, amati sinyal, dan jaga peluncuran berdasarkan hasilnya. Alat-alat ada untuk membuat setiap langkah tersebut otomatis. Dengan Apidog, Anda membangun rangkaian uji sekali, menjalankannya dari CLI di dalam pipeline apa pun, dan biarkan kode keluar memutuskan apakah rilis berlanjut. Rilis yang buruk berhenti pada 5% lalu lintas, dan pengguna Anda tidak akan pernah melihat kode 500.

Unduh Apidog untuk membangun skenario uji canary pertama Anda, arahkan lingkungan ke endpoint canary Anda, dan tambahkan satu langkah CLI ke pipeline Anda. Penggabungan buruk berikutnya akan rusak untuk beberapa permintaan saja, bukan untuk semua.

FAQ

Apakah pengujian canary sama dengan penerapan canary? Penerapan canary adalah mekanisme rilis: menyajikan versi baru ke sebagian kecil lalu lintas. Pengujian canary adalah apa yang Anda lakukan selama jendela tersebut, secara aktif menjalankan uji dan menegaskan respons daripada hanya mengamati dashboard. Anda memerlukan penerapan untuk melakukan pengujian, tetapi pengujianlah yang mengubah peluncuran berisiko menjadi peluncuran yang terjaga.

Apakah saya memerlukan service mesh untuk melakukan pengujian canary? Tidak. Service mesh seperti Istio atau Linkerd memang membuat pemisahan lalu lintas lebih mudah, tetapi Anda dapat menjalankan canary dengan bobot load balancer biasa, anotasi canary dari ingress controller, atau bahkan pembobotan DNS. Bagian uji dan jaga dari alur kerja, yang menjadi fokus panduan ini, bekerja sama terlepas dari bagaimana Anda membagi lalu lintas.

Bagaimana ini berbeda dengan uji smoke setelah deploy? Uji smoke biasanya berjalan sekali terhadap rilis yang sudah diterapkan sepenuhnya untuk mengkonfirmasi bahwa itu aktif. Pengujian canary berjalan terhadap rilis yang hanya melayani sebagian kecil lalu lintas nyata, dan menjaga peningkatannya. Penegasan bisa identik; perbedaannya adalah waktu dan konsekuensi. Uji smoke yang gagal berarti melakukan rollback sesuatu yang sudah tayang untuk semua orang; uji canary yang gagal berarti menghentikan peluncuran pada 5%. Untuk perbedaan antara rangkaian smoke dan regresi, lihat panduan perbandingan kami.

Dapatkah saya menggunakan kembali uji API yang sudah ada sebagai uji canary? Seringkali, ya. Jika Anda sudah memiliki skenario uji Apidog dengan penegasan nyata, Anda arahkan ke lingkungan yang URL dasarnya adalah canary dan menjalankannya dengan CLI. Pekerjaannya adalah memastikan uji Anda menegaskan pada body respons dan bukan hanya kode status, serta mengarahkannya ke canary daripada URL publik yang di-load-balance.

Apa yang terjadi ketika uji canary gagal di CI? CLI Apidog keluar dengan kode non-nol pada setiap penegasan yang gagal. Pipeline Anda memperlakukan itu seperti langkah yang gagal lainnya: pekerjaan berhenti, langkah promosi dilewati, dan langkah rollback if: failure() Anda berjalan. Tidak ada manusia yang harus mengawasi agar rollback terjadi.