API Kanarya Testi: Hatalı Sürümleri Kullanıcılar Fark Etmeden Yakalayın

PR'ı birleştirdiniz. CI yeşildi. Dağıtım, günlüklerde tek bir hata olmadan tamamlandı. Yirmi dakika sonra, destek talepleri gelmeye başlar: bir ödeme uç noktası, belirli bir müşteri grubuna 500'ler döndürüyor ve nedenini bilmiyorsunuz çünkü pipeline'da hiçbir şey başarısız olmadı.

Kanarya testi, bu boşluğu kapatır. Birim testleri ve entegrasyon testleri, kodunuzu beklediğiniz şeye göre kontrol eder. Kodunuzu gerçek dünyaya göre kontrol edemezler: üretim trafiği, gerçek veritabanı, geçen Salı günü sessizce hız sınırını değiştiren üçüncü taraf API. Kanarya testi, yeni bir sürümü önce gerçek trafiğin küçük bir kısmına dağıtır, nasıl davrandığını izler ve ancak sinyaller sağlıklı göründüğünde yayılımı genişletir. Bir şey bozulursa, bir saat boyunca kullanıcıların %100'ü yerine, iki dakika boyunca kullanıcıların %2'si için bozulur.

API'lar özelinde, gösterge panellerini izlemekten ve ummaktan daha iyisini yapabilirsiniz. Kanarya canlıya geçtiği anda ona karşı gerçek bir test paketi çalıştırabilir, durum kodlarını, yanıt şemalarını ve gecikmeyi doğrulayabilir, ardından dağıtımı sonuca göre kapılayabilirsiniz. Bu kılavuzun anlatacağı iş akışı budur ve tüm sürecin mevcut CI/CD pipeline'ınız içinde yaşamasını sağlamak için Apidog ve komut satırı çalıştırıcısı ile baştan sona bağlayacağız.

düğme

Kanarya Testi Gerçekte Nedir

Adı, maden ocağındaki kanaryadan gelir. Madenciler, zehirli gaza insanlardan çok önce tepki verdiği için kafesli bir kuşu yer altına taşırlardı. Kuş ötmeyi bırakırsa, dışarı çıkardınız. Bir kanarya sürümü de aynı şekilde çalışır: küçük, harcanabilir bir örnek önce riski üstlenir, böylece diğer kullanıcılarınız asla üstlenmek zorunda kalmaz.

Uygulamada, bir kanarya dağıtımı hizmetinizin iki sürümünü aynı anda çalıştırmak anlamına gelir:

Kararlı: mevcut üretim sürümü, trafiğin çoğuna hizmet verir.
Kanarya: yeni sürüm, küçük bir yüzdeye (genellikle başlangıçta %1 ila %5) hizmet verir.

Bir yük dengeleyici, servis ağı veya ingress kontrolcü, trafiği aralarında böler. Kanaryanın hata oranını, gecikmesini ve iş metriklerini kararlı taban çizgisine göre izlersiniz. Eğer kanarya dayanırsa, %100 hizmet verene ve yeni kararlı sürüm olana kadar trafiği adım adım ona yönlendirirsiniz. Eğer kötüleşirse, her şeyi kararlı sürüme geri yönlendirirsiniz ve kötü sürüm kitlenizin çoğuna asla ulaşmaz.

Kanarya testi, bu döngünün aktif yarısıdır. Organik trafiğin bir hatayı ortaya çıkarmasını beklemek yerine, kanaryaya kasıtlı bir API isteği paketi gönderir ve yanıtları kontrol edersiniz. Pasif izleme, kullanıcılar çarptıktan sonra bir şeylerin ters gittiğini söyler. Aktif kanarya testi, etki alanını genişletmeden önce bir şeylerin yanlış olduğunu size söyler.

Kanarya Testi ile Halihazırda Yaptığınız Testler Arasındaki Fark

Kanarya testi, diğer testlerinizin yerini almaz. Zincirin sonunda yer alır ve farklı bir hata sınıfını yakalar.

