Incident Runbooks: من الـ alert للـ postmortem

ده runbook زي اللي في أغلب الشركات. صفحة wiki، وتحتها script حد كتبه عشان يسرّع. الصفحة بتقول: ادخل الـ database وشوف فيه إيه. والـ script بيعمل connect بـ password مكتوبة في الـ repo، وبيقتل كل الـ connections. بص عليه كويس. المشاكل. الخطوات مش واضحة: أشوف إيه؟ أقتل أنهي query؟ والـ on call اللي صاحي من النوم مش هيفكّر كويس. الـ script بيقتل كل حاجة، من غير dry run، ومن غير approval، ومن غير ما يتأكد إن المشكلة اتحلّت. الـ password في الـ wiki وفي الـ repo. محدش عمل acknowledge، فالـ pager فضل يرن، ومحدش قائد، فخمسة بيعملوا حاجات متضاربة. ومفيش timeline، فالـ postmortem بقى memory الناس، وبقى blame. والأخطر: الـ runbook ده محدش جرّبه من سنة، فأول مرة هيشتغل هي وقت الـ incident.

الأول: يعني إيه incident؟ أي حاجة بتضر على الـ users أو هتضر قريب، ومحتاجة حد يتصرّف دلوقتي. وبنقسّمها بالـ severity. sev one: الـ service واقعة أو فيه data loss، والكل يصحى. sev two: جزء مهم واقع، زي الـ checkout، أو الـ service كلها بطيئة قوي. sev three: حاجة مزعجة بس فيه workaround. sev four: حاجة صغيرة تستنى الصبح. والـ severity بتحدد كل حاجة بعدها: مين يصحى، وفي قد إيه لازم حد يعمل ack، وكل قد إيه نبعت update للـ status page.

الـ roles. أول ما الـ incident يتفتح، لازم يبقى فيه incident commander. الـ commander مش لازم يكون أشطر واحد تقنيًا، بالعكس، شغله إنه ينسّق: مين بيعمل إيه، وإيه القرار الجاي، وهو اللي بيوافق على الـ actions الخطيرة. الـ scribe بيكتب الـ timeline. الـ comms بيبعت updates للـ status page وللـ support. والباقي بيحققوا وبيصلّحوا. القاعدة: محدش يعمل حاجة على الـ production من غير ما الـ commander يعرف. ده اللي بيمنع خمسة يعملوا restart لنفس الحاجة في نفس الوقت. الـ SLAs بتوع الـ incident نفسه. الـ ack: الـ alert ضرب، ولازم حد يقول أنا شايفه في وقت محدد. لو ما حصلش، الـ pager يصعّد للـ secondary، وبعدين للـ manager. الـ updates: في sev one كل نص ساعة لازم update، حتى لو هو: لسه بنحقق. لأن الـ users والـ support من غير updates بيفترضوا الأسوأ. وفي الـ code: الـ incident بيعرف الـ severity بتاعته، و overdue بترجّع list بالحاجات المتأخرة: ack أو update. وده اللي الـ bot بتاع الـ incident بيستخدمه عشان يفكّر الناس.

والـ statuses بالترتيب: open، بعدين acknowledged، بعدين mitigated، بعدين resolved. الفرق بين mitigated و resolved مهم. mitigated يعني الـ users مش حاسين بحاجة دلوقتي، زي إننا عملنا rollback أو قفلنا feature flag. resolved يعني السبب الأصلي اتصلّح. وغالبًا بنعمل mitigate الأول بسرعة، وبعدين نصلّح براحتنا. ومن الأوقات دي بنطلّع الـ metrics: TTA يعني time to acknowledge، و TTM يعني time to mitigate، و TTR يعني time to resolve. والمتوسط بتاعهم على الـ incidents كلها بيقولك الفريق بتاعك سريع ولا لأ. دلوقتي الـ runbook نفسه. أول قاعدة: كل alert ليه runbook، والـ link بتاعه جوّه الـ alert. الـ on call ما يدوّرش. وتاني قاعدة: الـ runbook يبقى code، مش نص. لأن النص بيتقادم ومحدش بيعرف، والـ code بيتجرّب في الـ CI وبيبوز قدامك لو حاجة اتغيّرت. والـ runbook عندنا ليه id، و title، والـ alert بتاعه، والـ owner، يعني الفريق اللي بيتصعّد له، والـ severity، والـ steps.

