🖼️ See the drawing + lab 🏠 Course home 🌿 Branch on GitHub ✏️ View source

🖼️ आकृती आणि labThe drawing + lab पूर्ण पानावर उघडा ↗Open full page ↗

🐤 धडा 05 — Release engineering: canary चा निर्णय आकड्यांवरून घ्या

📍 तुम्ही इथे आहात: 12 पैकी धडा 05 · मागे: lesson-04-on-call · पुढे: lesson-06-progressive-delivery

📦 या ब्रँचमध्ये काय आहे

भाग 2 सुरू होतो: सुरक्षितपणे बदल करणे. बहुतेक outages एखाद्या बदलापासून सुरू होतात — नवा code, नवा config, नवा flag. हा धडा एखादा बदल आधी traffic च्या छोट्या भागाकडे पाठवतो (canary) आणि त्याची baseline शी तुलना करतो, dashboard कडे डोळ्यांनी बघण्याऐवजी आकड्यांचा वापर करून: promote, rollback, की आणखी थांबायचे. sre/crew.py मधील canary_judge आणि sre/demo.py मधील canary().

🧒 5 वर्षांच्या मुलाला समजावल्यासारखे

पथकाला प्रत्येक वर्गात नवा heating boiler बसवायचा आहे. 🔥 पण नवा boiler खराब निघाला तर?

म्हणून ते तो आधी एकाच वर्गात बसवतात. आणि — ही हुशारीची गोष्ट आहे — ते शेजारच्या वर्गात एक ताजा जुना boiler सुद्धा बसवतात, तेवढ्याच आकाराचा, तेवढ्याच विद्यार्थिनींसाठी. आता ते boiler सोडून बाकी सगळ्या बाबतीत सारख्या असलेल्या दोन वर्गांची तुलना करू शकतात.

एका दिवसानंतर ऐश्वर्या तक्रारी मोजते. जुना boiler: 11 तक्रारी. नवा boiler: 42. हे दुर्दैव नाही; हा खराब boiler आहे. तो काढून टाका.

दुसऱ्या वेळी: जुना 11, नवा 13. हा छोटा फरक रोजचा सामान्य चढउतार आहे. नवा boiler सगळीकडे बसवा.

आणि आज त्या वर्गात फक्त काहीच विद्यार्थिनी आल्या असतील तर? "सांगायला अजून लवकर आहे. आणखी थांबा."

🗺️ आकृती

flowchart LR
    t["🚦 traffic"] --> b["baseline<br/>old version, fresh copy<br/>11 errors / 10,000 · p99 180 ms"]
    t --> c["canary<br/>new version, same size"]
    b & c --> j{"⚖️ judge<br/>z-test on errors<br/>p99 ratio"}
    j -->|"A: 13 errors · z 0.41"| p["✅ PROMOTE"]
    j -->|"B: 42 errors · z 4.26"| r["↩️ ROLLBACK"]
    j -->|"C: p99 260 ms · ×1.44"| r
    j -->|"D: only 400 requests"| e["⏳ EXTEND"]

🗺️ काढलेली आवृत्ती + एक lab: https://school-edh.pages.dev/sre/lesson-diagrams.html#l05

❓ काय