Test türü	Kime karşı çalışır	Neleri yakalar	Neleri kaçırır
Birim testleri	Yalıtılmış fonksiyonlar	Mantık hataları	Gerçek G/Ç içeren her şey
Entegrasyon testleri	Bağlı bileşenler	Servisler arasındaki bozuk sözleşmeler	Üretim yapılandırması, gerçek veri şekli
Duman testleri	Dağıtılmış bir yapı	"Ayakta mı?" temel hatalar	Belirsiz davranışsal gerilemeler
Kanarya testi	Gerçek altyapıda canlı bir sürüm	Hatalı yapılandırma, ortam kayması, performans gerilemeleri, kısmi kesintiler	Yalnızca tam ölçekte ortaya çıkan hatalar

Kanarya testinin yerini almasının nedeni: üretim olaylarının büyük bir kısmı, hiçbir ön üretim ortamının tam olarak yeniden üretemeyeceği şeylerden kaynaklanır. Eksik bir ortam değişkeni. Eskimiş bir bağlantı havuzu ayarı. Staging'de var olan ancak üretimde olmayan bir veritabanı indeksi. Gerçek kimlik doğrulama altında farklı davranan bir alt bağımlılık. Kodunuz doğru; etrafındaki ortam değil. Kanarya testi, yeni sürümünüzün bu ortamla ilk kez karşılaştığı anıdır ve onunla tüm trafiğin değil, trafiğin yüzde ikisiyle karşılaşmak istersiniz.

Bunun nereye oturduğu hakkında daha geniş bir bağlam isterseniz, CI/CD'de API testlerini nasıl otomatikleştireceğinize dair kılavuzumuz önceki aşamaları kapsar ve duman testi ile regresyon testi karşılaştırması kanaryaların en çok dayandığı iki test türünü açıklar.

Bir Kanaryada Ne Ölçülmeli

Bir kanarya, yalnızca "sağlıklı" olanın neye benzediğini biliyorsanız faydalıdır. Küçük bir sinyal kümesi seçin ve kanaryayı mutlak bir sayıya göre değil, kararlı taban çizgisine göre karşılaştırın. %1,2'lik bir hata oranı hizmetiniz için normal olabilir; önemli olan, kanaryanın şu anda kararlı durumdan anlamlı ölçüde daha kötü olup olmadığıdır.

Dört sinyal çoğu durumu kapsar:

Hata oranı: 5xx yanıtlarının ve genellikle bir kimlik doğrulama değişikliğinden sonraki ani 401'ler gibi, olmaması gereken 4xx yanıtlarının payı. Bu, en önemli metriktir.
Gecikme: ortalama değil, p95 ve p99. Ortalama, gerçek kullanıcıların acı çektiği yavaş kuyruğu gizler. Ortalaması iyi görünse bile p99'da 40ms daha yavaş olan bir kanarya bir uyarıdır.
Yanıt doğruluğu: gövde hala şemayla eşleşiyor mu? Yanlış şekilde dönen bir 200 OK, 500'den daha kötüdür, çünkü izleme bunu işaretlemeyecektir.
İş sinyalleri: ödeme başarısı, oturum açma başarısı, sepete eklenen öğeler. Bunlar, teknik olarak "başarılı" HTTP yanıtları olan mantık gerilemelerini yakalar.

İlk üçünü doğrudan bir API testinde doğrulayabilirsiniz. Otomatikleştireceğimiz kısım budur.Adım Adım Kanarya Testi İş Akışı

Otomatikleştirilmiş API testleriyle kapılanmış bir kanarya dağıtımının şekli aşağıdadır. Her adım, bir pipeline'dan çalıştırabileceğiniz bir şeydir.