الـ steps تلات أنواع. check: بيقرا بس. بيشوف كام query مستنية lock، وأنهي connections قاعدة idle in transaction. ودي آمنة، تشتغل في أي وقت. action: بيغيّر حاجة. يقفل feature flag، أو يقتل connection. verify: بيتأكد إن المشكلة اتحلّت فعلًا. وكل step بياخد نتايج اللي قبله. يعني الـ terminate بياخد الـ pids من الـ check، مش بيقتل كل حاجة. وفيه when: الـ step يشتغل بس لو شرط معيّن، زي إن فيه pids أصلًا.

defineRunbook بيرفض الـ runbook الغلط قبل ما يشتغل. كل action لازم يبقى عنده rollback، أو مكتوب صراحة إنه irreversible. زي قتل connection، مفيش رجوع منه. وأي irreversible لازم requiresApproval. ولازم يبقى فيه verify بعد آخر action. لأن action من غير verify يعني إنت عملت حاجة وافترضت إنها نفعت. وكل ده بيترفض في الـ CI، يعني الـ runbook البايز ما يوصلش للـ on call أصلًا. الـ dry run. أول حاجة الـ on call يعملها: يشغّل الـ runbook بـ dry run. الـ checks بتشتغل بجد، لأنها بتقرا بس، والـ actions بتتسجّل إنها كانت هتشتغل، من غير ما تشتغل. فالـ on call يشوف: فيه connection واحدة idle in transaction، والـ runbook هيقتلها. مش تلاتين، مش الـ replication. ولو الأرقام غريبة، يقف ويفكّر. وبعدين الـ approval. الـ action الخطير بيسأل الـ commander، وبيوريه نتايج الـ checks. لو رفض، الـ runbook يقف بـ denied، ومن غير ما يعمل الـ action.

الـ rollback والـ escalation. لو action فشل، أو الـ verify قال إن المشكلة لسه موجودة، بنرجّع اللي عملناه بالعكس. آخر action الأول، زي الـ database transaction. ليه؟ لأن الـ actions ممكن تعتمد على بعض. والـ irreversible بنسجّل إننا مش قادرين نرجّعه، عشان اللي بيقرا الـ timeline يعرف. ولو الـ rollback نفسه فشل، بنسجّل وبنكمّل الباقي. وبعدين escalate: الـ runbook ما نفعش، فلازم نصحّي الفريق اللي هو owner. الـ runbook مش بيحل كل حاجة، بس لازم يعرف إمتى يقول: أنا مش عارف، كلّموا حد. وكل step ليه timeout. الـ check اللي بيعمل query على database مخنوقة ممكن يعلّق، والـ on call قاعد مستني من غير ما يعرف. بالـ timeout، الـ step يفشل بـ TIMEOUT بعد خمس seconds، والـ runbook يعمل rollback و escalate. والـ redaction. الـ timeline بيتشاف من ناس كتير، وبيتنسخ في الـ postmortem، وساعات في Slack. فأي password في URL، أو Bearer token، أو key اسمه password أو token، بيتشال قبل ما يتسجّل. والـ connection string بيبقى من غير الـ password، بس لسه فيه الـ host، وده مفيد للتحقيق.

الـ timeline. كل حاجة بتتسجّل بالوقت: الـ alert، والـ ack، والـ roles، والـ updates، وكل step في الـ runbook ونتيجته، والـ approvals، والـ escalations. ده بيعمل حاجتين. وقت الـ incident: أي حد يدخل متأخر يقرا الـ timeline ويفهم إحنا فين، من غير ما يسأل ويقطع الشغل. بعد الـ incident: الـ postmortem بيتكتب من حقايق، مش من memory الناس الساعة تلاتة الفجر.