Canary release — नवी version आधी खऱ्या traffic च्या छोट्या वाट्याकडे पाठवा, तिच्यावर लक्ष ठेवा, मग निर्णय घ्या. (पूर्वी कोळशाच्या खाणींमध्ये धोक्याची आगाऊ सूचना म्हणून नेल्या जाणाऱ्या canary पक्ष्यांवरून हे नाव पडले.)
Baseline — जुनी version, ताजी deploy केलेली, canary इतक्याच आकाराची आणि तेवढ्याच traffic वाट्याची. खूप काळ चालणाऱ्या संपूर्ण जुन्या fleet शी तुलना करणे अन्यायकारक आहे: जुन्या machines वर warm caches, हळू होणाऱ्या leaks आणि वेगळे hosts असतात. Netflix आणि Google चे Kayenta canary tool नेमकी हीच baseline-विरुद्ध-canary रचना सुचवते.
Canary analysis — canary च्या metrics ची baseline च्या metrics शी तुलना: error rate, latency, CPU, memory, business metrics. Kayenta प्रत्येक metric ला Mann-Whitney U test ने गुण देते आणि pass व marginal thresholds सह त्यांची बेरीज 0–100 score मध्ये करते.
Two-proportion z-test — हा lab error rate साठी वापरतो तो check: दोन error rates एकमेकांपासून किती standard errors दूर आहेत? z = (p_canary − p_baseline) ÷ SE, इथे SE pooled rate वरून येतो. मोठा z म्हणजे "योगायोग असण्याची शक्यता कमी". Lab z = 3.0 च्या वर rollback करतो.
Ratio check — latency साठी, canary चा p99 baseline च्या 1.2 × पेक्षा जास्त असेल तेव्हा lab rollback करतो. (हा lab शिकवण्यासाठीचे model आहे: errors साठी एक test, latency साठी एक ratio. खरे tools अनेक metrics तपासतात आणि त्यांना हे हाताळावे लागते की अनेक metrics तपासल्याने खोट्या धोक्याच्या इशाऱ्याची शक्यता वाढते.)
किमान sample — खूप कमी requests असतील तर कोणतीही test खरा फरक आणि योगायोग यांत फरक करू शकत नाही. कोणत्याही बाजूला 1,000 पेक्षा कमी requests असतील तर lab EXTEND म्हणतो.
Promote / rollback / extend — तीन निकाल. त्यांना automate करा: शुक्रवारी 17:55 ला graphs कडे टक लावून बघणारी व्यक्ती जवळपास काहीही promote करते.

🤔 का

कारण बदल हे outages चे सर्वात मोठे कारण आहे, आणि canary वाईट बदल किती users पर्यंत पोहोचतो ते मर्यादित करते (धडा 06 ते मोजतो). पण canary तिच्या judge इतकीच चांगली असते. Dashboard वरच्या दोन रेषांकडे डोळ्यांनी बघितल्यास, दोन्ही अगदी लहान असताना 3× error rate सुटतो, आणि सामान्य गोंगाटाने घबराट होते. लिखित, automatic नियम प्रत्येक वेळी सारखाच निर्णय घेतो, आणि तो मिनिटांत कृती करू शकतो.

🔧 कसे (या repo मध्ये)

sre/crew.py मधील canary_judge(base, canary, min_requests=1000, z_limit=3.0, p99_ratio=1.2) प्रत्येक बाजूसाठी (errors, requests, p99_ms) घेते आणि (verdict, z, p99 ratio) परत देते. ते आधी sample चा आकार तपासते, मग error rate वर z-test, मग p99 ratio. sre/demo.py मधील canary() एका baseline विरुद्ध चार canaries चा निर्णय घेते.

🧪 करून पाहा

python3 sre/demo.py canary
python3 - <<'EOF'
import sys; sys.path.insert(0, "sre"); from crew import canary_judge
base = (11, 10000, 180)
for errors in (11, 20, 25, 30, 42):
    v, z, r = canary_judge(base, (errors, 10000, 180))
    print(f"canary {errors:>2} errors / 10,000 → z {z:5.2f} → {v}")