Yeni sürümü kararlı sürümün yanında kanarya olarak dağıtın.
Trafiğin küçük bir bölümünü (örneğin %5) kanaryaya yönlendirin.
Kanarya uç noktasına karşı otomatik bir API test paketi çalıştırın.
Kısa bir bekleme süresi boyunca hata oranını ve gecikmeyi izleyin.
Kapı: testler geçer ve metrikler bütçede kalırsa, daha fazla trafik kaydırın. Aksi takdirde geri alın.
Yükseltmeyi tekrarlayın (%5'ten %25'e, %50'ye, %100'e), her adımda yeniden test edin.
Kanaryayı kararlı sürüme yükseltin, eski sürümü devre dışı bırakın.

Dikkatinizi çekmesi gereken iki bölüm, adım 3 (test paketi) ve adım 5 (kapı). Bunları doğru yaparsanız, gerisi platformunuzun zaten sağladığı altyapıdır.

Apidog'da Test Paketini Oluşturma

Test paketi, kanarya testinin kalbidir ve çoğu ekibin kestirme yollara başvurduğu yer burasıdır. Sadece `/health` adresini ping'leyen ve 200 durum kodu kontrolü yapan bir kanarya "testi", sürecin başladığını söyler. Gerçek uç noktalarınızın çalışıp çalışmadığı hakkında hiçbir şey söylemez.

Gerçek bir kanarya paketi, önemli yolları çalıştırır: kimlik doğrulama, okuma, yazma ve her birinde yanıt şeklini doğrulama. Apidog'un test senaryoları, bu istekleri birbirine zincirlemenize, aralarında veri aktarmanıza ve yapıştırıcı kod yazmadan sonuçları doğrulamanıza olanak tanır.

Bir e-ticaret API'sı için sağlam bir kanarya senaryosu şöyle görünür:

Adım 1, kimlik doğrulama. Bir test hesabıyla POST /auth/login. 200 olduğunu doğrulayın, yanıttan token'ı bir değişkene çıkarın.
Adım 2, okuma. Token ile GET /products?limit=10. 200 olduğunu doğrulayın, yanıtın bir dizi olduğunu doğrulayın, her öğenin id, name ve price içerdiğini doğrulayın.
Adım 3, yazma. Bilinen bir ürünle POST /cart. 201 olduğunu doğrulayın, dönen sepet toplamının beklenen değerle eşleştiğini doğrulayın.
Adım 4, durumu doğrulama. GET /cart. Az önce eklediğiniz öğenin mevcut olduğunu doğrulayın.

Apidog'da her isteği bir kez oluşturur, ardından görsel olarak doğrulamalar eklersiniz. Şema kontrolleri için, yanıtı zaten tasarladığınız OpenAPI şemasına göre doğrulayabilirsiniz, böylece kaymış bir yanıt gövdesi testi otomatik olarak başarısız kılar. Kimlik doğrulama tokenı aktarımı için, bunu adım 1'in yanıtından çıkarır ve sonraki adımlarda bir değişken olarak referans alırsınız. Yaygın durumlar için komut dosyası gerekmez ve özel mantığa ihtiyaç duyduğunuzda JavaScript post-işlemcilerine geçebilirsiniz.

Bunun getirisi, bu aynı senaryonun tek bir tanımla üç şekilde çalıştırılmasıdır: siz onu oluştururken manuel olarak, canlıya geçtiğinde sentetik izleme olarak bir program üzerinde ve kanarya pipeline'ınız içinde komut satırından. Doğrulamaları bir kez yazarsınız.

Paketi Komut Satırından Çalıştırma

Bir dağıtımı kapılamak için, paketin CI'da başsız olarak çalışması gerekir. Apidog tam da bunun için bir CLI ile birlikte gelir. Bunu derleme aracınızda kurun:

npm install -g apidog-cli

Test senaryosu verilerinizi Apidog'dan CLI formatlı bir dosya olarak dışa aktarın veya bir erişim tokenı kullanarak çalıştırıcıyı kimliğe göre bir senaryoya yönlendirin, sonra çalıştırın:

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

Kanarya çalışmaları için bilmeye değer birkaç bayrak:

-t, --test-scenario belirli bir senaryoyu kimliğe göre çalıştırır. Bir senaryo klasörünün tamamını çalıştırmak için -f, --test-scenario-folder kullanın.
-e, --environment çalışma zamanı ortamını seçer. Bunu, temel URL'si kanarya uç noktanız olan bir ortama yönlendirin, böylece aynı testler tek bir değeri değiştirerek kanarya, staging veya üretim ortamlarına vurabilir.
-r, --reporters çıktıyı kontrol eder. cli konsola yazdırır, html paylaşılabilir bir rapor üretir ve junit, GitHub Actions, GitLab, Jenkins ve çoğu CI panosunun her test için başarılı/başarısız durumunu göstermek üzere yerel olarak ayrıştırdığı XML çıktısını verir.
-d, --iteration-data, paketi bir CSV veya JSON dosyasının her satırı için bir kez çalıştırır. Kanaryayı tek geçişte birden fazla kullanıcı profili veya ürün kimliğiyle vurmak için kullanışlıdır.
--upload-report, çalıştırma özetini Apidog'a geri iter, böylece ekip uygulamada kanarya geçmişini görebilir.

Bir doğrulama başarısız olduğunda CLI sıfır olmayan bir kodla çıkar. Bu çıkış kodu, tüm kapı mekanizmasıdır: pipeline'ınız zaten başarısız bir adımda nasıl duracağını bilir, bu nedenle başarısız bir kanarya testi, dağıtımı ücretsiz olarak durdurur.

Apidog'u pipeline'larda çalıştırmanın daha derinlemesine bir incelemesi için, GitHub Actions'da API testlerini nasıl otomatikleştireceğiniz ve Jenkins entegrasyon kılavuzu bu platformları ayrıntılı olarak kapsar.

CI/CD'ye Entegre Etme

İşte bir kanaryayı dağıtan, test eden ve yalnızca başarı durumunda terfi ettiren kısaltılmış bir GitHub Actions işi. Yapı, küçük sözdizimi değişiklikleriyle GitLab CI, CircleCI veya Jenkins'e taşınabilir.

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

Bunu düz bir dağıtımdan ziyade bir kanarya yapan mantık, sıralamadır. Kanarya, test çalışmadan önce trafiğin bir kısmını alır, böylece test zaten gerçek isteklere hizmet veren bir sürümü çalıştırır. if: failure() adımı bir güvenlik ağıdır: eğer test paketi sıfır olmayan bir kodla çıkarsa veya metrik kontrolü tetiklenirse, iş başarısız olur ve trafik %5'in üzerine çıkmadan önce geri alma çalışır.

CANARY_ENV_ID'yi, temel URL'si kanaryayı hedefleyen bir Apidog ortamına işaret etmeye devam edin. Daha sonra aynı paketi dağıtım sonrası üretim duman testi olarak çalıştırmak istediğinizde, üretim ortamı kimliğini değiştirir ve başka hiçbir şeyi değiştirmezsiniz. İşte bu yeniden kullanımın amacı: bir paket, birçok aşama.

Kanarya Testini İşe Yaramaz Hale Getiren Yaygın Hatalar