الـ postmortem. أهم كلمة: blameless. السؤال مش مين غلط، السؤال: إيه في الـ system سمح بالغلطة دي؟ لو حد قدر يقتل كل الـ connections بـ command واحد، المشكلة إن الـ system سمح بده، مش الشخص. والـ postmortem فيه: الـ impact، والـ root cause، والـ metrics، والـ timeline، والـ action items. وكل action item لازم يبقى ليه owner و due date. لأن action item من غير owner معناه إن محدش هيعمله، والـ incident هيتكرر. وعشان كده الـ postmortem بيترفض لو فيه item من غير owner. وآخر حاجة: الـ runbooks بتتجرّب. في الـ CI: test بيعمل المشكلة بجد، زي transaction قافلة row على Postgres حقيقي، ويشغّل الـ runbook، ويتأكد إنه حلّها. ده اللي هنعمله في الـ test. وفي game days: الفريق بيكسر حاجة في staging عن قصد، والـ on call يحلها بالـ runbook وهو مش عارف إيه اللي اتكسر. وده هنعمله في درس قريب على Redis و Postgres. الـ runbook اللي ما اتجرّبش، اعتبره مش موجود.

التحدي. عندك lab dot js بيعمل incident حقيقي على Postgres: transaction نسيت تعمل commit وقفلت الـ orders، و test dot js. والمطلوب runbook dot js. كل التفاصيل في الكومنت: SEVERITIES، و redact، و withTimeout، و defineRunbook بالـ validation، و createIncident بالـ statuses والـ roles والـ overdue والـ metrics، و runRunbook بالـ dry run والـ approvals والـ rollback والـ escalation، و postmortem. اقرا الكومنت كويس، ونشغّل test dot js لحد ما تبقى أربعتاشر من أربعتاشر.

الحل. redact بيلف على الـ value كله، والـ keys الحسّاسة بـ regex. defineRunbook بيجمع كل الـ problems مرة واحدة، عشان اللي بيكتب الـ runbook يشوفهم كلهم. الـ transition بيسمح بالـ status اللي بعده بس، بـ indexOf. في runRunbook، الترتيب مهم: when، بعدين dry run، بعدين approval، بعدين التشغيل بـ timeout. الـ actions اللي نجحت بتدخل done، والـ rollback بيلف عليها بالعكس. وكل حاجة بتعدّي على incident.log، اللي بيعمل redact. نشغّل lab dot js.

// runbook.js: runbooks بتتنفّذ: validation، و incidents بـ timeline و SLAs، و approvals، و dry run، و rollback، و redaction، و postmortem
// lab.js و test.js بيعملوا import من هنا: SEVERITIES و redact و withTimeout و defineRunbook و createIncident و runRunbook و postmortem
export const SEVERITIES = {
  sev1: { ackMs: 5 * 60e3, updateMs: 30 * 60e3 },
  sev2: { ackMs: 15 * 60e3, updateMs: 60 * 60e3 },
  sev3: { ackMs: 4 * 3600e3, updateMs: null },
  sev4: { ackMs: 24 * 3600e3, updateMs: null },
};
const STATUSES = ["open", "acknowledged", "mitigated", "resolved"];
const fail = (code, extra = {}) => Object.assign(new Error(code), { code }, extra);

export function redact(value) {
  if (typeof value === "string") {
    return value.replace(/(\/\/[^:/@\s]+:)[^@\s]+@/g, "$1***@").replace(/(Bearer\s+)[\w.~+/-]+=*/gi, "$1***");
  }
  if (Array.isArray(value)) return value.map(redact);
  if (value && typeof value === "object") {
    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, /pass|secret|token|api.?key|authorization/i.test(k) ? "[REDACTED]" : redact(v)]));
  }
  return value;
}

export function withTimeout(promise, ms) {
  let timer;
  const t = new Promise((_, reject) => { timer = setTimeout(() => reject(fail("TIMEOUT")), ms); });
  return Promise.race([Promise.resolve(promise), t]).finally(() => clearTimeout(timer));
}

