Files

T

DongHyeonka d71669eb59 fix: 하네스 제거 및 keycloak 문서 보강

2026-07-25 12:53:13 +09:00

12 KiB

Raw Permalink Blame History

title, source_type, url, url_secondary, archive_url, status, confidence, tags, related_projects, related_branches, created, last_reviewed

title

source_type

url

url_secondary

archive_url

status

confidence

Google SRE Workbook — On-Call & Monitoring (공식 참조)

Layer: raw/official-docs/ — Google SRE Workbook 의 원문 발췌·출처 기록. Strength 분류: official-reference — Google SRE Workbook 은 community consensus 형성 문헌(O'Reilly 출판 + Google 내부 사례 기반)이며, 특정 vendor product 의 공식 문서가 아니다. Spring/Keycloak/AWS 같은 product-doc 과 동급으로 인용하지 말 것. 검증된 요약은 /ingest 후 wiki/concepts/ 에 source-summary 로 별도 작성. 원본은 raw 영구 보관.

Parent / 활용 branch (필수)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-operational-runbook-contract	D2 (runbook 을 operational artifact 로 명문화) 의 근거 — SRE 문헌에서 playbook 이 alert response 의 표준 컴포넌트로 정의됨. D10 (error registry ↔ runbook coupling) 의 근거 — "alert 마다 대응되는 playbook entry 가 있어야 한다" 원칙.

컨텍스트

feature-operational-runbook-contract 는 알람 발생 시 운영자가 따라야 할 표준 절차(runbook) 와 에러 코드 레지스트리의 coupling 규칙을 정의한다. SRE Workbook 의 On-Call 챕터는 playbook 이 alert 의 표준 동반 자산 이라는 입장을 명문화하며, 운영자 부하·MTTR·human-error 감소가 그 정당성이라고 진술한다. 본 raw 는 D2/D10 결정의 외부 근거로 보관.

출처 / Source

원본 URL (메인 — On-Call 챕터): https://sre.google/workbook/on-call/
원본 URL (보조 — Monitoring 챕터): https://sre.google/workbook/monitoring/
아카이브 URL: (미수집 — 추후 archive.org 스냅샷 추가)
저자 / 조직: Google SRE / O'Reilly Media — Site Reliability Workbook (Beyer, Murphy, Rensin, et al.)
발행일: 2018 (서적 초판) / web 판본은 rolling
마지막 확인일: 2026-05-27

핵심 인용 / Key quotes (verbatim)

[§On-Call, opening definition] "Being on-call means being available during a set period of time, and being ready to respond to production incidents during that time with appropriate urgency."

[§On-Call, Recap] "At Google, the overall goal of being on-call is to provide coverage for critical services, while making sure that we never achieve reliability at the expense of an on-call engineer's health."

[§On-Call, Recap] "We target a maximum of two incidents per on-call shift, to ensure adequate time for follow-up."

[§On-Call, Forming a New Team] "Playbooks contain high-level instructions on how to respond to automated alerts. They explain the severity and impact of the alert, and include debugging suggestions and possible actions to take to mitigate impact and fully resolve the alert."

[§On-Call, Forming a New Team] "In SRE, whenever an alert is created, a corresponding playbook entry is usually created. These guides reduce stress, the mean time to repair (MTTR), and the risk of human error."

[§On-Call, Anatomy of Pager Load — Alerting] "Just like new code, new alerts should be thoroughly and thoughtfully reviewed. Each alert should have a corresponding playbook entry."

[§On-Call, Identification delay] "Ensure pages link to relevant monitoring consoles, and that consoles highlight where the system is operating out of specification."

[§Monitoring, Dependencies] "When choosing the metrics to graph, keep the four golden signals in mind."

[§Monitoring, Alert classification] "It's helpful to be able to classify alerts: multiple categories of alerts allow for proportional responses. The ability to set different severity levels for different alerts is also useful: you might file a ticket to investigate a low rate of errors that lasts more than an hour, while a 100% error rate is an emergency that deserves immediate response."

Claims Extracted / 추출된 주장

자료가 직접 말하는 것만 claim 으로 분리. 내 프로젝트에 적용한 결론은 여기 쓰지 않음.

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
SRE-WB-OC-C1	On-call 의 정의는 "지정된 시간 동안 production incident 에 적절한 긴급도로 응답할 수 있는 상태"	[§On-Call] "Being on-call means being available during a set period of time, and being ready to respond to production incidents during that time with appropriate urgency."	`official-reference`	SRE 모델을 채택하는 조직의 on-call 정의	모든 조직이 동일 on-call 정의를 사용해야 한다는 뜻은 아님 (DevOps/NOC 모델은 별도)
SRE-WB-OC-C2	Google 의 on-call 목표는 "critical service coverage" 와 "engineer health" 양립이며 신뢰성을 엔지니어 건강과 맞바꾸지 않는다	[§On-Call, Recap] "we never achieve reliability at the expense of an on-call engineer's health."	`official-reference`	SRE 문화를 채택하는 조직의 on-call 정책 설계	Google 외 조직에서도 동일 목표가 실현 가능하다는 뜻은 아님 (인원 규모·서비스 critical 도 차이)
SRE-WB-OC-C3	Google SRE 는 shift 당 incident 2건을 상한으로 목표 (follow-up 시간 확보 목적)	[§On-Call, Recap] "We target a maximum of two incidents per on-call shift, to ensure adequate time for follow-up."	`official-reference`	Google 의 on-call rotation 운영	다른 조직의 "적정 incident 수" 가 동일해야 한다는 뜻은 아님 — Google 내부 target 의 보고
SRE-WB-OC-C4	Playbook 은 자동 alert 에 대한 high-level 대응 지침이며 severity/impact/debugging suggestion/mitigation action 을 포함한다	[§On-Call, Forming a New Team] "Playbooks contain high-level instructions on how to respond to automated alerts. They explain the severity and impact of the alert, and include debugging suggestions and possible actions to take to mitigate impact and fully resolve the alert."	`official-reference`	runbook/playbook 의 구성 요소 정의	모든 조직이 playbook 에 동일 4요소를 포함해야 한다는 표준은 아님 (SRE 문헌의 권고)
SRE-WB-OC-C5	SRE 에서는 alert 생성 시 대응 playbook entry 도 함께 생성 하는 것이 일반적이며, 이는 stress·MTTR·human error 를 감소시킨다	[§On-Call, Forming a New Team] "whenever an alert is created, a corresponding playbook entry is usually created. These guides reduce stress, the mean time to repair (MTTR), and the risk of human error."	`official-reference`	alert ↔ runbook 1:1 coupling 원칙의 근거	"1:1 coupling 이 모든 환경에서 효율적" 이라는 정량 증명은 본 문헌이 직접 제공하지 않음 (정성적 권고)
SRE-WB-OC-C6	새 alert 는 신규 코드와 동일하게 review 되어야 하며, 각 alert 에는 대응되는 playbook entry 가 있어야 한다	[§Anatomy of Pager Load — Alerting] "Just like new code, new alerts should be thoroughly and thoughtfully reviewed. Each alert should have a corresponding playbook entry."	`official-reference`	alert pipeline 의 governance / review 정책	review 절차의 구체적 형식(PR/체크리스트 등) 까지는 본 인용이 규정하지 않음
SRE-WB-OC-C7	Page (alert 통지) 는 관련 monitoring console 로 link 해야 하며, console 은 spec 이탈 지점을 강조해야 한다	[§Identification delay] "Ensure pages link to relevant monitoring consoles, and that consoles highlight where the system is operating out of specification."	`official-reference`	alert 메시지 본문 설계 (link/context 포함)	"alert 메시지에 반드시 runbook URL 도 포함" 이라는 명시적 권고는 본 인용에 없음 (console link 권고만 직접 진술)
SRE-WB-OC-C8	메트릭 선정 시 four golden signals 를 염두에 두어야 한다 (Latency/Traffic/Errors/Saturation — SRE Book 참조)	[§Monitoring] "When choosing the metrics to graph, keep the four golden signals in mind."	`official-reference`	모니터링 대시보드 / 메트릭 선택	본 chapter 자체에는 4개 signal 의 정의는 없음 — SRE Book 의 hyperlink 참조
SRE-WB-OC-C9	alert classification (severity level) 은 proportional response 를 가능하게 하며, 낮은 error rate 는 ticket, 100% error 는 즉시 emergency 로 분류 가능	[§Monitoring] "It's helpful to be able to classify alerts: multiple categories of alerts allow for proportional responses…"	`official-reference`	alert severity 정책 설계	severity level 의 표준 개수(예: P1/P2/P3) 가 정해진다는 뜻은 아님 — 분류 자체의 유용성을 진술

Usage Boundaries / 적용 경계

이 자료가 직접 증명하는 것:
- SRE-WB-OC-C4, C5, C6: alert 와 playbook 의 1:1 coupling 이 SRE 문헌상 권고됨 (D10 의 외부 근거로 인용 가능)
- SRE-WB-OC-C7: alert 메시지에 monitoring console link 를 포함하는 패턴이 공식 권고됨
- SRE-WB-OC-C8, C9: 메트릭 선정·alert severity 분류의 기본 원칙
이 자료가 증명하지 않는 것:
- runbook 의 구체적 markdown 템플릿 / 필드 구조 (SRE 문헌은 "playbook 에 무엇이 들어가야 하는가" 까지 진술하나, 파일 포맷·필드 schema 는 규정하지 않음)
- error code ↔ runbook 1:1 mapping 이 alert ↔ playbook 1:1 mapping 과 동치라는 점 — error registry 라는 개념 자체는 SRE Workbook 에 직접 등장하지 않음. D10 은 SRE 의 alert-playbook coupling 원칙을 error-runbook coupling 으로 확장 적용 한 것이며, 그 확장은 본 raw 가 직접 보증하지 않는다 (UNSUPPORTED_EXTENSION 경계)
- "alert 메시지에 runbook URL 을 포함하라" 는 직접 권고는 본 raw 의 인용 범위 내에 없음 (C7 은 monitoring console link 까지만 명시). runbook URL 포함 권고는 별도 출처 필요
- Google 의 "shift 당 incident 2건" target (C3) 이 다른 조직의 기준이 될 수 있다는 보장
내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- feature-operational-runbook-contract 의 runbook 템플릿 필드 (예: Symptoms, Diagnosis, Mitigation, Rollback) 가 본 raw 의 C4 ("severity/impact/debugging/mitigation") 와 매핑되는지 — 매핑 분석은 wiki/concepts 의 source-summary 에서 수행
- error code 레지스트리 ↔ runbook 매핑(D10) 의 추가 외부 근거 — SRE 외 자료 (예: PagerDuty / Atlassian runbook 가이드) 보강 필요

메모 / Notes

본 raw 는 두 chapter 를 묶어 보관 — 운영상 on-call 과 monitoring 의 alerting 원칙이 D2/D10 결정에 동시 인용되기 때문. wiki 추출 시 두 source-summary 로 분리할지 단일 문서로 둘지는 추출 시점에 판단.
C7 의 "pages link to monitoring consoles" 는 D2 의 "runbook URL 을 alert 본문에 포함" 결정과 정확히 동일하지 않음 — alert → console 까지만 직접 보증, alert → runbook 은 C5/C6 의 "alert ↔ playbook coupling" 원칙으로 간접 뒷받침. wiki 옮길 때 이 간접성 명시 필수.
Spring/Keycloak/Caddy 문서와 동급으로 "공식 best practice" 라 인용하지 말 것. Strength = official-reference (community consensus), NOT official-vendor-doc.

같은 주제 다른 raw 자료: (현재 없음 — 추후 PagerDuty / Atlassian runbook 가이드 보강 시 추가)
이 자료를 인용한 wiki 요약: (미작성)
이 자료를 인용하는 branch: raw/branch-notes/feature-operational-runbook-contract
인용하는 project: raw/project-notes/ca-skeleton-operational-contract

12 KiB Raw Permalink Blame History