Yanlış uç noktayı test etmek. Testiniz yük dengeleyici tarafından yönlendirilen genel URL'ye ulaşırsa, istek kanarya yerine kararlı bir örneğe düşebilir. Testi açıkça kanaryaya yönlendirin; bu, ağın yönlendirdiği bir başlık aracılığıyla, özel bir kanarya ana bilgisayar adı aracılığıyla veya temel URL'si kanaryanın adresi olan bir ortam aracılığıyla yapılabilir.
Sıfır bekleme süresi. Bazı hatalar yalnızca sürekli yük altında ortaya çıkar: bellek sızıntıları, bağlantı havuzu tükenmesi, dolan bir önbellek. Testi çalıştırın, ardından terfi ettirmeden önce birkaç dakika izleyin. Anında geçen ve on saniye içinde terfi ettirilen bir kanarya, zar zor bir kanaryadır.
Otomatik geri alma yok. Bir insanın hatayı fark edip geri alma düğmesine tıklaması gerekiyorsa, olay yanıtının en yavaş kısmını döngüde tutmuş olursunuz. Tüm değer, pipeline'ın kendi başına geri almasıdır. Geri almayı hata koşuluna bağlayın ve geri almanın çalıştığını test edin.
Karşılaştırmalar yerine mutlak eşikler. "Hata oranı %1'in üzerindeyse başarısız ol" kuralı, temel hata oranınız meşru olarak %1,5 olduğunda bozulur. Kanaryayı mevcut kararlı sürümle karşılaştırın ve kanarya anlamlı ölçüde daha kötü olduğunda kapıyı tetikleyin, aylar önce seçtiğiniz bir sayıyı aştığında değil.
Zayıf doğrulamalar. Hatalı bir gövdeye sahip 200 yanıtı, yalnızca durum kodu kontrolünü geçer ve kullanıcılarınızı başarısız kılar. Yalnızca koda değil, yanıt şemasına göre doğrulama yapın. API sözleşmenizi önce tasarlamak ve yanıtları şemaya göre doğrulamak doğrudan burada meyvesini verir: kanarya testiniz sözleşmeyi ücretsiz olarak miras alır.

Kanarya ne kadar geniş olmalı ve ne kadar süreyle?

Evrensel bir yanıt yok, ancak çoğu ekip için uygulanabilir bir varsayılan:

Trafiğin %5'i ile başlayın. Hasarı sınırlamak için yeterince küçük, yoğun bir hizmette dakikalar içinde gerçek bir sinyal almak için yeterince büyük. Düşük trafikli API'lar, yeterli istek toplamak için daha uzun bir pencereye ihtiyaç duyabilir.
Adım adım yükseltin: %5'ten %25'e, %50'ye, %100'e. Her adımda test paketini yeniden çalıştırın. %5'te gizlenen bir regresyon, bağlantı havuzu doyduğunda bazen %50'de ortaya çıkar.
Her adım için en az birkaç dakika bekleyin. Yavaş yanan hataların ortaya çıkması için yeterince uzun, her sürümü bir saat boyunca durdurmayacak kadar kısa.

Yüksek trafikli hizmetler, sinyali hızla biriktirdikleri için daha hızlı hareket edebilirler. Saniyede binlerce isteği işleyen bir ödeme API'sı, bir kanaryayı bir dakika içinde değerlendirecek yeterli veriye sahiptir. Saatte birkaç istek gören dahili bir yönetici API'sı, bir karara varmak için daha uzun bir bekleme süresine veya daha ağır bir sentetik test yüküne ihtiyaç duyar.

Kanarya Testinin Yayın Stratejinizdeki Yeri

Kanarya testi, özellik bayrakları ve mavi-yeşil dağıtımlarla doğal olarak eşleşir ve farkı netleştirmekte fayda vardır. Mavi-yeşil, tüm trafiği bir tam ortamdan diğerine anında çevirir; geri alma hızlıdır, ancak kademeli bir maruz kalma yoktur. Özellik bayrakları, yeniden dağıtım yapmadan seçilen kullanıcılar için davranışı değiştirir. Kanarya sürümleri, gerçek trafiği kademeli olarak kaydırır ve canlı sinyallere göre kapılar.

Çoğu olgun ekip üçünü de kullanır: altyapı takası için mavi-yeşil, otomatik kapılarla kademeli trafik artışı için kanarya ve kod canlıya geçtiğinde hassas kontrol için özellik bayrakları. Ortak nokta, hiçbiri sürümü üretime karşı test etme ihtiyacını ortadan kaldırmaz. Bunu yaparken kitlenizin ne kadarının maruz kaldığını kontrol ederler.

