@drsamonline/canary 0.0.0-stage → 0.12.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +23 -4
- package/src/index.js +156 -0
- package/README.md +0 -3
package/package.json
CHANGED
|
@@ -1,6 +1,25 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@drsamonline/canary",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.12.3",
|
|
4
|
+
"description": "Canary rollout with SLO-tied automatic rollback (B9.2).",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"license": "MIT",
|
|
7
|
+
"main": "./src/index.js",
|
|
8
|
+
"exports": {
|
|
9
|
+
".": "./src/index.js",
|
|
10
|
+
"./src/*": "./src/*"
|
|
11
|
+
},
|
|
12
|
+
"files": [
|
|
13
|
+
"src"
|
|
14
|
+
],
|
|
15
|
+
"repository": {
|
|
16
|
+
"type": "git",
|
|
17
|
+
"url": "git://github.com/drsamonline/sui.git",
|
|
18
|
+
"directory": "packages/canary"
|
|
19
|
+
},
|
|
20
|
+
"homepage": "https://github.com/drsamonline/sui#readme",
|
|
21
|
+
"publishConfig": {
|
|
22
|
+
"access": "public",
|
|
23
|
+
"registry": "https://registry.npmjs.org/"
|
|
24
|
+
}
|
|
25
|
+
}
|
package/src/index.js
ADDED
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @drsamonline/canary — canary rollout with SLO-tied rollback (B9.2).
|
|
3
|
+
*
|
|
4
|
+
* A canary is a percentage of traffic sent to a candidate instead of the baseline,
|
|
5
|
+
* watched against three numbers: success rate, p95 latency, and a minimum sample
|
|
6
|
+
* size before any judgement is allowed.
|
|
7
|
+
*
|
|
8
|
+
* Two rules that make the difference between a useful canary and a coin flip:
|
|
9
|
+
*
|
|
10
|
+
* 1. **No verdict on a handful of requests.** Until `minSamples` have been
|
|
11
|
+
* observed, the canary neither promotes nor rolls back.
|
|
12
|
+
* 2. **An outage is not a regression.** If the provider is resting, both arms
|
|
13
|
+
* fail, and rolling the candidate back would blame it for someone else's
|
|
14
|
+
* downtime. Those observations are counted separately and excluded.
|
|
15
|
+
*/
|
|
16
|
+
|
|
17
|
+
export const STATES = ['running', 'promoted', 'rolled_back'];
|
|
18
|
+
|
|
19
|
+
const DEFAULT_SLO = {
|
|
20
|
+
minSuccessRate: 0.9,
|
|
21
|
+
maxP95Ms: 8000,
|
|
22
|
+
minSamples: 20,
|
|
23
|
+
};
|
|
24
|
+
|
|
25
|
+
/**
|
|
26
|
+
* @param {{
|
|
27
|
+
* id?: string, baseline: string, candidate: string, percent?: number,
|
|
28
|
+
* slo?: Partial<typeof DEFAULT_SLO>, now?: () => number, random?: () => number
|
|
29
|
+
* }} opts
|
|
30
|
+
*/
|
|
31
|
+
export function createCanary(opts) {
|
|
32
|
+
if (!opts?.baseline || !opts?.candidate) {
|
|
33
|
+
throw new Error('A canary needs a baseline and a candidate.');
|
|
34
|
+
}
|
|
35
|
+
if (opts.baseline === opts.candidate) {
|
|
36
|
+
throw new Error('A canary cannot compare a combo with itself.');
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
const now = opts.now ?? Date.now;
|
|
40
|
+
const random = opts.random ?? Math.random;
|
|
41
|
+
const slo = { ...DEFAULT_SLO, ...(opts.slo ?? {}) };
|
|
42
|
+
const percent = Math.max(0, Math.min(100, Number(opts.percent ?? 10)));
|
|
43
|
+
|
|
44
|
+
/** @type {{ok: number, failed: number, latencies: number[], excluded: number}} */
|
|
45
|
+
const candidateStats = { ok: 0, failed: 0, latencies: [], excluded: 0 };
|
|
46
|
+
/** @type {Array<{at: number, event: string, detail: string}>} */
|
|
47
|
+
const events = [];
|
|
48
|
+
|
|
49
|
+
let state = 'running';
|
|
50
|
+
|
|
51
|
+
const stats = () => {
|
|
52
|
+
const samples = candidateStats.ok + candidateStats.failed;
|
|
53
|
+
const sorted = [...candidateStats.latencies].sort((a, b) => a - b);
|
|
54
|
+
const p95 = sorted.length ? sorted[Math.min(sorted.length - 1, Math.ceil(0.95 * sorted.length) - 1)] : 0;
|
|
55
|
+
return {
|
|
56
|
+
samples,
|
|
57
|
+
successRate: samples ? Math.round((candidateStats.ok / samples) * 1000) / 1000 : null,
|
|
58
|
+
p95Ms: p95,
|
|
59
|
+
excludedOutages: candidateStats.excluded,
|
|
60
|
+
};
|
|
61
|
+
};
|
|
62
|
+
|
|
63
|
+
const record = (event, detail) => events.push({ at: now(), event, detail });
|
|
64
|
+
|
|
65
|
+
return {
|
|
66
|
+
id: opts.id ?? `${opts.candidate}-canary`,
|
|
67
|
+
baseline: opts.baseline,
|
|
68
|
+
candidate: opts.candidate,
|
|
69
|
+
percent,
|
|
70
|
+
slo,
|
|
71
|
+
|
|
72
|
+
get state() {
|
|
73
|
+
return state;
|
|
74
|
+
},
|
|
75
|
+
|
|
76
|
+
/** Which arm should answer this request? */
|
|
77
|
+
pick() {
|
|
78
|
+
if (state !== 'running') return { arm: 'baseline', reason: `canary is ${state}` };
|
|
79
|
+
const candidate = random() * 100 < percent;
|
|
80
|
+
return {
|
|
81
|
+
arm: candidate ? 'candidate' : 'baseline',
|
|
82
|
+
combo: candidate ? opts.candidate : opts.baseline,
|
|
83
|
+
reason: candidate ? `${percent}% of traffic goes to the candidate` : 'baseline traffic',
|
|
84
|
+
};
|
|
85
|
+
},
|
|
86
|
+
|
|
87
|
+
/**
|
|
88
|
+
* Fold in one observation from the candidate arm.
|
|
89
|
+
* @param {{ok: boolean, latencyMs?: number, outage?: boolean}} observation
|
|
90
|
+
* @returns {{state: string, event: string|null, detail: string}}
|
|
91
|
+
*/
|
|
92
|
+
observe(observation) {
|
|
93
|
+
if (state !== 'running') return { state, event: null, detail: 'canary is finished' };
|
|
94
|
+
|
|
95
|
+
// An outage is not evidence about the candidate: it is evidence about the
|
|
96
|
+
// provider, and it hits both arms equally.
|
|
97
|
+
if (observation.outage) {
|
|
98
|
+
candidateStats.excluded += 1;
|
|
99
|
+
return { state, event: null, detail: 'provider outage — observation excluded from the verdict' };
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
if (observation.ok) {
|
|
103
|
+
candidateStats.ok += 1;
|
|
104
|
+
if (Number.isFinite(observation.latencyMs)) candidateStats.latencies.push(Number(observation.latencyMs));
|
|
105
|
+
} else {
|
|
106
|
+
candidateStats.failed += 1;
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
const s = stats();
|
|
110
|
+
if (s.samples < slo.minSamples) {
|
|
111
|
+
return { state, event: null, detail: `${s.samples}/${slo.minSamples} samples — no verdict yet` };
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
if (s.successRate < slo.minSuccessRate) {
|
|
115
|
+
state = 'rolled_back';
|
|
116
|
+
const detail = `success rate ${Math.round(s.successRate * 100)}% fell below ${Math.round(slo.minSuccessRate * 100)}% over ${s.samples} samples`;
|
|
117
|
+
record('rolled_back', detail);
|
|
118
|
+
return { state, event: 'rolled_back', detail };
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
if (s.p95Ms > slo.maxP95Ms) {
|
|
122
|
+
state = 'rolled_back';
|
|
123
|
+
const detail = `p95 ${s.p95Ms}ms exceeded ${slo.maxP95Ms}ms over ${s.samples} samples`;
|
|
124
|
+
record('rolled_back', detail);
|
|
125
|
+
return { state, event: 'rolled_back', detail };
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
// Sample floor met and both SLOs held: the candidate has earned the traffic.
|
|
129
|
+
state = 'promoted';
|
|
130
|
+
const detail = `success ${Math.round(s.successRate * 100)}%, p95 ${s.p95Ms}ms over ${s.samples} samples`;
|
|
131
|
+
record('promoted', detail);
|
|
132
|
+
return { state, event: 'promoted', detail };
|
|
133
|
+
},
|
|
134
|
+
|
|
135
|
+
/** Roll back by hand — the operator always outranks the SLO. */
|
|
136
|
+
rollback(reason = 'rolled back by an operator') {
|
|
137
|
+
if (state !== 'running') return { state, event: null, detail: 'canary is finished' };
|
|
138
|
+
state = 'rolled_back';
|
|
139
|
+
record('rolled_back', reason);
|
|
140
|
+
return { state, event: 'rolled_back', detail: reason };
|
|
141
|
+
},
|
|
142
|
+
|
|
143
|
+
snapshot() {
|
|
144
|
+
return {
|
|
145
|
+
id: opts.id ?? `${opts.candidate}-canary`,
|
|
146
|
+
baseline: opts.baseline,
|
|
147
|
+
candidate: opts.candidate,
|
|
148
|
+
percent,
|
|
149
|
+
slo,
|
|
150
|
+
state,
|
|
151
|
+
stats: stats(),
|
|
152
|
+
events: [...events].slice(-20),
|
|
153
|
+
};
|
|
154
|
+
},
|
|
155
|
+
};
|
|
156
|
+
}
|
package/README.md
DELETED