export function defineRunbook(rb) {
  const p = [];
  if (!/^[a-z0-9-]+$/.test(rb.id ?? "")) p.push("id");
  for (const f of ["title", "alert", "owner"]) if (!rb[f]) p.push(f);
  if (!SEVERITIES[rb.severity]) p.push("severity");
  const steps = rb.steps ?? [];
  if (!steps.length) p.push("steps");
  const seen = new Set();
  steps.forEach((s, i) => {
    const at = s.id ?? `#${i}`;
    if (!s.id || seen.has(s.id)) p.push(`${at}: id`);
    seen.add(s.id);
    if (!["check", "action", "verify"].includes(s.kind)) p.push(`${at}: kind`);
    if (typeof s.run !== "function") p.push(`${at}: run`);
    if (s.kind === "action" && typeof s.rollback !== "function" && s.irreversible !== true) p.push(`${at}: rollback`);
    if (s.kind === "action" && s.irreversible === true && s.requiresApproval !== true) p.push(`${at}: approval`);
  });
  const lastAction = steps.map((s) => s.kind).lastIndexOf("action");
  if (lastAction >= 0 && !steps.slice(lastAction + 1).some((s) => s.kind === "verify")) p.push("verify");
  if (p.length) throw fail("INVALID_RUNBOOK", { problems: p });
  return Object.freeze({ ...rb, steps: Object.freeze([...steps]) });
}