for n in (500, 5000, 50000):
    v, z, r = canary_judge((n * 11 // 10000, n, 180), (n * 22 // 10000, n, 180))
    print(f"double the error rate, {n:>6,} requests each → {v}" + ("" if z is None else f" (z {z:.2f})"))
EOF

✅ तपासा — तुम्हाला काय दिसायला हवे

canary हे print करते:

   canary A: 13 errors / 10,000 · p99 185 ms → z   0.41 · p99 ×1.03 → PROMOTE
   canary B: 42 errors / 10,000 · p99 182 ms → z   4.26 · p99 ×1.01 → ROLLBACK
   canary C: 12 errors / 10,000 · p99 260 ms → z   0.21 · p99 ×1.44 → ROLLBACK
   canary D:  3 errors /    400 · p99 179 ms → z    n/a · p99 ×0.99 → EXTEND  (first minutes: baseline 1 / 400)

तुमचा snippet हे print करतो:

canary 11 errors / 10,000 → z  0.00 → PROMOTE
canary 20 errors / 10,000 → z  1.62 → PROMOTE
canary 25 errors / 10,000 → z  2.34 → PROMOTE
canary 30 errors / 10,000 → z  2.97 → PROMOTE
canary 42 errors / 10,000 → z  4.26 → ROLLBACK
double the error rate,    500 requests each → EXTEND
double the error rate,  5,000 requests each → PROMOTE (z 1.50)
double the error rate, 50,000 requests each → ROLLBACK (z 4.29)

🏁 तुम्ही आत्ताच काय सिद्ध केले

11 ऐवजी 30 errors असलेली canary — जवळपास 3× वाईट — promote झाली, कारण इतक्या लहान error rates साठी 10,000 requests हा z = 3.0 वर पुरेसा पुरावा नाही. तोच दुप्पट error rate 5,000 requests वर pass झाला आणि 50,000 वर fail झाला. म्हणजे canary चा आकार आणि थांबण्याचा कालावधी हे ठरवतात की judge ला काय दिसू शकते: लहान error rates साठी भरपूर traffic लागते. Canary C दुसरा धडा दाखवते — error rate ठीक होता पण latency 44% वाईट होती, म्हणून एक metric पुरेसा नाही.

⚠️ नेहमीच्या चुका

ताज्या baseline ऐवजी संपूर्ण जुन्या fleet शी canary ची तुलना करणे
डोळ्यांनी बघून निर्णय घेणे, किंवा judge शिवाय फक्त timer वर promote करणे
तुम्हाला महत्त्वाचे errors दिसण्यासाठी खूप लहान किंवा खूप कमी काळाची canary
फक्त एकच metric (errors) — हळू असणे हेही बिघडलेलेच आहे
अनेक metrics वर कडक threshold, म्हणजे प्रत्येक canary fail होते आणि लोक तो override करायला शिकतात
फक्त अंतर्गत किंवा test traffic मिळणाऱ्या canaries, जे users करतात तसे नसते

🏭 प्रत्यक्ष वापरात

Argo Rollouts एका AnalysisTemplate मधून analysis चालवते: एक query, ती किती वेळा चालवायची आणि यश कशाला म्हणायचे. खऱ्या account वर — Prometheus विरुद्ध error-rate check:

apiVersion: argoproj.io/v1alpha1
kind: AnalysisTemplate
metadata: {name: error-rate}
spec:
  args: [{name: service-name}]
  metrics:
    - name: error-rate
      interval: 5m
      failureLimit: 1
      successCondition: result[0] < 0.005
      provider:
        prometheus:
          address: http://prometheus.monitoring:9090
          query: |
            sum(rate(http_requests_total{service="{{args.service-name}}",code=~"5.."}[5m]))
            / sum(rate(http_requests_total{service="{{args.service-name}}"}[5m]))

हे template ठराविक threshold तपासते, तुलना नाही. खऱ्या baseline-विरुद्ध-canary तुलनेसाठी Argo Rollouts baseline आणि canary experiments शेजारी शेजारी सुरू करू शकते, आणि Kayenta सह Spinnaker तुमच्यासाठी statistical तुलना आणि score करते. Flagger Istio, Linkerd, NGINX आणि इतर routers साठी threshold-आधारित analysis करते.

🏭 प्रत्यक्ष वापरात हे का महत्त्वाचे आहे: तुमच्या पुढच्या release साठी आधीच लिहून ठेवा: कोणते metrics, canary किती मोठी, किती काळ, आणि कोणते आकडे म्हणजे rollback. हे करता आले नाही, तर तुमची canary ही test नसून फक्त एक आशा आहे.

⏭️ पुढे

Judge म्हणतो "rollback करा". तुम्ही ते किती वेगाने करू शकता? आणि तुम्ही ते करण्याआधी किती users ना त्रास झाला? पुढचा धडा ते मोजतो.

git checkout lesson-06-progressive-delivery

🐤 Lesson 05 — Release engineering: judge the canary with numbers

📍 You are here: Lesson 05 of 12 · Previous: lesson-04-on-call · Next: lesson-06-progressive-delivery

📦 What's in this branch

Part 2 begins: changing things safely. Most outages start with a change — new code, new config, a new flag. This lesson sends a change to a small slice of traffic first (the canary) and compares it with a baseline, using numbers instead of eyeballing a dashboard: promote, roll back, or keep waiting. canary_judge in sre/crew.py and canary() in sre/demo.py.

🧒 Explain like I'm 5

The crew wants to put a new heating boiler in every classroom. 🔥 But what if the new boiler is bad?

So they put it in one classroom first. And — this is the clever part — they also put a fresh old boiler in the classroom next door, same size, same number of pupils. Now they can compare two classrooms that are the same in every way except the boiler.

After a day, Aishwarya counts the complaints. Old boiler: 11 complaints. New boiler: 42. That is not bad luck; that is a bad boiler. Take it out.

Another time: old 11, new 13. That small difference is normal day-to-day wobble. Put the new boiler everywhere.

And if only a few pupils used the room today? "Too early to tell. Wait longer."

🗺️ Diagram

flowchart LR
    t["🚦 traffic"] --> b["baseline<br/>old version, fresh copy<br/>11 errors / 10,000 · p99 180 ms"]
    t --> c["canary<br/>new version, same size"]
    b & c --> j{"⚖️ judge<br/>z-test on errors<br/>p99 ratio"}
    j -->|"A: 13 errors · z 0.41"| p["✅ PROMOTE"]
    j -->|"B: 42 errors · z 4.26"| r["↩️ ROLLBACK"]
    j -->|"C: p99 260 ms · ×1.44"| r
    j -->|"D: only 400 requests"| e["⏳ EXTEND"]

🗺️ Drawn version + a lab: https://school-edh.pages.dev/sre/lesson-diagrams.html#l05

❓ What

Canary release — send a new version a small share of real traffic first, watch it, then decide. (Named after the canaries once taken into coal mines as an early warning.)
Baseline — the old version, deployed fresh, with the same size and the same traffic share as the canary. Comparing with the whole long-running old fleet is unfair: old machines have warm caches, slow leaks and different hosts. Netflix and Google's Kayenta canary tool recommends exactly this baseline-vs-canary setup.
Canary analysis — compare the canary's metrics with the baseline's: error rate, latency, CPU, memory, business metrics. Kayenta scores each metric with a Mann-Whitney U test and adds them into a 0–100 score with pass and marginal thresholds.
Two-proportion z-test — the check this lab uses for the error rate: how many standard errors apart are the two error rates? z = (p_canary − p_baseline) ÷ SE, with SE from the pooled rate. A big z means "unlikely to be chance". The lab rolls back above z = 3.0.
Ratio check — for latency, the lab rolls back when the canary's p99 is more than 1.2 × the baseline's. (This lab is a teaching model: one test for errors, one ratio for latency. Real tools check many metrics and must handle the fact that testing many metrics raises the chance of a false alarm.)
Minimum sample — with too few requests, no test can tell a real difference from chance. The lab says EXTEND below 1,000 requests on either side.
Promote / rollback / extend — the three outcomes. Automate them: a human staring at graphs at 17:55 on a Friday promotes almost anything.

🤔 Why

Because change is the top cause of outages, and the canary limits how many users a bad change reaches (lesson 06 counts them). But a canary is only as good as its judge. Eyeballing two lines on a dashboard misses a 3× error rate when both are tiny, and panics at normal noise. A written, automatic rule decides the same way every time, and it can act in minutes.

🔧 How (in this repo)

canary_judge(base, canary, min_requests=1000, z_limit=3.0, p99_ratio=1.2) in sre/crew.py takes (errors, requests, p99_ms) for each side and returns (verdict, z, p99 ratio). It checks the sample size first, then the z-test on the error rate, then the p99 ratio. canary() in sre/demo.py judges four canaries against one baseline.

🧪 Try it

python3 sre/demo.py canary
python3 - <<'EOF'
import sys; sys.path.insert(0, "sre"); from crew import canary_judge
base = (11, 10000, 180)
for errors in (11, 20, 25, 30, 42):
    v, z, r = canary_judge(base, (errors, 10000, 180))
    print(f"canary {errors:>2} errors / 10,000 → z {z:5.2f} → {v}")
for n in (500, 5000, 50000):
    v, z, r = canary_judge((n * 11 // 10000, n, 180), (n * 22 // 10000, n, 180))
    print(f"double the error rate, {n:>6,} requests each → {v}" + ("" if z is None else f" (z {z:.2f})"))
EOF

✅ Verify — what you should see

canary prints:

   canary A: 13 errors / 10,000 · p99 185 ms → z   0.41 · p99 ×1.03 → PROMOTE
   canary B: 42 errors / 10,000 · p99 182 ms → z   4.26 · p99 ×1.01 → ROLLBACK
   canary C: 12 errors / 10,000 · p99 260 ms → z   0.21 · p99 ×1.44 → ROLLBACK
   canary D:  3 errors /    400 · p99 179 ms → z    n/a · p99 ×0.99 → EXTEND  (first minutes: baseline 1 / 400)

Your snippet prints:

canary 11 errors / 10,000 → z  0.00 → PROMOTE
canary 20 errors / 10,000 → z  1.62 → PROMOTE
canary 25 errors / 10,000 → z  2.34 → PROMOTE
canary 30 errors / 10,000 → z  2.97 → PROMOTE
canary 42 errors / 10,000 → z  4.26 → ROLLBACK
double the error rate,    500 requests each → EXTEND
double the error rate,  5,000 requests each → PROMOTE (z 1.50)
double the error rate, 50,000 requests each → ROLLBACK (z 4.29)

🏁 What you just proved

A canary with 30 errors instead of 11 — almost 3× worse — was promoted, because 10,000 requests with error rates this small is not enough evidence at z = 3.0. The same doubled error rate passed with 5,000 requests and failed with 50,000. So the size of the canary and the length of the wait decide what the judge can see: small error rates need lots of traffic. Canary C shows the other lesson — the error rate was fine but latency was 44% worse, so one metric is not enough.

⚠️ Common mistakes

comparing the canary with the whole old fleet instead of a fresh baseline
judging by eye, or promoting on a timer with no judge at all
a canary too small or too short to see the errors you care about
one metric only (errors) — slow is also broken
a strict threshold on many metrics, so every canary fails and people learn to override it
canaries that get only internal or test traffic, which is not what users do

🏭 In production

Argo Rollouts runs analysis from an AnalysisTemplate: a query, how often to run it and what counts as success. On a real account — an error-rate check against Prometheus:

apiVersion: argoproj.io/v1alpha1
kind: AnalysisTemplate
metadata: {name: error-rate}
spec:
  args: [{name: service-name}]
  metrics:
    - name: error-rate
      interval: 5m
      failureLimit: 1
      successCondition: result[0] < 0.005
      provider:
        prometheus:
          address: http://prometheus.monitoring:9090
          query: |
            sum(rate(http_requests_total{service="{{args.service-name}}",code=~"5.."}[5m]))
            / sum(rate(http_requests_total{service="{{args.service-name}}"}[5m]))

This template checks a fixed threshold, not a comparison. For a true baseline-vs-canary comparison, Argo Rollouts can start baseline and canary experiments side by side, and Spinnaker with Kayenta does the statistical comparison and scoring for you. Flagger does threshold-based analysis for Istio, Linkerd, NGINX and other routers.

🏭 Why this matters in production: for your next release, write down in advance: which metrics, what size canary, how long, and what numbers mean rollback. If you cannot, your canary is a hope, not a test.

⏭️ Next

The judge says "roll back". How fast can you? And how many users were hurt before you did? The next lesson counts them.

git checkout lesson-06-progressive-delivery

← Previouson call Next →progressive delivery

This page is the lesson's README from the lesson-05-canary-analysis branch, shown here so the whole School stays on one site. Code files open on GitHub at the same branch.