Asıl çıkarım budur. Kanarya testi satın aldığınız bir araç değildir; bu bir disiplindir: küçük dağıtımlar yapın, canlı sürümü gerçek doğrulamalarla test edin, sinyalleri izleyin ve dağıtımı sonuca göre kapılayın. Bu adımların her birini otomatik hale getirmek için araçlar mevcuttur. Apidog ile test paketini bir kez oluşturur, herhangi bir pipeline içinde CLI'dan çalıştırır ve çıkış kodunun sürümün ilerleyip ilerlemeyeceğine karar vermesini sağlarsınız. Kötü sürümler trafiğin %5'inde durur ve kullanıcılarınız asla 500'leri görmez.

İlk kanarya test senaryonuzu oluşturmak için Apidog'u indirin, bir ortamı kanarya uç noktanıza yönlendirin ve pipeline'ınıza bir CLI adımı ekleyin. Bir sonraki kötü birleştirme, tüm istekler yerine yalnızca bir avuç istek için bozulur.

düğme

SSS

Kanarya testi, kanarya dağıtımı ile aynı mıdır? Bir kanarya dağıtımı, yayın mekanizmasıdır: yeni bir sürümü trafiğin küçük bir kısmına sunmak. Kanarya testi, bu pencere sırasında yaptığınız şeydir; yalnızca gösterge tablolarını izlemek yerine aktif olarak testler çalıştırır ve yanıtlara göre doğrulama yaparsınız. Testi yapmak için dağıtıma ihtiyacınız var, ancak riskli bir dağıtımı kapalı bir dağıtıma dönüştüren şey test etmektir.

Kanarya testi yapmak için bir hizmet ağına ihtiyacım var mı? Hayır. Istio veya Linkerd gibi bir hizmet ağı, trafiği bölmeyi kolaylaştırır, ancak kanaryaları düz bir yük dengeleyici ağırlığıyla, bir ingress denetleyicisinin kanarya açıklamalarıyla ve hatta DNS ağırlıklandırmasıyla çalıştırabilirsiniz. Bu kılavuzun odaklandığı iş akışının test ve kapı kısmı, trafiği nasıl böldüğünüze bakılmaksızın aynı şekilde çalışır.

Bu, dağıtım sonrası duman testinden nasıl farklıdır? Bir duman testi genellikle tamamen dağıtılmış bir sürüme karşı bir kez çalıştırılır ve ayakta olduğunu doğrular. Kanarya testi, gerçek trafiğin yalnızca bir kısmına hizmet veren bir sürüme karşı çalışır ve yükseltmeyi kapılar. Doğrulamalar aynı olabilir; fark zamanlama ve sonuçtadır. Başarısız bir duman testi, zaten herkes için canlı olan bir şeyi geri almayı; başarısız bir kanarya testi ise %5'te bir dağıtımı durdurmayı ifade eder. Duman ve regresyon paketleri arasındaki ayrım için, karşılaştırma kılavuzumuza bakın.

Mevcut API testlerimi kanarya testleri olarak yeniden kullanabilir miyim? Çoğunlukla, evet. Halihazırda gerçek doğrulamalar içeren Apidog test senaryolarınız varsa, bunları temel URL'si kanarya olan bir ortama yönlendirir ve CLI ile çalıştırırsınız. Yapılacak iş, testlerinizin yalnızca durum kodlarına değil, yanıt gövdelerine de doğrulama yaptığından ve onları yük dengeleyici tarafından yönlendirilen genel URL yerine kanaryaya yönlendirdiğinizden emin olmaktır.

Bir kanarya testi CI'da başarısız olduğunda ne olur? Herhangi bir başarısız doğrulama durumunda Apidog CLI sıfır olmayan bir kodla çıkar. Pipeline'ınız bunu başarısız bir adım gibi ele alır: iş durur, terfi adımı atlanır ve if: failure() geri alma adımınız çalışır. Geri almanın gerçekleşmesi için hiçbir insanın izlemesi gerekmez.