export function createIncident({ id, title, severity = "sev3", now = Date.now }) {
  if (!SEVERITIES[severity]) throw fail("BAD_SEVERITY");
  const openedAt = now();
  const timeline = [];
  const at = {};
  const roles = {};
  let status = "open", lastUpdateAt = openedAt;
  const log = (type, message, data) => {
    const e = { at: now(), type, message: redact(message) };
    if (data !== undefined) e.data = redact(data);
    timeline.push(e);
    return e;
  };
  log("open", `${severi
…

$ node lab.js
① runbook من غير verify بعد الـ action:
   INVALID_RUNBOOK: restart: approval | verify

② الساعة تلاتة الفجر، الـ alert ضرب:
   بعد ستاشر دقيقة من غير ack: overdue = ["ack"] ← الـ pager يصعّد للـ secondary

③ dry run الأول:
   dry_run: blocked = 1، و idle in transaction = 1، والـ actions: pause-export dry_run، terminate dry_run

④ التشغيل الحقيقي، والـ commander بيوافق:
   approval؟ terminate: هيقتل 1 connection ← mona: موافقة
   succeeded: terminated = 1، و blocked بعدها = 0، والـ checkout: خلص

⑤ runbook الـ verify بتاعه فشل ← rollback:
   verify_failed، و rolledBack = ["pause-export"]، و nightly-export = true، و pg-lock-pileup-v0: verify failed → page team-db

⑥ الـ postmortem:
   # Postmortem: Checkout معلّق
   Severity: sev2 | TTA: 16 min | TTM: 19 min | TTR: 44 min
   Commander: mona
   
   ## Impact
   الـ checkout معلّق تسعتاشر دقيقة
   
   ## Root cause
   الـ nightly export فتح transaction ونسي الـ commit
   
   ## Timeline
   - T+00:00 [open] sev2: Checkout معلّق
   - T+00:00 [alert] PgBlockedQueries > 0 for 2m (db: postgres://app:***@localhost:5432/app)
   - T+16:00 [acknowledged] acknowledged by mona
   - T+16:00 [role] scribe: omar
   - T+16:00 [update] 
…

الأول: runbook بيعمل restart من غير approval ومن غير verify، واترفض قبل ما يشتغل. التاني: الـ alert ضرب، وعدّى ستاشر دقيقة من غير ack، فـ overdue قالت ack، والـ pager هيصعّد. التالت: الـ dry run لقى query واحدة مستنية، و connection واحدة idle in transaction، والـ actions ما اشتغلتش. الرابع: التشغيل الحقيقي، والـ commander وافق، والـ connection اتقتلت، والـ checkout المستني خلص. الخامس: verify فشل، والـ flag رجع، والـ team اتصعّد لها. والسادس: الـ postmortem، والـ connection string في الـ timeline من غير password. ونشغّل test dot js.

$ node test.js
✅ 1 redact: الـ keys الحسّاسة، والـ password في الـ URL، و Bearer، وجوّه arrays {"url":"postgres://app:***@db:5432/app","password":"[REDACTED]","nested":[{"apiKey":"[REDACTED]","note":"Authorization: Bearer ***"}],"n":5}
✅ 2 defineRunbook بيرفض: id، و alert ناقص، و severity، و id مكرر، و action من غير rollback، و irreversible من غير approval، و kind غلط، ومفيش verify ["id","alert","severity","a: id","a: rollback","b: approval","c: kind","verify"]
✅ 3 runbook سليم ← frozen، ومن غير actions مش محتاج verify 
✅ 4 الـ statuses بالترتيب بس: mitigated قبل ack ← BAD_TRANSITION، و ack بيعيّن الـ commander {"status":"acknowledged","roles":{"commander":"mona"}}
✅ 5 overdue بالـ SLA بتاع الـ severity: ack بعد خمس دقايق، و update كل نص ساعة [[],["ack"],["update"],[]]
✅ 6 metrics: TTA و TTM و TTR من وقت الفتح {"ttaMs":180000,"ttmMs":3000000,"ttrMs":4200000}
✅ 7 الـ happy path: checks، و when بيعمل skip، و actions، و verify ← succeeded ["count: ok","noop: skipped","disable-flag: ok","purge: approved","purge: ok","verify: ok"]
✅ 8 dry run: الـ checks بتشتغل، والـ actions والـ verify لأ، ومن غير approval {"count":{"status":"ok","errors":7},"noop":{"status":"skipped"},"disable-flag":{
…

كله نجح. في الـ lab، الحل كان إننا قتلنا connection. بس إيه اللي بيحصل للـ requests اللي كانت شغّالة لما الـ pod نفسه بيتقتل في deploy؟ الدرس الجاي: الـ graceful shutdown. إزاي الـ process يقفل من غير ما يضيّع ولا request، ولا job، ولا transaction.

// runbook.naive.js: الـ runbook زي ما بيتكتب في أغلب الشركات، ومحدش فتحه من سنة
// الـ wiki:
// # Database slow
// 1. ادخل على الـ database وشوف فيه إيه       ← إزاي؟ بأنهي user؟ أشوف إيه بالضبط؟
// 2. لو فيه queries معلّقة اعملها kill          ← أنهي queries؟ معلّقة من قد إيه؟
//    psql postgres://admin:Pa55w0rd@prod-db/app   ← الـ password في الـ wiki
//    select pg_terminate_backend(pid) from pg_stat_activity;  ← بيقتل كل الـ connections، ومنهم الـ replication
// 3. لو ما اتحلّتش، اعمل restart للـ database   ← من غير approval، ومن غير ما تعرف ده هيعمل إيه
// 4. كلّم أحمد                                    ← أحمد ساب الشركة من سنة
//
// وأثناء الـ incident:
// - خمسة بيكتبوا commands في نفس الوقت، ومحدش عارف مين عمل إيه
// - محدش عمل acknowledge للـ alert، فالـ pager فضل يرن عشرين دقيقة
// - الـ status page ما اتحدّثتش ساعة
// - الـ postmortem: "الـ root cause: محمد عمل kill غلط" ← blame، ومفيش action items ليها owner

// والـ script اللي حد كتبه "عشان يسرّع":
import pg from "pg";
const c = new pg.Client("postgres://admin:Pa55w0rd@prod-db/app"); // الـ password في الـ repo
await c.connect();
await c.query("select pg_terminate_backend(pid) from pg_stat_activity where pid <> pg_backend_pid()"); // من غير dry run ولا approval
console.log("fixed"); // من غير verify: مين قال إنه اتصلّح؟