diff --git a/.azure/deployment-plan.md b/.azure/deployment-plan.md index b634133a..6956d92b 100644 --- a/.azure/deployment-plan.md +++ b/.azure/deployment-plan.md @@ -12,9 +12,9 @@ Generated: 2026-08-12T03:35:07Z **Path:** Add Components -**Design:** `docs/superpowers/specs/2026-08-12-azure-sre-agent-event-testing-design.md` +**Design:** `monitor/sre-agent-event-lab/README.md` -**Execution plan:** `docs/superpowers/plans/2026-08-12-azure-sre-agent-event-testing-execution.md` +**Execution plan:** `monitor/sre-agent-event-lab/README.md` --- @@ -43,7 +43,7 @@ The current Azure CLI context matches the recorded subscription. Korea Central s | Azure infrastructure | IaC | Bicep | `monitor/sre-agent-event-lab/infra/` | | Deployment and incident tooling | Operations | Azure CLI, Bash, Python | `monitor/sre-agent-event-lab/scripts/` | | Agent knowledge | Runbook | Markdown | `monitor/sre-agent-event-lab/runbooks/` | -| Results | Report | Markdown | `docs/superpowers/reports/2026-08-12-azure-sre-agent-event-testing-results.md` | +| Results | Report | Markdown | `monitor/sre-agent-event-lab/validation-results.md` | --- diff --git a/docs/superpowers/plans/2026-07-15-hdinsight-kafka-lag-scaled-test-execution.md b/docs/superpowers/plans/2026-07-15-hdinsight-kafka-lag-scaled-test-execution.md deleted file mode 100644 index 4dd33e1e..00000000 --- a/docs/superpowers/plans/2026-07-15-hdinsight-kafka-lag-scaled-test-execution.md +++ /dev/null @@ -1,414 +0,0 @@ -# HDInsight Kafka Consumer Lag — 비율 축소 실증 테스트 실행 계획 - -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. 이 계획은 코드가 아니라 **Azure 운영 런북**이므로 각 Task는 TDD 대신 "명령 실행 → 기대 출력 확인 → 결과 기록" 사이클을 따른다. - -**Goal:** 기존 HDInsight Kafka 테스트베드에서 consumer lag를 재현하고, 부하·브로커 사이징을 비율로 조절해 "lag 1분 이내 회복"이 가능함을 실측 데이터로 증명한다. - -**Architecture:** 클러스터는 프라이빗이므로 모든 Kafka 작업은 동일 VNet 안의 `vm-kafka-loadgen`에서 `az vm run-command invoke`로 실행한다. 부하 생성/소비는 전용 클라이언트 VM(perf-test)으로 브로커에서 격리하고, 모니터링은 기존 Prometheus+Grafana(`vm-monitoring`)로 관측한다. Baseline→Arm A(부하 축소)를 핵심 증명으로 실행하고, Arm B(브로커 RAM)는 시간·예산 게이트로 진행한다. - -**Tech Stack:** Azure HDInsight 5.1 (Kafka 3.2.0), Apache Kafka perf-test CLI, Prometheus + Grafana, `az cli` / `az vm run-command`. - -## Global Constraints - -- 구독: `95933ae5-0201-4a21-a1fc-8051a7437982` (contoso / ME-MngEnvMCAP310512-inhwanhwang-3) -- 리소스 그룹: `rg-krafton-kafka-dev-jpe` (japaneast) -- 클러스터: `krafton-kafka-hdi-68944` (현재 3×`Standard_D4ads_v5` 워커=브로커, 16 GB RAM, 데이터디스크 2/노드) -- Ambari(내부에서만): `https://krafton-kafka-hdi-68944.azurehdinsight.net`, 계정 `admin` / `KfkBDQPfW9NyC6!7` -- 로드젠 VM: `vm-kafka-loadgen` (현재 `Standard_B2s`, 부하생성용으로 `Standard_D8s_v5`로 리사이즈) -- 모니터링 VM: `vm-monitoring` (Prometheus + Grafana), 매니지드 Grafana `grafana-krafton-68944` -- 예산: **오늘 1일, $1000 이내.** money보다 HDInsight 재생성 시간이 실질 제약. 각 Arm 종료 후 유휴 VM은 즉시 deallocate. -- 프라이빗 클러스터 → 외부에서 브로커 접속 불가. **반드시** `az vm run-command invoke -n vm-kafka-loadgen` 경유. -- 결과는 `docs/superpowers/reports/2026-07-15-hdinsight-kafka-lag-results.md` 리빙 문서에 Arm별로 갱신(한눈에 보이는 표 중심). -- 테스트 토픽: `lag-test`, 파티션 30, RF 2 (프로덕션 180파티션/18브로커 = 브로커당 10 → 3브로커 테스트베드 = 30파티션으로 브로커당 10 동일). -- 각 명령 실행 위치는 명시(로컬 `az` vs 로드젠 VM `run-command`). - ---- - -## 축소 매핑 요약 (왜 이 테스트가 유효한가) - -| 지표 | 프로덕션 | 테스트베드 | 매핑 | -|---|---|---|---| -| 브로커 수 | 18 | 3 | k=6 축소 | -| 브로커당 RAM | 32 GB | 16 GB | 캐시 1/2 → 부하도 1/2로 맞춰 ρ 보존 | -| 브로커당 리더 파티션 | 10 | 10 | 동일 (30파티션/3브로커) | -| per-broker page cache | ~20 GB | ~10 GB | — | -| T_cache 목표 | ~8분 | ~8분 | per-broker 유입률을 `cache/8min`으로 설정 | -| 테스트베드 총 목표 produce율 | — | ~10GB/8min×3 ≈ **60 MB/s** | 로드젠에서 `--throughput`으로 고정 | - -핵심: per-broker `ρ = 유입률/캐시`를 프로덕션과 맞추면, 3브로커 테스트베드가 18브로커 중 브로커 1대의 캐시 축출 동역학을 재현한다. Baseline에서 T_cache급(수 분) lag를 유발하고, 부하를 낮추면(Arm A) 회복<1분이 되는 임계를 찾는다. - ---- - -## Phase 0 — 환경 준비 - -### Task 0.1: 모니터링·로드젠 VM 기동 및 로드젠 리사이즈 - -**Files:** 없음 (Azure 작업) - -- [ ] **Step 1: 구독 고정** - -로컬 실행: -```bash -az account set --subscription 95933ae5-0201-4a21-a1fc-8051a7437982 -``` - -- [ ] **Step 2: 로드젠 VM을 D8s_v5로 리사이즈 (deallocated 상태에서)** - -로컬 실행: -```bash -az vm resize -g rg-krafton-kafka-dev-jpe -n vm-kafka-loadgen --size Standard_D8s_v5 -``` -Expected: VM 정의가 `Standard_D8s_v5`로 갱신 (deallocated라 즉시 반영). - -- [ ] **Step 3: 모니터링·로드젠 VM 기동** - -로컬 실행: -```bash -az vm start -g rg-krafton-kafka-dev-jpe -n vm-monitoring -az vm start -g rg-krafton-kafka-dev-jpe -n vm-kafka-loadgen -``` -Expected: 두 VM 모두 `VM running`. - -- [ ] **Step 4: 전원 상태 확인** - -로컬 실행: -```bash -az vm list -g rg-krafton-kafka-dev-jpe -d --query "[].{name:name,size:hardwareProfile.vmSize,power:powerState}" -o table -``` -Expected: `vm-kafka-loadgen Standard_D8s_v5 VM running`, `vm-monitoring ... VM running`. - -### Task 0.2: 로드젠 VM에 Kafka 클라이언트 설치 + 브로커 검색 - -**Files:** 없음 (로드젠 VM 내부 구성) - -- [ ] **Step 1: JDK + Kafka 3.2.0 클라이언트 설치** - -로컬 실행 (run-command): -```bash -az vm run-command invoke -g rg-krafton-kafka-dev-jpe -n vm-kafka-loadgen --command-id RunShellScript --scripts ' -set -e -if [ ! -d /opt/kafka ]; then - sudo apt-get update -y -qq - sudo apt-get install -y -qq openjdk-11-jre-headless wget - cd /opt - sudo wget -q https://archive.apache.org/dist/kafka/3.2.0/kafka_2.12-3.2.0.tgz - sudo tar xzf kafka_2.12-3.2.0.tgz - sudo mv kafka_2.12-3.2.0 kafka -fi -/opt/kafka/bin/kafka-topics.sh --version -java -version 2>&1 | head -1 -' --query "value[0].message" -o tsv -``` -Expected: `3.2.0` 및 java 버전 출력. (설치 최초 1회 수 분 소요.) - -- [ ] **Step 2: Ambari에서 브로커 호스트 검색 → bootstrap 문자열 생성** - -로컬 실행 (run-command): -```bash -az vm run-command invoke -g rg-krafton-kafka-dev-jpe -n vm-kafka-loadgen --command-id RunShellScript --scripts ' -CL=$(curl -s -u "admin:KfkBDQPfW9NyC6!7" "https://krafton-kafka-hdi-68944.azurehdinsight.net/api/v1/clusters" | python3 -c "import sys,json;print(json.load(sys.stdin)[\"items\"][0][\"Clusters\"][\"cluster_name\"])") -BROKERS=$(curl -s -u "admin:KfkBDQPfW9NyC6!7" "https://krafton-kafka-hdi-68944.azurehdinsight.net/api/v1/clusters/$CL/services/KAFKA/components/KAFKA_BROKER" | python3 -c "import sys,json;d=json.load(sys.stdin);print(\",\".join(h[\"HostRoles\"][\"host_name\"]+\":9092\" for h in d[\"host_components\"]))") -echo "CLUSTER=$CL" -echo "BOOTSTRAP=$BROKERS" -echo "$BROKERS" | sudo tee /opt/kafka/bootstrap.txt -' --query "value[0].message" -o tsv -``` -Expected: `BOOTSTRAP=wn0-...:9092,wn1-...:9092,wn2-...:9092` 3개. `/opt/kafka/bootstrap.txt` 저장. - -- [ ] **Step 3: 브로커 연결 확인** - -로컬 실행 (run-command): -```bash -az vm run-command invoke -g rg-krafton-kafka-dev-jpe -n vm-kafka-loadgen --command-id RunShellScript --scripts ' -BS=$(cat /opt/kafka/bootstrap.txt) -/opt/kafka/bin/kafka-broker-api-versions.sh --bootstrap-server "$BS" 2>&1 | head -5 -' --query "value[0].message" -o tsv -``` -Expected: 각 브로커가 응답(`... (id: 100X rack: ...)`). 실패 시 NSG/포트 9092 확인. - -### Task 0.3: 테스트 토픽 생성 + 모니터링 확인 - -**Files:** 없음 - -- [ ] **Step 1: `lag-test` 토픽 생성 (30 파티션, RF 2)** - -로컬 실행 (run-command): -```bash -az vm run-command invoke -g rg-krafton-kafka-dev-jpe -n vm-kafka-loadgen --command-id RunShellScript --scripts ' -BS=$(cat /opt/kafka/bootstrap.txt) -/opt/kafka/bin/kafka-topics.sh --bootstrap-server "$BS" --create --if-not-exists --topic lag-test --partitions 30 --replication-factor 2 --config retention.ms=129600000 --config max.message.bytes=1000000 --config segment.bytes=1073741824 -/opt/kafka/bin/kafka-topics.sh --bootstrap-server "$BS" --describe --topic lag-test | head -3 -' --query "value[0].message" -o tsv -``` -Expected: `Topic: lag-test PartitionCount: 30 ReplicationFactor: 2`. - -- [ ] **Step 2: Grafana/Prometheus 도달 확인 (모니터링 VM 경유)** - -로컬 실행 (run-command): -```bash -az vm run-command invoke -g rg-krafton-kafka-dev-jpe -n vm-monitoring --command-id RunShellScript --scripts ' -curl -s -o /dev/null -w "prometheus %{http_code}\n" http://localhost:9090/-/ready -curl -s "http://localhost:9090/api/v1/query?query=kafka_brokers" | head -c 200; echo -curl -s -o /dev/null -w "grafana %{http_code}\n" http://localhost:3000/api/health -' --query "value[0].message" -o tsv -``` -Expected: `prometheus 200`, `kafka_brokers` 값 반환, `grafana 200`. (지표 미수집 시 kafka-exporter/JMX 타깃 점검.) - -- [ ] **Step 3: 결과 리포트 파일 초기화 (로컬)** - -`docs/superpowers/reports/2026-07-15-hdinsight-kafka-lag-results.md` 생성, 아래 "결과 리포트 템플릿" 섹션 내용으로 초기화 후 커밋. -```bash -git add docs/superpowers/reports/2026-07-15-hdinsight-kafka-lag-results.md -git commit -m "docs(hdinsight): init lag test results report - -Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>" -``` - ---- - -## Phase 1 — Baseline (lag 재현) - -### Task 1.1: 부하 프로파일 캘리브레이션 (목표 ~60 MB/s produce) - -**Files:** 없음 - -- [ ] **Step 1: 워밍업 produce로 처리량 상한 확인** - -로드젠에서 무제한 produce 30초 → 달성 MB/s 확인. record-size 1MB(프로덕션 max.message 정렬), 하지만 60MB/s = 60 msg/s로는 파티션 분배가 거칠어 record-size 10KB, throughput=6000 msg/s(≈60MB/s)로 설정. - -로컬 실행 (run-command): -```bash -az vm run-command invoke -g rg-krafton-kafka-dev-jpe -n vm-kafka-loadgen --command-id RunShellScript --scripts ' -BS=$(cat /opt/kafka/bootstrap.txt) -/opt/kafka/bin/kafka-producer-perf-test.sh --topic lag-test --num-records 300000 --record-size 10240 --throughput -1 --producer-props bootstrap.servers=$BS acks=1 compression.type=lz4 2>&1 | tail -2 -' --query "value[0].message" -o tsv -``` -Expected: `... records/sec, ... MB/sec` — 달성 MB/s 기록. 60MB/s 미달이면 record-size/throughput 조정, 초과 가능하면 60MB/s로 상한. - -- [ ] **Step 2: 캘리브레이션 값 기록** - -달성 produce율(MB/s), 이를 60MB/s로 고정하기 위한 `--throughput`(msg/s) 값을 리포트 "캘리브레이션" 행에 기록. - -### Task 1.2: Baseline 부하 실행 + lag 유발/회복 측정 - -**Files:** 없음 - -- [ ] **Step 1: 컨슈머 그룹을 느리게(뒤처짐 유발) 상태로 준비** - -컨슈머는 `kafka-consumer-perf-test.sh` 대신, "피크 중 소비율 < produce율"을 만들기 위해 **produce를 먼저 일정량 선적재(backlog) 후 소비 시작**하는 방식으로 lag를 유발한다. - -- [ ] **Step 2: Baseline 시나리오 — 60MB/s로 8분 produce, 2분 후 소비 시작** - -로컬 실행 (run-command, 백그라운드 produce + 지연 소비). 스크립트가 produce를 nohup으로 띄우고, 120초 뒤 컨슈머를 붙여 lag 곡선을 만든다: -```bash -az vm run-command invoke -g rg-krafton-kafka-dev-jpe -n vm-kafka-loadgen --command-id RunShellScript --scripts ' -BS=$(cat /opt/kafka/bootstrap.txt) -GROUP=lag-baseline -# produce ~8분치: 6000 msg/s * 480s = 2.88M, record 10KB -nohup /opt/kafka/bin/kafka-producer-perf-test.sh --topic lag-test --num-records 2880000 --record-size 10240 --throughput 6000 --producer-props bootstrap.servers=$BS acks=1 compression.type=lz4 >/tmp/prod_baseline.log 2>&1 & -echo "producer started pid $!" -sleep 120 -# 소비를 produce보다 약간 느리게: 단일 소비프로세스로 시작(파티션 30개를 1 컨슈머가 → 자연 지연) -nohup /opt/kafka/bin/kafka-console-consumer.sh --bootstrap-server $BS --topic lag-test --group $GROUP --from-beginning >/tmp/cons_baseline.log 2>&1 & -echo "consumer started pid $!" -' --query "value[0].message" -o tsv -``` -Expected: producer/consumer PID 출력. - -- [ ] **Step 3: lag 곡선 폴링 (30초 간격, 최대 20분)** - -로컬 실행 (run-command 반복). consumer-group describe로 총 lag를 폴링: -```bash -az vm run-command invoke -g rg-krafton-kafka-dev-jpe -n vm-kafka-loadgen --command-id RunShellScript --scripts ' -BS=$(cat /opt/kafka/bootstrap.txt) -for i in $(seq 1 40); do - TS=$(date +%H:%M:%S) - LAG=$(/opt/kafka/bin/kafka-consumer-groups.sh --bootstrap-server $BS --describe --group lag-baseline 2>/dev/null | awk "NR>1{s+=\$6} END{print s}") - echo "$TS total_lag=$LAG" - sleep 30 -done -' --query "value[0].message" -o tsv -``` -Expected: lag가 상승(수 분간 backlog 누적) → produce 종료(8분) 후 하강 → 0 복귀. **peak lag**, **produce 종료 시각**, **lag=0 복귀 시각** → 회복시간 산출. - -- [ ] **Step 4: Baseline 결과 기록** - -peak lag, 회복시간(초), 이 구간의 Grafana(디스크 read MB/s, page cache, under-replicated) 캡처 경로를 리포트 "Baseline" 행에 기록. 회복시간이 수 분급이면 lag 재현 성공. - -- [ ] **Step 5: 정리 (그룹/오프셋 리셋)** - -```bash -az vm run-command invoke -g rg-krafton-kafka-dev-jpe -n vm-kafka-loadgen --command-id RunShellScript --scripts ' -BS=$(cat /opt/kafka/bootstrap.txt) -pkill -f kafka-console-consumer || true; pkill -f kafka-producer-perf || true -/opt/kafka/bin/kafka-consumer-groups.sh --bootstrap-server $BS --delete --group lag-baseline 2>&1 | tail -1 -' --query "value[0].message" -o tsv -``` - ---- - -## Phase 2 — Arm A: 부하 축소 (핵심 증명) - -### Task 2.1: 부하 배율별 회복시간 측정 (75% / 50% / 25%) - -**Files:** 없음 - -- [ ] **Step 1: 각 배율 반복 실행 (Baseline과 동일 절차, `--throughput`만 변경)** - -75%=4500, 50%=3000, 25%=1500 msg/s. 각 배율마다 Task 1.2의 Step 2~5를 그룹명 `lag-armA-`로 반복. 스크립트(배율 변수화): -```bash -for PCT in 75 50 25; do - RATE=$((6000 * PCT / 100)) - GROUP=lag-armA-$PCT - az vm run-command invoke -g rg-krafton-kafka-dev-jpe -n vm-kafka-loadgen --command-id RunShellScript --scripts " -BS=\$(cat /opt/kafka/bootstrap.txt) -nohup /opt/kafka/bin/kafka-producer-perf-test.sh --topic lag-test --num-records \$(($RATE*480)) --record-size 10240 --throughput $RATE --producer-props bootstrap.servers=\$BS acks=1 compression.type=lz4 >/tmp/prod_$GROUP.log 2>&1 & -sleep 120 -nohup /opt/kafka/bin/kafka-console-consumer.sh --bootstrap-server \$BS --topic lag-test --group $GROUP --from-beginning >/tmp/cons_$GROUP.log 2>&1 & -echo started $GROUP rate=$RATE -" --query "value[0].message" -o tsv - # 이어서 Task 1.2 Step 3 폴링 스크립트를 그룹명만 바꿔 실행, 회복시간 기록, Step 5 정리 -done -``` -Expected: 배율이 낮아질수록 peak lag↓, 회복시간↓. 어느 배율에서 회복<60초가 되는지 임계 도출. - -- [ ] **Step 2: Arm A 결과표 기록 + 임계 부하 도출** - -리포트 "Arm A" 표에 배율·produce율(MB/s)·peak lag·회복시간(초) 기록. "회복<1분 임계 부하율" 명시. 프로덕션 환산: 임계 부하율 → "브로커 N대 증설 시 per-broker 유입률 = 임계율" 역산. - -- [ ] **Step 3: 커밋** - -```bash -git add docs/superpowers/reports/2026-07-15-hdinsight-kafka-lag-results.md -git commit -m "docs(hdinsight): record baseline + arm A load-scaling results - -Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>" -``` - ---- - -## Phase 3 — Arm B: 브로커 RAM 확대 (게이트 스트레치) - -> **게이트:** Phase 0~2 종료 후 남은 시간·예산 확인. HDInsight 재생성 ~20-30분 + 재테스트 ~20분. 여유 있을 때만 진행. 없으면 Phase 4로. - -### Task 3.1: 32 GB 브로커로 클러스터 재생성 - -**Files:** -- Modify: `~/.copilot/session-state/7b4d87cb-701e-412d-b7dc-fce27943d35c/files/hdi-kafka-template-public.json` (workernode vmSize → `Standard_D8a_v4`) - -- [ ] **Step 1: 템플릿 워커 SKU를 D8a_v4(32GB)로 변경** - -`hdi-kafka-template-public.json`의 `workernode` 역할 `hardwareProfile.vmSize`를 `Standard_D4ads_v5` → `Standard_D8a_v4`로 수정(디스크/카운트 유지). headnode/zk는 유지해 비용 억제. - -- [ ] **Step 2: 클러스터 삭제 후 재생성** - -로컬 실행: -```bash -az hdinsight delete -g rg-krafton-kafka-dev-jpe -n krafton-kafka-hdi-68944 --yes -az deployment group create -g rg-krafton-kafka-dev-jpe -n hdi-armB-$(date +%H%M%S) \ - --template-file ~/.copilot/session-state/7b4d87cb-701e-412d-b7dc-fce27943d35c/files/hdi-kafka-template-public.json -``` -Expected: 배포 성공, 클러스터 `Running`. (20-30분 소요.) - -- [ ] **Step 3: Task 0.2~0.3 재실행 (브로커 재검색, 토픽 재생성)** - -새 브로커 호스트로 `bootstrap.txt` 갱신, `lag-test` 토픽 재생성. - -### Task 3.2: Baseline 부하로 Arm B 측정 - -- [ ] **Step 1: Baseline과 동일 60MB/s 부하 재실행 (그룹 `lag-armB`)** - -Task 1.2 절차 그대로, 32GB 브로커에서 실행. Expected: T_cache 2배 → 같은 부하에서 peak lag↓, 회복시간↓. - -- [ ] **Step 2: Arm B 결과 기록 + 커밋** - -리포트 "Arm B" 행에 기록. Baseline(16GB) 대비 회복시간 개선률 명시. -```bash -git add -A && git commit -m "docs(hdinsight): record arm B broker RAM results - -Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>" -``` - ---- - -## Phase 4 — 결과 종합 및 정리 - -### Task 4.1: 결론·프로덕션 권고 작성 - -- [ ] **Step 1: 리포트 "결론" 섹션 작성** - -- Baseline에서 재현된 lag(peak/회복) → 프로덕션 7분과 자릿수 정합 확인 -- Arm A: 회복<1분 임계 부하율 X% → 프로덕션 환산 "브로커 18→N대 증설 또는 유입률 X% 절감" -- Arm B(수행 시): RAM 2배 → 회복시간 Y% 개선 → "브로커 RAM 상향" 정량 효과 -- 최소 비용 권고: 컨슈머 증설 무효(파티션 180 상한), 유효 레버는 [브로커 증설 / RAM↑ / 디스크 tier↑] - -- [ ] **Step 2: Arm C/D 후속 안내 명시** - -Arm C(Premium SSD, HDInsight 디스크 지원 확인 필요)·Arm D(AKS+실제 rdkafka fetch 튜닝)는 오늘 예산·시간 밖 → 후속 실행 항목으로 리포트에 명시. - -- [ ] **Step 3: 최종 커밋 + push** - -```bash -git add -A -git commit -m "docs(hdinsight): finalize lag scaled-test results and prod recommendation - -Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>" -git push origin main -``` - -### Task 4.2: 비용 정리 (teardown) - -- [ ] **Step 1: 유휴 VM deallocate** - -로컬 실행: -```bash -az vm deallocate -g rg-krafton-kafka-dev-jpe -n vm-kafka-loadgen -az vm deallocate -g rg-krafton-kafka-dev-jpe -n vm-monitoring -``` -Expected: 두 VM `deallocated`. - -- [ ] **Step 2: 클러스터 존치 여부 확인 (사용자 결정)** - -HDInsight는 정지 불가(비용 지속). 후속 Arm C/D 미실행 시 사용자에게 `teardown.sh` 실행 여부 확인. 무단 삭제 금지. - ---- - -## 결과 리포트 템플릿 (`docs/superpowers/reports/2026-07-15-hdinsight-kafka-lag-results.md` 초기 내용) - -```markdown -# HDInsight Kafka Lag 축소 실증 테스트 — 결과 - -- 실행일: 2026-07-15 | 리전: japaneast | 클러스터: krafton-kafka-hdi-68944 -- 목표: consumer lag "1분 이내 회복" 가능성 실증 - -## 한눈에 보기 - -| Arm | 구성 | 부하(produce) | Peak lag | 회복시간 | 판정 | -|---|---|---|---|---|---| -| 캘리브레이션 | 16GB×3 | 상한 측정 | — | — | ⏳ | -| Baseline | 16GB×3 | 60 MB/s (100%) | — | — | ⏳ | -| Arm A-75 | 16GB×3 | 45 MB/s (75%) | — | — | ⏳ | -| Arm A-50 | 16GB×3 | 30 MB/s (50%) | — | — | ⏳ | -| Arm A-25 | 16GB×3 | 15 MB/s (25%) | — | — | ⏳ | -| Arm B | 32GB×3 | 60 MB/s (100%) | — | — | ⏳ | - -판정: ✅ 회복<60s / ⚠️ 1-3분 / ❌ >3분 / ⏳ 미실행 - -## Arm별 상세 -(각 Arm: 실행 시각, produce 로그 요약, lag 폴링 원자료, Grafana 캡처 경로) - -## 결론 및 프로덕션 권고 -(Phase 4에서 작성) - -## 후속 (오늘 범위 밖) -- Arm C: Premium SSD 디스크 tier — HDInsight 지원 확인 후 -- Arm D: AKS + 실제 rdkafka fetch 파라미터 튜닝 -``` - ---- - -## Self-Review 체크 - -- **Spec 커버리지:** spec §3 테스트베드→Phase 0, §3.1 실행위치(VM)→Phase 0~2, §4 매트릭스 Baseline/A/B→Phase 1~3, C/D→Phase 4 후속 명시, §5 측정지표→lag 폴링+Grafana, §6 절차→Phase 순서, §7 제약(재생성 비용·teardown)→Phase 3 게이트+4.2. 커버됨. -- **범위:** 오늘/$1000 현실 반영 — Baseline+Arm A 보장, Arm B 게이트, C/D 후속. Money보다 시간이 제약임을 명시. -- **실행 모델 일관성:** 모든 Kafka 작업 `vm-kafka-loadgen` run-command 경유, bootstrap.txt 재사용. 그룹명 규칙 `lag-` 일관. diff --git a/docs/superpowers/plans/2026-08-12-azure-monitor-dynamic-thresholds-sre-integration-execution.md b/docs/superpowers/plans/2026-08-12-azure-monitor-dynamic-thresholds-sre-integration-execution.md deleted file mode 100644 index f86f8b9d..00000000 --- a/docs/superpowers/plans/2026-08-12-azure-monitor-dynamic-thresholds-sre-integration-execution.md +++ /dev/null @@ -1,102 +0,0 @@ -# Azure Monitor Dynamic Thresholds SRE Integration Implementation Plan - -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. - -**Goal:** Explain how the deterministic static-threshold lab evolves into a production Dynamic Threshold design without claiming an unexecuted result. - -**Architecture:** Keep the deployed one-minute static scheduled-query rules unchanged. Add a documentation-only operating model that maps the same numeric KQL signals to five-minute Dynamic Threshold shadow rules and reuses the tested Action Group → Logic App → SRE Agent bridge after the learning gate passes. - -**Tech Stack:** Markdown, Azure Monitor scheduled-query alerts, KQL, Azure SRE Agent HTTP Trigger bridge. - -## Global Constraints - -- State explicitly that Dynamic Thresholds were not executed in this session. -- Preserve the static rules as the source of all measured S1/S2/S3 results. -- Include the official minimum of three days and 30 samples before firing. -- Include the 10-day baseline window and three-week weekly-seasonality requirement. -- State that one-minute Log Search Dynamic Threshold rules are unsupported. -- Recommend numeric query results, Medium/Low sensitivity, and 2-of-4 violations. -- Reuse `ag-sre-agent-event-lab`; do not add unvalidated preview Bicep. - ---- - -### Task 1: Add the Static-to-Dynamic operating guide - -**Files:** -- Modify: `monitor/sre-agent-event-lab/README.md` -- Modify: `docs/superpowers/reports/2026-08-12-azure-sre-agent-event-testing-results.md` - -**Interfaces:** -- README produces the reusable configuration and rollout checklist. -- Results report produces the measured-vs-proposed distinction and operational recommendation. - -- [ ] **Step 1: Add a documentation contract check** - -Run after editing: - -```bash -for phrase in \ - "3일" \ - "30 samples" \ - "10일" \ - "3주" \ - "1분" \ - "미실증" \ - "ag-sre-agent-event-lab"; do - rg -q "$phrase" monitor/sre-agent-event-lab/README.md - rg -q "$phrase" \ - docs/superpowers/reports/2026-08-12-azure-sre-agent-event-testing-results.md -done -``` - -Expected before implementation: one or more commands exit nonzero. - -- [ ] **Step 2: Add README operating guidance** - -Add: - -- Static vs Dynamic decision table. -- S1/S2/S3 numeric KQL candidate table. -- Five-minute frequency, 15–20-minute window, Medium sensitivity, and 2-of-4 recommendation. -- Three-day/30-sample gate, 10-day baseline, and three-week seasonality caveat. -- Shadow mode rollout and existing Action Group bridge reuse. -- Official Dynamic Threshold link. - -- [ ] **Step 3: Add report recommendation** - -Add a “Static에서 Dynamic으로” section that: - -- says all current scores use static rules; -- explains why static was required for a same-day deterministic test; -- lists Dynamic candidate signals; -- labels Dynamic as `미실증`; -- describes the future comparison metrics: alert latency, pickup, conclusion, false positives, false negatives. - -- [ ] **Step 4: Verify** - -```bash -for phrase in \ - "3일" \ - "30 samples" \ - "10일" \ - "3주" \ - "1분" \ - "미실증" \ - "ag-sre-agent-event-lab"; do - rg -q "$phrase" monitor/sre-agent-event-lab/README.md - rg -q "$phrase" \ - docs/superpowers/reports/2026-08-12-azure-sre-agent-event-testing-results.md -done -git diff --check -``` - -Expected: all checks pass. - -- [ ] **Step 5: Commit** - -```bash -git add monitor/sre-agent-event-lab/README.md \ - docs/superpowers/reports/2026-08-12-azure-sre-agent-event-testing-results.md -git commit -m "docs(monitor): explain Dynamic Threshold SRE rollout" \ - -m "Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>" -``` diff --git a/docs/superpowers/plans/2026-08-12-azure-sre-agent-event-testing-execution.md b/docs/superpowers/plans/2026-08-12-azure-sre-agent-event-testing-execution.md deleted file mode 100644 index c86643e8..00000000 --- a/docs/superpowers/plans/2026-08-12-azure-sre-agent-event-testing-execution.md +++ /dev/null @@ -1,736 +0,0 @@ -# Azure SRE Agent Event Testing Implementation Plan - -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. - -**Goal:** Deploy an isolated Azure Container Apps workload, trigger three real Azure Monitor incidents, measure Azure SRE Agent's event-driven investigations, and publish an evidence-based results report. - -**Architecture:** A Python HTTP service runs on Azure Container Apps and sends request, exception, and Blob dependency telemetry to workspace-based Application Insights. Azure Monitor scheduled-query alerts turn deterministic HTTP 500, latency, and Storage RBAC failures into incidents; Azure SRE Agent receives them through its Azure Monitor incident platform and investigates in Review mode using the test resource group, observability connector, repository, and runbook. - -**Tech Stack:** Python 3.12, FastAPI, Azure Monitor OpenTelemetry, Azure Identity, Azure Blob Storage, pytest, Docker/ACR Tasks, Bicep, Azure CLI, Azure Container Apps, Log Analytics, Application Insights, Azure Monitor, Azure SRE Agent. - -## Global Constraints - -- Use subscription `95933ae5-0201-4a21-a1fc-8051a7437982` and region `koreacentral`. -- Create only resources in `rg-sre-agent-event-lab-krc`, except the Azure SRE Agent managed identity's required subscription-scope `Monitoring Contributor` role assignment. -- Apply `purpose=sre-agent-event-lab` and `expiresOn=2026-08-13` tags to created resources. -- Configure every incident response plan in `Review` mode. -- Do not grant the Agent Contributor access to the workload. -- Disable or delete the default `quickstart_handler` response plan before enabling custom plans. -- Run only one failure scenario at a time and verify recovery before starting the next. -- Never delete or change role assignments outside the test Storage container and the Agent's explicitly recorded role assignments. -- Record all test timestamps in UTC. -- Do not modify or commit unrelated existing worktree changes. - ---- - -## File Map - -| File | Responsibility | -|---|---| -| `monitor/sre-agent-event-lab/app/main.py` | FastAPI endpoints, deterministic failure modes, structured logs, Blob dependency call | -| `monitor/sre-agent-event-lab/app/telemetry.py` | Azure Monitor OpenTelemetry initialization | -| `monitor/sre-agent-event-lab/app/requirements.txt` | Runtime dependencies pinned to compatible major/minor versions | -| `monitor/sre-agent-event-lab/app/requirements-dev.txt` | pytest and HTTP test dependencies | -| `monitor/sre-agent-event-lab/app/tests/test_main.py` | Unit tests for normal, HTTP 500, latency, and dependency failure behavior | -| `monitor/sre-agent-event-lab/app/Dockerfile` | Reproducible Python 3.12 container | -| `monitor/sre-agent-event-lab/infra/main.bicep` | Resource group deployment entry point and outputs | -| `monitor/sre-agent-event-lab/infra/observability.bicep` | Log Analytics and Application Insights | -| `monitor/sre-agent-event-lab/infra/workload.bicep` | ACR, Storage, Container Apps environment/app, managed identity, Blob role assignment | -| `monitor/sre-agent-event-lab/infra/alerts.bicep` | Three scheduled-query alert rules scoped to the deployed application telemetry | -| `monitor/sre-agent-event-lab/infra/main.bicepparam` | Stable Korea Central deployment parameters | -| `monitor/sre-agent-event-lab/scripts/common.sh` | Subscription, names, outputs, precondition checks, evidence directory helpers | -| `monitor/sre-agent-event-lab/scripts/deploy.sh` | RG creation, Bicep deployment, ACR build, final app deployment | -| `monitor/sre-agent-event-lab/scripts/loadgen.py` | Bounded concurrent HTTP traffic generator with JSON summary | -| `monitor/sre-agent-event-lab/scripts/run-scenario.sh` | Inject, observe, and recover exactly one named scenario | -| `monitor/sre-agent-event-lab/scripts/query-evidence.sh` | Export Azure Monitor alert, App Insights, activity, and Container Apps evidence | -| `monitor/sre-agent-event-lab/scripts/cleanup.sh` | Remove recorded Agent role assignment and test RG safely | -| `monitor/sre-agent-event-lab/runbooks/incident-response.md` | Ground-truth-free investigation order and safe mitigations for the Agent | -| `monitor/sre-agent-event-lab/README.md` | Operator guide and test prerequisites | -| `docs/superpowers/reports/2026-08-12-azure-sre-agent-event-testing-results.md` | Living measured-results report | - ---- - -### Task 1: Build the instrumented failure-injection service - -**Files:** -- Create: `monitor/sre-agent-event-lab/app/main.py` -- Create: `monitor/sre-agent-event-lab/app/telemetry.py` -- Create: `monitor/sre-agent-event-lab/app/requirements.txt` -- Create: `monitor/sre-agent-event-lab/app/requirements-dev.txt` -- Create: `monitor/sre-agent-event-lab/app/tests/test_main.py` -- Create: `monitor/sre-agent-event-lab/app/Dockerfile` - -**Interfaces:** -- Consumes: `FAILURE_MODE`, `ORDER_DELAY_MS`, `AZURE_STORAGE_ACCOUNT_URL`, and `APPLICATIONINSIGHTS_CONNECTION_STRING` environment variables. -- Produces: `GET /healthz`, `GET /api/orders`, and `GET /api/documents`; structured JSON log fields `scenario`, `operation`, `status`, `elapsed_ms`, and `correlation_id`. - -- [ ] **Step 1: Write failing endpoint tests** - -Create tests using `pytest`, `fastapi.testclient.TestClient`, and `monkeypatch`. Define a `FakeBlobService` whose `get_container_client("documents").list_blobs()` returns one item, then assert: - -```python -def test_orders_normal(client, monkeypatch): - monkeypatch.setenv("FAILURE_MODE", "none") - monkeypatch.setenv("ORDER_DELAY_MS", "0") - response = client.get("/api/orders") - assert response.status_code == 200 - assert response.json()["status"] == "accepted" - -def test_orders_http500(client, monkeypatch): - monkeypatch.setenv("FAILURE_MODE", "http500") - response = client.get("/api/orders") - assert response.status_code == 500 - assert response.json()["detail"] == "Injected order processing failure" - -def test_orders_delay(client, monkeypatch): - monkeypatch.setenv("ORDER_DELAY_MS", "50") - started = time.perf_counter() - response = client.get("/api/orders") - assert response.status_code == 200 - assert time.perf_counter() - started >= 0.045 - -def test_documents_maps_authorization_failure_to_503(client, monkeypatch): - def denied_service(): - raise HttpResponseError(message="AuthorizationPermissionMismatch", response=None) - - monkeypatch.setattr(main, "list_documents", denied_service) - response = client.get("/api/documents") - assert response.status_code == 503 - assert response.json()["detail"] == "Blob dependency unavailable" -``` - -- [ ] **Step 2: Run tests and confirm the RED state** - -Run: - -```bash -cd monitor/sre-agent-event-lab/app -python3 -m venv .venv -.venv/bin/pip install -r requirements-dev.txt -.venv/bin/pytest -q -``` - -Expected: collection fails because `main.py` and its endpoints do not exist. - -- [ ] **Step 3: Implement telemetry initialization** - -In `telemetry.py`, export: - -```python -def configure_telemetry() -> None: - connection_string = os.getenv("APPLICATIONINSIGHTS_CONNECTION_STRING") - if connection_string: - configure_azure_monitor(connection_string=connection_string) -``` - -Do not catch initialization errors. A malformed connection string must fail startup rather than silently disabling telemetry. - -- [ ] **Step 4: Implement the FastAPI service** - -In `main.py`: - -- Call `configure_telemetry()` before constructing `FastAPI`. -- Read failure configuration per request so unit tests and new revisions are deterministic. -- Raise `HTTPException(500, "Injected order processing failure")` when `FAILURE_MODE=http500`. -- Sleep `ORDER_DELAY_MS / 1000` seconds when the value is a non-negative integer; raise a clear `ValueError` for invalid values instead of silently defaulting. -- Use `DefaultAzureCredential()` and `BlobServiceClient(account_url=..., credential=...)` for `/api/documents`. -- Convert only `azure.core.exceptions.HttpResponseError` from Blob access to HTTP 503; do not broadly catch unrelated exceptions. -- Emit one JSON log record per request outcome. - -- [ ] **Step 5: Pin dependencies and build the container** - -Use: - -```text -fastapi~=0.116 -uvicorn[standard]~=0.35 -azure-monitor-opentelemetry~=1.8 -azure-identity~=1.24 -azure-storage-blob~=12.26 -``` - -Development requirements add: - -```text --r requirements.txt -pytest~=8.4 -httpx~=0.28 -``` - -The Dockerfile must use `python:3.12-slim`, install `requirements.txt`, copy only application files, run as a non-root user, expose port 8000, and start `uvicorn main:app --host 0.0.0.0 --port 8000`. - -- [ ] **Step 6: Run tests and local process validation** - -Run: - -```bash -.venv/bin/pytest -q -FAILURE_MODE=none ORDER_DELAY_MS=0 \ - .venv/bin/uvicorn main:app --host 127.0.0.1 --port 18000 \ - >/tmp/sre-event-lab-uvicorn.log 2>&1 & -APP_PID=$! -trap 'kill "$APP_PID" 2>/dev/null || true' EXIT -for attempt in $(seq 1 30); do - curl --fail --silent http://127.0.0.1:18000/healthz && break - sleep 1 -done -curl --fail http://127.0.0.1:18000/healthz -curl --fail http://127.0.0.1:18000/api/orders -kill "$APP_PID" -wait "$APP_PID" || true -trap - EXIT -``` - -Expected: all tests pass; both requests return HTTP 200; uvicorn exits after the PID-specific `kill`. The Dockerfile is validated later by the remote `az acr build`, so local Docker is not required. - -- [ ] **Step 7: Commit** - -```bash -git add monitor/sre-agent-event-lab/app -git commit -m "feat(monitor): add SRE Agent failure lab app" \ - -m "Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>" -``` - ---- - -### Task 2: Define isolated Azure infrastructure - -**Files:** -- Create: `monitor/sre-agent-event-lab/infra/main.bicep` -- Create: `monitor/sre-agent-event-lab/infra/observability.bicep` -- Create: `monitor/sre-agent-event-lab/infra/workload.bicep` -- Create: `monitor/sre-agent-event-lab/infra/alerts.bicep` -- Create: `monitor/sre-agent-event-lab/infra/main.bicepparam` - -**Interfaces:** -- Consumes: `location`, `suffix`, `containerImage`, `deployContainerApp`, and `tags`. -- Produces: `acrName`, `acrLoginServer`, `containerAppName`, `containerAppFqdn`, `containerAppPrincipalId`, `storageContainerScope`, `blobRoleAssignmentName`, `workspaceId`, `appInsightsName`, and alert rule names. - -- [ ] **Step 1: Write the deployment entry point** - -`main.bicep` must call focused `observability`, `workload`, and `alerts` modules. Pass the Application Insights connection string from observability to workload. Deploy the `alerts` module only when `deployContainerApp=true`, after the workload module, so there is no circular dependency. - -- [ ] **Step 2: Define observability resources and exact alert queries** - -Create one workspace-based Application Insights component in `observability.bicep`. Create three `Microsoft.Insights/scheduledQueryRules@2023-12-01` resources in `alerts.bicep` with 5-minute windows and 1-minute evaluation: - -```kusto -AppRequests -| where TimeGenerated > ago(5m) -| where AppRoleName == "sre-event-lab" -| where ResultCode startswith "5" -| summarize Failures=count() -``` - -Fire S1 when `Failures > 10`. - -```kusto -AppRequests -| where TimeGenerated > ago(5m) -| where AppRoleName == "sre-event-lab" -| where Name has "/api/orders" -| summarize P95DurationMs=percentile(DurationMs, 95) -``` - -Fire S2 when `P95DurationMs > 2000`. - -```kusto -AppDependencies -| where TimeGenerated > ago(5m) -| where AppRoleName == "sre-event-lab" -| where Target has "blob.core.windows.net" -| where Success == false -| summarize DependencyFailures=count() -``` - -Fire S3 when `DependencyFailures > 5`. - -Use Sev2, auto-mitigation, enabled rules, and titles prefixed exactly with `[SRE-LAB-S1]`, `[SRE-LAB-S2]`, and `[SRE-LAB-S3]`. - -- [ ] **Step 3: Define workload resources** - -Create: - -- Basic ACR with admin disabled. -- Standard_LRS Storage account with public blob access disabled. -- Private `documents` blob container. -- Container Apps managed environment connected to the Log Analytics workspace. -- Consumption Container App with external ingress on port 8000, one active revision, min replicas 1, max replicas 2, 0.5 CPU, 1 GiB memory. -- System-assigned identity with `AcrPull` on ACR and `Storage Blob Data Reader` on the `documents` container. -- Environment variables: `FAILURE_MODE=none`, `ORDER_DELAY_MS=0`, `AZURE_STORAGE_ACCOUNT_URL`, `APPLICATIONINSIGHTS_CONNECTION_STRING`, `OTEL_SERVICE_NAME=sre-event-lab`. - -Use deterministic role assignment GUIDs based on scope, principal ID, and role definition ID. Export the role assignment name and container scope for safe S3 recovery. - -- [ ] **Step 4: Add stable parameters** - -Set `location = 'koreacentral'`, derive resource names from `suffix = '95933ae5'`, and define: - -```bicep -param tags = { - purpose: 'sre-agent-event-lab' - expiresOn: '2026-08-13' -} -``` - -The initial deployment uses `deployContainerApp = false` and `containerImage = 'mcr.microsoft.com/azuredocs/containerapps-helloworld:latest'`; the image is not referenced while the app condition is false. - -- [ ] **Step 5: Validate Bicep** - -Run: - -```bash -az bicep build --file monitor/sre-agent-event-lab/infra/main.bicep -az bicep build --file monitor/sre-agent-event-lab/infra/main.bicep --stdout >/dev/null -``` - -Expected: exit code 0 and no errors. Remove generated `main.json` from the first command after validation. - -- [ ] **Step 6: Commit** - -```bash -git add monitor/sre-agent-event-lab/infra -git commit -m "feat(monitor): define SRE Agent lab infrastructure" \ - -m "Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>" -``` - ---- - -### Task 3: Add bounded scenario and evidence tooling - -**Files:** -- Create: `monitor/sre-agent-event-lab/scripts/common.sh` -- Create: `monitor/sre-agent-event-lab/scripts/deploy.sh` -- Create: `monitor/sre-agent-event-lab/scripts/loadgen.py` -- Create: `monitor/sre-agent-event-lab/scripts/run-scenario.sh` -- Create: `monitor/sre-agent-event-lab/scripts/query-evidence.sh` -- Create: `monitor/sre-agent-event-lab/scripts/cleanup.sh` -- Create: `monitor/sre-agent-event-lab/scripts/tests/test_loadgen.py` - -**Interfaces:** -- `loadgen.py URL --requests N --concurrency N --expect-status CODE --output FILE` returns nonzero when observed status codes differ from the expectation and writes a JSON summary. -- `run-scenario.sh s1|s2|s3` creates `evidence/-/`. -- `query-evidence.sh SCENARIO EVIDENCE_DIR START_UTC END_UTC` writes JSON/TSV evidence without changing Azure resources. - -- [ ] **Step 1: Test the bounded load generator** - -Use a local `ThreadingHTTPServer` fixture and assert that 20 requests with concurrency 4 produce: - -```json -{ - "total": 20, - "status_counts": {"200": 20}, - "errors": 0 -} -``` - -Also assert that `--expect-status 500` returns exit code 2 when the server returns 200. - -- [ ] **Step 2: Implement `loadgen.py`** - -Use only the Python standard library. Bound `requests` to 1-10,000 and `concurrency` to 1-50. Record UTC start/end, request count, status counts, transport errors, average milliseconds, and p95 milliseconds. Write atomically by creating `.tmp` and replacing the output path. - -- [ ] **Step 3: Implement shared safety checks** - -`common.sh` must: - -- require `az`, `jq`, `curl`, and `python3`; -- verify the current subscription ID equals `95933ae5-0201-4a21-a1fc-8051a7437982`; -- set `RESOURCE_GROUP=rg-sre-agent-event-lab-krc`; -- refuse scenario or cleanup operations if the RG lacks tag `purpose=sre-agent-event-lab`; -- load deployment outputs with `az deployment group show`; -- create evidence directories under `monitor/sre-agent-event-lab/evidence/`, with that directory added to `.gitignore`. - -- [ ] **Step 4: Implement two-phase deployment** - -`deploy.sh` must: - -1. Create or validate the tagged RG. -2. Run subscription and group deployment validation. -3. Deploy `deployContainerApp=false`. -4. Read ACR name from outputs. -5. Build `sre-event-lab:20260812.1` with `az acr build`. -6. Deploy `deployContainerApp=true` with the resulting image. -7. Poll `/healthz` until HTTP 200 with a maximum 10-minute deadline. -8. Print all final outputs as JSON. - -- [ ] **Step 5: Implement scenario injection and unconditional recovery** - -`run-scenario.sh` must install a shell `trap` that runs the matching recovery action on `EXIT`, then: - -- S1: set `FAILURE_MODE=http500`, wait for the new revision to become ready, run 120 requests at concurrency 4 expecting 500, and recover to `FAILURE_MODE=none`. -- S2: set `ORDER_DELAY_MS=4000`, wait for readiness, run 90 requests at concurrency 8 expecting 200, and recover to `ORDER_DELAY_MS=0`. -- S3: delete only the output `blobRoleAssignmentName` at `storageContainerScope`, run 60 `/api/documents` requests at concurrency 4 expecting 503, and recreate `Storage Blob Data Reader` on exactly that scope in the trap. - -After traffic generation, keep the failure active for up to 12 minutes while polling Azure Monitor for the matching fired alert. Record the alert ID and firing time before recovery. Never use a fixed blind sleep when readiness or alert state can be polled. - -- [ ] **Step 6: Implement evidence export** - -Export: - -- Container App revisions and environment variable names, redacting secret values. -- AppRequests/AppDependencies/AppExceptions query results for the scenario interval. -- relevant Azure Activity Log entries. -- fired and resolved Azure Monitor alert instances. -- role assignments only for the test app principal and test container scope. - -Do not export access tokens, connection strings, or unrelated subscription resources. - -- [ ] **Step 7: Implement safe cleanup** - -`cleanup.sh` must require the exact RG name and tag, accept `--yes`, remove only the recorded Agent `Monitoring Contributor` assignment if its principal ID and assignment ID were saved by setup, then delete the test RG with `az group delete --no-wait`. Without `--yes`, print the planned actions and exit without changes. - -- [ ] **Step 8: Run tests and static checks** - -Run: - -```bash -python3 -m pytest monitor/sre-agent-event-lab/scripts/tests/test_loadgen.py -q -bash -n monitor/sre-agent-event-lab/scripts/*.sh -``` - -Expected: pytest passes and every shell script parses successfully. - -- [ ] **Step 9: Commit** - -```bash -git add .gitignore monitor/sre-agent-event-lab/scripts -git commit -m "feat(monitor): add safe SRE lab scenario tooling" \ - -m "Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>" -``` - ---- - -### Task 4: Add Agent runbook and operator documentation - -**Files:** -- Create: `monitor/sre-agent-event-lab/runbooks/incident-response.md` -- Create: `monitor/sre-agent-event-lab/README.md` -- Create: `docs/superpowers/reports/2026-08-12-azure-sre-agent-event-testing-results.md` - -**Interfaces:** -- The runbook gives investigation order and allowed mitigations but does not reveal scenario ground truth. -- The report uses one row per scenario with detection latency, pickup latency, completion latency, RCA score, and verdict. - -- [ ] **Step 1: Write the ground-truth-free runbook** - -The runbook must tell the Agent to: - -1. identify the affected resource and exact UTC onset; -2. separate availability, latency, and dependency symptoms; -3. inspect requests, exceptions, dependencies, revisions, configuration changes, Activity Log, and RBAC changes; -4. cite concrete query results before concluding; -5. propose the smallest reversible mitigation; -6. avoid changing anything outside `rg-sre-agent-event-lab-krc`; -7. wait for approval before remediation. - -Do not include strings such as `FAILURE_MODE=http500`, `ORDER_DELAY_MS=4000`, or “role assignment was removed,” because those are the answers being tested. - -- [ ] **Step 2: Write the operator guide** - -Document prerequisites, exact deploy/test/query/cleanup commands, SRE Agent portal checkpoints, expected maximum duration, estimated low-cost footprint, safety boundaries, and troubleshooting order. - -- [ ] **Step 3: Create the living report** - -Add: - -- execution metadata; -- “한눈에 보기” table for S1-S3; -- Agent and observability configuration; -- one section per scenario with ground truth, timeline, evidence, Agent findings, scoring rubric, recovery; -- cross-scenario conclusions; -- cost and cleanup status. - -Mark unexecuted measured fields as `⏳ 미실행` rather than inventing values. - -- [ ] **Step 4: Validate documentation** - -Run: - -```bash -rg -n 'PENDING_VALUE|FIXME|REPLACE_ME' \ - monitor/sre-agent-event-lab/README.md \ - monitor/sre-agent-event-lab/runbooks/incident-response.md \ - docs/superpowers/reports/2026-08-12-azure-sre-agent-event-testing-results.md -git diff --check -``` - -Expected: no placeholder matches and no whitespace errors. - -- [ ] **Step 5: Commit** - -```bash -git add monitor/sre-agent-event-lab/README.md \ - monitor/sre-agent-event-lab/runbooks/incident-response.md \ - docs/superpowers/reports/2026-08-12-azure-sre-agent-event-testing-results.md -git commit -m "docs(monitor): add SRE Agent lab runbook and report" \ - -m "Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>" -``` - ---- - -### Task 5: Deploy and validate the Azure workload - -**Files:** -- Modify: `docs/superpowers/reports/2026-08-12-azure-sre-agent-event-testing-results.md` - -**Interfaces:** -- Consumes: Tasks 1-4 commits. -- Produces: healthy public test endpoint, populated observability tables, enabled alert rules, deployment evidence. - -- [ ] **Step 1: Verify Azure context and providers** - -Run: - -```bash -az account set --subscription 95933ae5-0201-4a21-a1fc-8051a7437982 -az account show --query '{name:name,id:id,state:state}' -o table -for provider in Microsoft.App Microsoft.OperationalInsights Microsoft.Insights \ - Microsoft.Storage Microsoft.ContainerRegistry; do - az provider register --namespace "$provider" --wait -done -``` - -Expected: the named development subscription is enabled and every provider becomes `Registered`. - -- [ ] **Step 2: Validate and deploy** - -Run: - -```bash -bash monitor/sre-agent-event-lab/scripts/deploy.sh \ - 2>&1 | tee monitor/sre-agent-event-lab/evidence/deploy.log -``` - -Expected: deployment succeeds, ACR build succeeds, `/healthz` returns 200. - -- [ ] **Step 3: Verify baseline telemetry** - -Send 30 normal `/api/orders` requests and 10 successful `/api/documents` requests. Query `AppRequests` and `AppDependencies` until both contain current records. Confirm all three alert queries are below threshold. - -- [ ] **Step 4: Record deployment facts** - -Write resource names, deployment IDs, baseline query counts, exact UTC times, and observed cost meter start into the report. Do not store connection strings or tokens. - -- [ ] **Step 5: Commit measured deployment metadata** - -```bash -git add docs/superpowers/reports/2026-08-12-azure-sre-agent-event-testing-results.md -git commit -m "docs(monitor): record SRE lab deployment" \ - -m "Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>" -``` - ---- - -### Task 6: Create and connect Azure SRE Agent - -**Files:** -- Modify: `docs/superpowers/reports/2026-08-12-azure-sre-agent-event-testing-results.md` -- Create in evidence directory: `agent-setup.json` - -**Interfaces:** -- Produces: Agent in Korea Central, GitHub and observability context, Azure Monitor incident platform, three Review-mode response plans, recorded managed identity and role assignment IDs. - -- [ ] **Step 1: Create the Agent through `https://sre.azure.com`** - -Use: - -- subscription: `95933ae5-0201-4a21-a1fc-8051a7437982`; -- resource group: `rg-sre-agent-event-lab-krc`; -- agent name: `sre-devguidesample-95933ae5`; -- region: Korea Central; -- Application Insights: use the lab instance when selectable, otherwise allow the wizard-created instance and record it. - -Checkpoint: deployment status is `Succeeded`. - -- [ ] **Step 2: Connect context** - -Connect: - -- GitHub repository `hellices/devguidesample`; -- Azure resource group `rg-sre-agent-event-lab-krc` with Reader access; -- the lab Log Analytics/Application Insights connector; -- `monitor/sre-agent-event-lab/runbooks/incident-response.md` as knowledge. - -Checkpoint: each card shows connected/healthy. - -- [ ] **Step 3: Connect Azure Monitor incident platform** - -Open **Builder → Incident platform**, choose Azure Monitor, turn off Quickstart response plan, and save. If a `quickstart_handler` exists, delete it before continuing. - -- [ ] **Step 4: Create response plans** - -Create exactly: - -| Name | Severity | Title filter | Mode | -|---|---|---|---| -| `sre-lab-s1-http500` | Sev2 | `[SRE-LAB-S1]` | Review | -| `sre-lab-s2-latency` | Sev2 | `[SRE-LAB-S2]` | Review | -| `sre-lab-s3-storage-rbac` | Sev2 | `[SRE-LAB-S3]` | Review | - -Checkpoint: all plans are On and show Review. - -- [ ] **Step 5: Verify and record permissions** - -Confirm the Agent managed identity has: - -- Reader on the test RG; -- Monitoring Contributor on the test subscription as required by the Azure Monitor scanner; -- no Contributor or Owner role. - -Save only principal ID, role assignment IDs, scopes, and timestamps to `agent-setup.json`. Never save credentials. - -- [ ] **Step 6: Record setup in the report** - -Record Agent region, model provider, connectors, response plans, role scopes, and setup checkpoints. - ---- - -### Task 7: Execute S1 and score the HTTP 500 investigation - -**Files:** -- Modify: `docs/superpowers/reports/2026-08-12-azure-sre-agent-event-testing-results.md` - -- [ ] **Step 1: Establish a clean baseline** - -Verify `/healthz` and `/api/orders` return 200, S1 alert is resolved, and no prior active S1 thread exists. - -- [ ] **Step 2: Run S1** - -```bash -bash monitor/sre-agent-event-lab/scripts/run-scenario.sh s1 -``` - -Expected: HTTP 500 traffic, S1 alert fired, SRE Agent thread created, recovery trap restores HTTP 200. - -- [ ] **Step 3: Wait on observable conditions** - -Poll until the Agent thread has a structured conclusion or 15 minutes elapse. Do not prompt the Agent manually; the event-driven path is under test. - -- [ ] **Step 4: Export evidence and score** - -Run `query-evidence.sh`, compare Agent statements to the recorded configuration change, and score impact 0-2, cause 0-3, evidence 0-2, mitigation 0-2, uncertainty 0-1. - -- [ ] **Step 5: Update and commit the report** - -Record exact timeline, Agent output summary, cited evidence, unsupported claims, score, verdict, and recovery. - ---- - -### Task 8: Execute S2 and score the latency investigation - -**Files:** -- Modify: `docs/superpowers/reports/2026-08-12-azure-sre-agent-event-testing-results.md` - -- [ ] **Step 1: Establish a clean baseline** - -Verify `ORDER_DELAY_MS=0`, request p95 is below 2 seconds, S2 alert is resolved, and the app is healthy. - -- [ ] **Step 2: Run S2** - -```bash -bash monitor/sre-agent-event-lab/scripts/run-scenario.sh s2 -``` - -Expected: 2xx responses with approximately 4-second latency, S2 alert fired, event-driven Agent thread, recovery to baseline latency. - -- [ ] **Step 3: Export evidence and score** - -Confirm the Agent distinguishes latency from availability, identifies the affected revision/configuration timing, and does not claim a dependency outage without evidence. - -- [ ] **Step 4: Update the report** - -Use the same timeline and 10-point scoring format as S1. - ---- - -### Task 9: Execute S3 and score the Storage RBAC investigation - -**Files:** -- Modify: `docs/superpowers/reports/2026-08-12-azure-sre-agent-event-testing-results.md` - -- [ ] **Step 1: Establish a clean baseline** - -Verify `/api/documents` returns 200, the exact Blob Data Reader assignment exists on the test container, and S3 alert is resolved. - -- [ ] **Step 2: Run S3** - -```bash -bash monitor/sre-agent-event-lab/scripts/run-scenario.sh s3 -``` - -Expected: Blob authorization failures surface as HTTP 503, S3 alert fires, Agent thread starts, and the trap restores only the deleted role assignment. - -- [ ] **Step 3: Verify recovery before analysis** - -Poll until `/api/documents` returns 200 and the role assignment ID/scope match the intended test container. - -- [ ] **Step 4: Export evidence and score** - -Confirm the Agent connects 503 symptoms to Blob 403 dependency evidence and the recent role assignment deletion. Penalize generic “network issue” conclusions unsupported by evidence. - -- [ ] **Step 5: Update the report** - -Use the same timeline and 10-point scoring format as S1 and S2. - ---- - -### Task 10: Complete the report, verify the lab, and clean up - -**Files:** -- Modify: `docs/superpowers/reports/2026-08-12-azure-sre-agent-event-testing-results.md` -- Modify: `monitor/sre-agent-event-lab/README.md` only if measured behavior changes an operator instruction - -- [ ] **Step 1: Calculate cross-scenario results** - -Calculate detection, pickup, and completion latency from UTC timestamps. Apply: - -- Pass: score 8-10 -- Partial: score 5-7 -- Fail: score 0-4 - -Overall success requires every scenario Partial or better, at least two Pass results, and zero unauthorized autonomous actions. - -- [ ] **Step 2: Add operational conclusions** - -Document which evidence sources the Agent used well, missed correlations, false claims, response-plan tuning, RBAC implications, scanner behavior, and whether the Agent is suitable for this repository's future incident labs. - -- [ ] **Step 3: Capture cost** - -Query Cost Management for the tagged RG when data is available. If cost ingestion is delayed, record the Azure retail estimate separately from observed cost and label it clearly. - -- [ ] **Step 4: Run final code and IaC verification** - -```bash -monitor/sre-agent-event-lab/app/.venv/bin/pytest \ - monitor/sre-agent-event-lab/app/tests \ - monitor/sre-agent-event-lab/scripts/tests -q -bash -n monitor/sre-agent-event-lab/scripts/*.sh -az bicep build --file monitor/sre-agent-event-lab/infra/main.bicep --stdout >/dev/null -git diff --check -``` - -Expected: tests pass, scripts parse, Bicep compiles, and no whitespace errors remain. - -- [ ] **Step 5: Clean up safely** - -After preserving evidence and report facts: - -```bash -bash monitor/sre-agent-event-lab/scripts/cleanup.sh -bash monitor/sre-agent-event-lab/scripts/cleanup.sh --yes -``` - -Expected: first command is dry-run only; second removes the recorded subscription role assignment and starts deletion of only `rg-sre-agent-event-lab-krc`. - -- [ ] **Step 6: Verify cleanup** - -Poll until the test RG no longer exists. Query role assignments for the Agent principal and confirm the recorded subscription-scope Monitoring Contributor assignment is absent. Record whether the Agent resource was deleted with the RG. - -- [ ] **Step 7: Final commit** - -```bash -git add monitor/sre-agent-event-lab \ - docs/superpowers/reports/2026-08-12-azure-sre-agent-event-testing-results.md -git commit -m "docs(monitor): publish Azure SRE Agent event test results" \ - -m "Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>" -``` diff --git a/docs/superpowers/plans/2026-08-12-azure-sre-agent-evidence-capture-execution.md b/docs/superpowers/plans/2026-08-12-azure-sre-agent-evidence-capture-execution.md deleted file mode 100644 index b4318bcb..00000000 --- a/docs/superpowers/plans/2026-08-12-azure-sre-agent-evidence-capture-execution.md +++ /dev/null @@ -1,249 +0,0 @@ -# Azure SRE Agent Evidence Capture Implementation Plan - -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. - -**Goal:** Capture real Azure Monitor and Azure SRE Agent incident state transitions, preserve redacted evidence, and render reproducible PNG/GIF/Markdown investigation timelines. - -**Architecture:** A standard-library Python collector polls Azure Alerts Management and the SRE Agent data-plane APIs, writing immutable raw snapshots under the Git-ignored evidence directory. A normalizer converts snapshots to a typed, redacted event timeline, and a Pillow renderer creates deterministic 1280×720 frames and an animated GIF that the report embeds. - -**Tech Stack:** Python 3.12, Azure CLI, Azure SRE Agent REST API, Azure Alerts Management REST API, Pillow, pytest, Bash, Markdown, Mermaid. - -## Global Constraints - -- Raw API JSON stays under `monitor/sre-agent-event-lab/evidence/` and is never committed. -- Rendered assets go under scenario directories such as `monitor/sre-agent-event-lab/assets/captures/s1/`. -- Never write bearer tokens, connection strings, instrumentation keys, cookies, PATs, or credential payloads to disk. -- Keep full resource, alert, thread, and message IDs only in raw/normalized JSON; GIF footers show short hashes. -- Poll at a bounded interval and stop at a configurable deadline. -- Treat 401/403 as fatal RBAC errors, honor `Retry-After` for 429/5xx, and preserve the last successful snapshot. -- Never invent missing tool/action events; render an explicit unknown or timeout state. -- A capture is complete when it contains alert-fired, thread-created, investigating, and conclusion events, or explicitly records which state was missing. - ---- - -## File Map - -| File | Responsibility | -|---|---| -| `monitor/sre-agent-event-lab/scripts/capture_agent.py` | Authenticate through Azure CLI, poll alert/thread/message APIs, write raw snapshots | -| `monitor/sre-agent-event-lab/scripts/capture_model.py` | Typed event model, redaction, normalization, state classification | -| `monitor/sre-agent-event-lab/scripts/render_capture.py` | Render deterministic PNG frames, GIF, Mermaid, and Markdown timeline | -| `monitor/sre-agent-event-lab/scripts/capture-scenario.sh` | Safe operator wrapper that reads Agent setup and scenario timeline | -| `monitor/sre-agent-event-lab/scripts/tests/test_capture_model.py` | Normalization, redaction, state, and missing-event tests | -| `monitor/sre-agent-event-lab/scripts/tests/test_render_capture.py` | Frame count, dimensions, GIF, Mermaid, and secret scan tests | -| `monitor/sre-agent-event-lab/app/requirements-dev.txt` | Pillow dependency for tests and capture rendering | -| `monitor/sre-agent-event-lab/README.md` | Automated capture and optional Portal recording commands | -| `docs/superpowers/reports/2026-08-12-azure-sre-agent-event-testing-results.md` | Per-scenario GIF, conclusion frame, timeline, and evidence references | - ---- - -### Task 1: Collect and normalize actual incident evidence - -**Files:** -- Create: `monitor/sre-agent-event-lab/scripts/capture_agent.py` -- Create: `monitor/sre-agent-event-lab/scripts/capture_model.py` -- Create: `monitor/sre-agent-event-lab/scripts/tests/test_capture_model.py` - -**Interfaces:** -- `capture_agent.py --scenario s1 --alert-id ID --output-dir PATH --timeout 1200 --interval 15` -- `capture_model.normalize_capture(alert: dict, snapshots: list[dict]) -> list[dict]` -- Each normalized event has `event_id`, `timestamp`, `state`, `title`, `summary`, `source`, and `source_file`. - -- [ ] **Step 1: Write failing normalization and redaction tests** - -Test a fixture containing: - -```python -snapshots = [{ - "captured_at": "2026-08-12T05:10:00Z", - "threads": [{"id": "thread-1", "title": "[SRE-LAB-S1] HTTP 500", "status": "Running"}], - "messages": [{ - "id": "message-1", - "createdAt": "2026-08-12T05:10:01Z", - "role": "assistant", - "content": "Authorization: Bearer secret-token", - }], -}] -``` - -Assert the normalized timeline includes alert-fired and thread-created, removes `secret-token`, preserves the message ID, and reports a missing conclusion. - -- [ ] **Step 2: Run RED** - -```bash -monitor/sre-agent-event-lab/app/.venv/bin/python -m pytest \ - monitor/sre-agent-event-lab/scripts/tests/test_capture_model.py -q -``` - -Expected: import failure because `capture_model.py` does not exist. - -- [ ] **Step 3: Implement typed normalization and redaction** - -Use dataclasses and standard library only. Redact keys matching: - -```python -SENSITIVE_KEYS = { - "authorization", "cookie", "token", "access_token", - "connectionstring", "connection_string", "instrumentationkey", - "pat", "password", "secret", -} -``` - -Also replace bearer-token and connection-string patterns inside strings with `[REDACTED]`. Sort by parsed UTC timestamp and deduplicate with `(source, event_id, state)`. - -- [ ] **Step 4: Implement bounded API collection** - -Use `subprocess.run` to call: - -```bash -az account get-access-token --resource https://azuresre.dev --query accessToken -o tsv -az rest --method get --url \ - "https://management.azure.com/subscriptions/95933ae5-0201-4a21-a1fc-8051a7437982/providers/Microsoft.AlertsManagement/alerts?api-version=2019-03-01" -``` - -Keep access tokens only in memory. Call: - -- `GET /api/v1/threads` -- `GET /api/v1/threads/{threadId}` -- `GET /api/v1/threads/{threadId}/messages` - -Write each successful response atomically to `thread-snapshots/0001.json`. Match a thread by alert title and creation time after the alert fired time. - -- [ ] **Step 5: Run GREEN and commit** - -```bash -monitor/sre-agent-event-lab/app/.venv/bin/python -m pytest \ - monitor/sre-agent-event-lab/scripts/tests/test_capture_model.py -q -git add monitor/sre-agent-event-lab/scripts/capture_agent.py \ - monitor/sre-agent-event-lab/scripts/capture_model.py \ - monitor/sre-agent-event-lab/scripts/tests/test_capture_model.py -git commit -m "feat(monitor): capture SRE Agent incident evidence" \ - -m "Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>" -``` - ---- - -### Task 2: Render actual evidence as PNG, GIF, Mermaid, and Markdown - -**Files:** -- Create: `monitor/sre-agent-event-lab/scripts/render_capture.py` -- Create: `monitor/sre-agent-event-lab/scripts/tests/test_render_capture.py` -- Modify: `monitor/sre-agent-event-lab/app/requirements-dev.txt` - -**Interfaces:** -- `render_capture.py TIMELINE_JSON OUTPUT_DIR` -- Produces numbered PNGs, `investigation.gif`, `timeline.mmd`, and `timeline.md`. - -- [ ] **Step 1: Add Pillow and write failing renderer tests** - -Add: - -```text -Pillow~=11.3.0 -``` - -Test a four-event fixture and assert: - -- four 1280×720 PNG files; -- animated GIF with four frames; -- final frame duration is 3000 ms; -- Mermaid contains the alert and Agent participants; -- rendered files do not contain any forbidden secret pattern. - -- [ ] **Step 2: Run RED** - -```bash -monitor/sre-agent-event-lab/app/.venv/bin/pip install -r \ - monitor/sre-agent-event-lab/app/requirements-dev.txt -monitor/sre-agent-event-lab/app/.venv/bin/python -m pytest \ - monitor/sre-agent-event-lab/scripts/tests/test_render_capture.py -q -``` - -Expected: import failure because `render_capture.py` does not exist. - -- [ ] **Step 3: Implement deterministic rendering** - -Use a 1280×720 RGB canvas and DejaVu Sans when available, otherwise Pillow's default font. Render: - -- scenario/state header; -- alert card; -- elapsed timeline; -- latest Agent event; -- short SHA-256 hashes for alert/thread IDs. - -Save frames with stable filenames based on state order, then create a looping GIF with 1500 ms regular frames and 3000 ms conclusion/timeout frame. - -- [ ] **Step 4: Generate Mermaid and Markdown** - -`timeline.mmd` must use `sequenceDiagram` with participants `AzureMonitor`, `SREAgent`, and `Evidence`. `timeline.md` must list UTC, elapsed seconds, state, source, and summary. - -- [ ] **Step 5: Run GREEN and commit** - -```bash -monitor/sre-agent-event-lab/app/.venv/bin/python -m pytest \ - monitor/sre-agent-event-lab/scripts/tests/test_render_capture.py -q -git add monitor/sre-agent-event-lab/app/requirements-dev.txt \ - monitor/sre-agent-event-lab/scripts/render_capture.py \ - monitor/sre-agent-event-lab/scripts/tests/test_render_capture.py -git commit -m "feat(monitor): render SRE investigation captures" \ - -m "Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>" -``` - ---- - -### Task 3: Integrate scenario capture and report documentation - -**Files:** -- Create: `monitor/sre-agent-event-lab/scripts/capture-scenario.sh` -- Modify: `monitor/sre-agent-event-lab/README.md` -- Modify: `docs/superpowers/reports/2026-08-12-azure-sre-agent-event-testing-results.md` - -**Interfaces:** -- `capture-scenario.sh s1 EVIDENCE_DIR` reads `agent-setup.json` and `timeline.json`. -- Produces Git-ignored raw evidence and commit-safe assets under `assets/captures/s1/`. - -- [ ] **Step 1: Implement the safe wrapper** - -Validate the subscription, resource group tag, Agent setup file, alert ID, and timeline timestamps. Invoke collector, normalizer, and renderer. Fail if the normalized timeline contains a forbidden secret or fewer than four explicit states. - -- [ ] **Step 2: Document automated capture** - -Add exact commands: - -```bash -monitor/sre-agent-event-lab/scripts/capture-scenario.sh \ - s1 monitor/sre-agent-event-lab/evidence/s1-20260812T051000Z -``` - -Document the generated files and how to validate frame count with Pillow. - -- [ ] **Step 3: Document optional Portal recording** - -Document a 30–60 second macOS window-only recording procedure and an `ffmpeg` conversion command, while stating that Portal video never replaces API evidence. - -- [ ] **Step 4: Integrate captures into the report** - -Each scenario section must embed: - -```markdown -![S1 SRE Agent investigation](../../../monitor/sre-agent-event-lab/assets/captures/s1/investigation.gif) -``` - -Also link the conclusion PNG, Mermaid source, normalized evidence location, and regeneration command. - -- [ ] **Step 5: Verify and commit** - -```bash -monitor/sre-agent-event-lab/app/.venv/bin/python -m pytest \ - monitor/sre-agent-event-lab/scripts/tests -q -bash -n monitor/sre-agent-event-lab/scripts/*.sh -rg -n 'Bearer |InstrumentationKey=|connectionString|access_token' \ - monitor/sre-agent-event-lab/assets/captures && exit 1 || true -git diff --check -git add monitor/sre-agent-event-lab/scripts/capture-scenario.sh \ - monitor/sre-agent-event-lab/README.md \ - docs/superpowers/reports/2026-08-12-azure-sre-agent-event-testing-results.md \ - monitor/sre-agent-event-lab/assets/captures -git commit -m "docs(monitor): add SRE Agent investigation captures" \ - -m "Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>" -``` diff --git a/docs/superpowers/plans/2026-08-12-azure-sre-agent-introduction-execution.md b/docs/superpowers/plans/2026-08-12-azure-sre-agent-introduction-execution.md deleted file mode 100644 index 3d7304e3..00000000 --- a/docs/superpowers/plans/2026-08-12-azure-sre-agent-introduction-execution.md +++ /dev/null @@ -1,311 +0,0 @@ -# Azure SRE Agent Hybrid Introduction Implementation Plan - -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. - -**Goal:** Replace the report-first experience with a practical Azure SRE Agent introduction that explains the product, walks through an understandable incident story, and demonstrates ticket/email operational outputs. - -**Architecture:** A new `monitor/azure-sre-agent.md` is the entry point and uses Microsoft Learn-hosted official images for product concepts. Existing raw event timelines feed a storyboard renderer that adds scenario, expectation, actual evidence, and outcome frames; a notification generator converts the validated S1 conclusion into a GitHub issue body and Outlook-compatible email draft. - -**Tech Stack:** Markdown, Microsoft Learn images, Python 3.12, Pillow, HTML, RFC 5322 email, GitHub CLI, pytest. - -## Global Constraints - -- The new introduction is the primary document; the existing results document becomes a validation appendix. -- Use Microsoft Learn images by direct HTTPS URL with source attribution; do not copy or alter Microsoft screenshots. -- Distinguish `SCENARIO` explanatory frames from `ACTUAL` API-evidence frames. -- Never claim ServiceNow, PagerDuty, Outlook, or Teams were connected in this lab. -- Create one real GitHub issue in `hellices/devguidesample` with `[SRE-LAB]` prefix. -- Do not send a real email; create `.eml`, HTML, and PNG preview artifacts labeled Draft. -- Exclude tokens, callback URLs, connection strings, identity claims, and private evidence from ticket/email assets. -- Preserve the existing measured S1/S2/S3 results and known S3 limitation. - ---- - -## File Map - -| File | Responsibility | -|---|---| -| `monitor/azure-sre-agent.md` | Product introduction and primary navigation | -| `monitor/sre-agent-event-lab/scripts/render_storyboard.py` | Merge explanatory frames with selected actual evidence | -| `monitor/sre-agent-event-lab/scripts/generate_notifications.py` | Build sanitized GitHub issue body, HTML email, and `.eml` | -| `monitor/sre-agent-event-lab/scripts/tests/test_storyboard.py` | Story order, badges, dimensions, GIF tests | -| `monitor/sre-agent-event-lab/scripts/tests/test_notifications.py` | Ticket/email content, RFC headers, secret redaction tests | -| `monitor/sre-agent-event-lab/assets/storyboards/` | Commit-safe scenario storyboard frames and GIFs | -| `monitor/sre-agent-event-lab/assets/notifications/` | Commit-safe issue/email artifacts and screenshots | -| `docs/superpowers/reports/2026-08-12-azure-sre-agent-event-testing-results.md` | Validation appendix with introduction backlink | - ---- - -### Task 1: Build the product introduction - -**Files:** -- Create: `monitor/azure-sre-agent.md` -- Modify: `monitor/sre-agent-event-lab/README.md` -- Modify: `docs/superpowers/reports/2026-08-12-azure-sre-agent-event-testing-results.md` - -**Interfaces:** -- Introduction links to the lab README, actual storyboard assets, GitHub issue, email preview, and validation appendix. - -- [ ] **Step 1: Create a failing document contract** - -Verify the new document is absent: - -```bash -test ! -f monitor/azure-sre-agent.md -``` - -- [ ] **Step 2: Write the introduction** - -Include: - -- one-sentence definition; -- manual-before/agent-after comparison; -- `Detect → Investigate → Recommend/Act → Communicate → Learn`; -- hypothesis-driven RCA; -- incident platforms, built-in Azure tools, source/knowledge, connectors; -- ReadOnly/Review/Autonomous safety; -- representative HTTP 500 scenario; -- ticket/email operational output; -- S2/S3 pattern cards; -- Dynamic Threshold operating extension; -- adoption checklist and limitations. - -- [ ] **Step 3: Add official images** - -Embed and attribute at least: - -```text -https://learn.microsoft.com/en-us/azure/sre-agent/media/root-cause-analysis/root-cause-analysis.svg -https://learn.microsoft.com/en-us/azure/sre-agent/media/tutorial-incident-response/incident-response-plans.png -https://learn.microsoft.com/en-us/azure/sre-agent/media/tutorial-incident-response/sample-app-memory-search-results.png -https://learn.microsoft.com/en-us/azure/sre-agent/media/managed-connectors/managed-connectors-icon-grid.png -https://learn.microsoft.com/en-us/azure/sre-agent/media/managed-connectors/office365-operations.png -https://learn.microsoft.com/en-us/azure/sre-agent/media/managed-connectors/office365-parameter-policy.png -``` - -- [ ] **Step 4: Reframe the report** - -Change the report title/intro to “actual behavior validation appendix,” link to `monitor/azure-sre-agent.md`, and preserve all measured tables. - -- [ ] **Step 5: Verify and commit** - -```bash -for phrase in \ - "Detect" "Investigate" "Communicate" "Review" \ - "GitHub Issue" "Outlook" "ServiceNow" "PagerDuty"; do - rg -q "$phrase" monitor/azure-sre-agent.md -done -test "$(rg -c 'learn.microsoft.com/en-us/azure/sre-agent/media/' \ - monitor/azure-sre-agent.md)" -ge 5 -git diff --check -git add monitor/azure-sre-agent.md \ - monitor/sre-agent-event-lab/README.md \ - docs/superpowers/reports/2026-08-12-azure-sre-agent-event-testing-results.md -git commit -m "docs(monitor): introduce Azure SRE Agent workflows" \ - -m "Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>" -``` - ---- - -### Task 2: Render scenario-aware storyboard GIFs - -**Files:** -- Create: `monitor/sre-agent-event-lab/scripts/render_storyboard.py` -- Create: `monitor/sre-agent-event-lab/scripts/tests/test_storyboard.py` -- Create: `monitor/sre-agent-event-lab/assets/storyboards/s1/` -- Create: `monitor/sre-agent-event-lab/assets/storyboards/s2/` -- Create: `monitor/sre-agent-event-lab/assets/storyboards/s3/` - -**Interfaces:** -- `render_storyboard.py --scenario s1 --timeline PATH --output-dir PATH --ticket-url URL --email-preview PATH` -- Produces a seven-frame 1280×720 GIF with explanatory and actual badges. - -- [ ] **Step 1: Write failing storyboard tests** - -Assert: - -- frame 1 badge is `SCENARIO`; -- frame 2 badge is `EXPECTATION`; -- actual frames use `ACTUAL`; -- final frame uses `OPERATIONAL OUTPUT`; -- all frames are 1280×720; -- GIF has 7 frames; -- S1 final frame contains ticket and email labels. - -- [ ] **Step 2: Run RED** - -```bash -monitor/sre-agent-event-lab/app/.venv/bin/python -m pytest \ - monitor/sre-agent-event-lab/scripts/tests/test_storyboard.py -q -``` - -- [ ] **Step 3: Implement storyboard rendering** - -Reuse fonts/colors from `render_capture.py`. Each scenario supplies: - -```python -{ - "situation": "...", - "impact": "...", - "expectations": ["...", "..."], - "actual_event_states": ["alert-fired", "thread-created", "investigating", "conclusion"], - "result": "...", -} -``` - -Select representative actual events instead of every message. - -- [ ] **Step 4: Generate S1/S2/S3 storyboards** - -Use normalized timelines: - -```text -evidence/s1-20260812T080606Z/normalized-timeline.json -evidence/s2-20260812T081539Z/normalized-timeline.json -evidence/s3-20260812T084004Z/normalized-timeline.json -``` - -- [ ] **Step 5: Browser-validate the final frame and commit** - -Open S1 GIF and conclusion/output PNG in the browser, verify text hierarchy and clipping, then: - -```bash -git add monitor/sre-agent-event-lab/scripts/render_storyboard.py \ - monitor/sre-agent-event-lab/scripts/tests/test_storyboard.py \ - monitor/sre-agent-event-lab/assets/storyboards -git commit -m "feat(monitor): add SRE incident storyboards" \ - -m "Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>" -``` - ---- - -### Task 3: Generate and publish the ticket artifact - -**Files:** -- Create: `monitor/sre-agent-event-lab/scripts/generate_notifications.py` -- Create: `monitor/sre-agent-event-lab/scripts/tests/test_notifications.py` -- Create: `monitor/sre-agent-event-lab/assets/notifications/s1-github-issue.md` -- Create after issue creation: `monitor/sre-agent-event-lab/assets/notifications/github-issue.json` -- Create after browser capture: `monitor/sre-agent-event-lab/assets/notifications/github-issue.png` - -**Interfaces:** -- `generate_notifications.py --timeline PATH --report-url URL --output-dir PATH` -- Produces sanitized issue body and email artifacts. - -- [ ] **Step 1: Write failing notification tests** - -Assert issue body contains: - -- Impact -- Detection -- Root cause -- Evidence -- Current status -- Recommended follow-up - -Assert no bearer token, instrumentation key, callback signature, or connection string. - -- [ ] **Step 2: Implement issue generation** - -Use the final S1 conclusion and measured timestamps. Do not read unredacted callback URLs or Agent setup secrets. - -- [ ] **Step 3: Create the real GitHub issue** - -```bash -ISSUE_URL=$(gh issue create \ - --repo hellices/devguidesample \ - --title "[SRE-LAB] ca-sre-event-lab-vnet HTTP 500 incident" \ - --body-file monitor/sre-agent-event-lab/assets/notifications/s1-github-issue.md) -gh issue view "$ISSUE_URL" --repo hellices/devguidesample --json number,url,title,state \ - > monitor/sre-agent-event-lab/assets/notifications/github-issue.json -``` - -- [ ] **Step 4: Capture the issue page** - -Open the public issue URL in the integrated browser and save a screenshot. - -- [ ] **Step 5: Verify and commit** - -```bash -jq -e '.url and .number and .state' \ - monitor/sre-agent-event-lab/assets/notifications/github-issue.json -git add monitor/sre-agent-event-lab/scripts/generate_notifications.py \ - monitor/sre-agent-event-lab/scripts/tests/test_notifications.py \ - monitor/sre-agent-event-lab/assets/notifications/s1-github-issue.md \ - monitor/sre-agent-event-lab/assets/notifications/github-issue.json \ - monitor/sre-agent-event-lab/assets/notifications/github-issue.png -git commit -m "docs(monitor): publish SRE incident ticket example" \ - -m "Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>" -``` - ---- - -### Task 4: Create the Outlook email draft and integrate outputs - -**Files:** -- Create: `monitor/sre-agent-event-lab/assets/notifications/s1-incident-summary.html` -- Create: `monitor/sre-agent-event-lab/assets/notifications/s1-incident-summary.eml` -- Create: `monitor/sre-agent-event-lab/assets/notifications/s1-email-preview.png` -- Modify: `monitor/azure-sre-agent.md` -- Modify: `monitor/sre-agent-event-lab/README.md` - -- [ ] **Step 1: Generate HTML and `.eml`** - -Use: - -```text -From: azure-sre-agent-demo@example.invalid -To: oncall@example.invalid -Subject: [Resolved][SRE-LAB] Order API HTTP 500 incident -``` - -Include issue URL, timeline, root cause, evidence, mitigation, status, and follow-up. - -- [ ] **Step 2: Render the email preview** - -Open the HTML in the integrated browser at 1280×900 and save a screenshot. - -- [ ] **Step 3: Document Outlook production setup** - -Explain: - -- Send email (Outlook) connector; -- locked `To` parameter; -- Agent-defined subject/body; -- `Ask` permission in Review workflows; -- Autonomous mode bypass warning from Microsoft Learn. - -- [ ] **Step 4: Integrate ticket/email into storyboard and introduction** - -Regenerate S1 final storyboard frame with real issue URL and email preview link. Add both artifacts to the introduction. - -- [ ] **Step 5: Final verification** - -```bash -monitor/sre-agent-event-lab/app/.venv/bin/python -m pytest \ - monitor/sre-agent-event-lab/scripts/tests -q -for path in \ - monitor/sre-agent-event-lab/assets/storyboards/s1/investigation-guide.gif \ - monitor/sre-agent-event-lab/assets/notifications/github-issue.png \ - monitor/sre-agent-event-lab/assets/notifications/s1-email-preview.png; do - test -s "$path" -done -if rg -n -i \ - 'Bearer eyJ|InstrumentationKey=[0-9a-fA-F-]{36}|sig=[A-Za-z0-9_-]{20,}' \ - monitor/sre-agent-event-lab/assets/notifications \ - monitor/sre-agent-event-lab/assets/storyboards; then - exit 1 -fi -git diff --check -``` - -- [ ] **Step 6: Commit** - -```bash -git add monitor/azure-sre-agent.md \ - monitor/sre-agent-event-lab/README.md \ - monitor/sre-agent-event-lab/assets/storyboards/s1 \ - monitor/sre-agent-event-lab/assets/notifications -git commit -m "docs(monitor): integrate SRE ticket and email workflow" \ - -m "Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>" -``` diff --git a/docs/superpowers/plans/2026-08-13-azure-sre-agent-korean-briefing-redesign.md b/docs/superpowers/plans/2026-08-13-azure-sre-agent-korean-briefing-redesign.md deleted file mode 100644 index 7a79368c..00000000 --- a/docs/superpowers/plans/2026-08-13-azure-sre-agent-korean-briefing-redesign.md +++ /dev/null @@ -1,279 +0,0 @@ -# Azure SRE Agent Korean Customer Briefing Redesign Implementation Plan - -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. - -**Goal:** Rewrite the Azure SRE Agent introduction as a natural Korean customer/partner briefing and replace fragile external images and unhelpful storyboards with local process diagrams and actual result screens. - -**Architecture:** A briefing-specific test suite enforces the Microsoft Korean Localization Style Guide rules and local-image integrity. A focused renderer creates two original local diagrams plus a public-safe Agent conclusion card; the primary Markdown document is rewritten around those static visuals and actual GitHub/email screenshots, while detailed measurements remain in the validation appendix. - -**Tech Stack:** Korean Markdown, Microsoft Korean Localization Style Guide, Python 3.12, Pillow, SVG, pytest, integrated browser. - -## Global Constraints - -- Use Microsoft Korean Localization Style Guide as the normative Korean source. -- Use `-합니다/-할 수 있습니다` for explanations and `-하세요` for direct instructions. -- Keep official Microsoft/Azure product names in English. -- Prefer Korean for general concepts: 경고, 인시던트, 근본 원인, 근거, 대응 계획, 검토 모드, 커넥터, 운영 절차서, 원격 분석 데이터, 완화 조치. -- Avoid mixed Korean-English translationese and noun-heavy phrasing. -- Remove every externally embedded Microsoft Learn image from the primary document; retain source links only. -- Remove storyboard GIFs from the primary document and remove storyboard generation artifacts from the repository. -- Use local relative PNG paths in the primary document. -- Keep actual GitHub Issue #43 and email draft screenshots. -- Distinguish native Azure Monitor integration from the lab-specific bridge. -- Preserve the measured validation appendix and live lab behavior. - ---- - -## File Map - -| File | Responsibility | -|---|---| -| `monitor/azure-sre-agent.md` | Natural Korean customer briefing | -| `monitor/sre-agent-event-lab/scripts/render_briefing_assets.py` | Create local process, scenario, and conclusion visuals | -| `monitor/sre-agent-event-lab/scripts/tests/test_briefing_docs.py` | Korean tone, terminology, local image, and product/lab distinction checks | -| `monitor/sre-agent-event-lab/scripts/tests/test_briefing_assets.py` | SVG/PNG dimensions, privacy, and required panel checks | -| `monitor/sre-agent-event-lab/assets/briefing/sre-agent-process.svg` | Editable process diagram | -| `monitor/sre-agent-event-lab/assets/briefing/sre-agent-process.png` | Markdown-safe process diagram | -| `monitor/sre-agent-event-lab/assets/briefing/s1-three-panel.svg` | Editable representative scenario | -| `monitor/sre-agent-event-lab/assets/briefing/s1-three-panel.png` | Markdown-safe representative scenario | -| `monitor/sre-agent-event-lab/assets/briefing/s1-agent-conclusion.png` | Public-safe actual conclusion card | -| `monitor/sre-agent-event-lab/assets/storyboards/` | Delete | -| `monitor/sre-agent-event-lab/scripts/render_storyboard.py` | Delete | -| `monitor/sre-agent-event-lab/scripts/tests/test_storyboard.py` | Delete | - ---- - -### Task 1: Add Korean briefing quality gates - -**Files:** -- Create: `monitor/sre-agent-event-lab/scripts/tests/test_briefing_docs.py` - -**Interfaces:** -- Reads `monitor/azure-sre-agent.md`. -- Fails on translationese, external embedded images, storyboard references, missing product/lab distinction, or broken local image paths. - -- [ ] **Step 1: Write the failing style tests** - -The test must: - -1. remove fenced code, inline code, links, and URLs before prose checks; -2. reject these general English terms in prose: - -```python -FORBIDDEN_PROSE = ( - " alert", " incident", " evidence", " root cause", " hypothesis", - " response plan", " connector", " runbook", " telemetry", - " mitigation", " workflow", " ticket", " email", -) -``` - -3. reject `-다.` explanatory endings; -4. require `-합니다` or `-할 수 있습니다` across the introduction; -5. require `Microsoft Korean Localization Style Guide`; -6. reject remote Markdown image targets; -7. reject `storyboard` and `.gif` in the primary document; -8. resolve every local Markdown image path. - -- [ ] **Step 2: Run RED** - -```bash -monitor/sre-agent-event-lab/app/.venv/bin/python -m pytest \ - monitor/sre-agent-event-lab/scripts/tests/test_briefing_docs.py -q -``` - -Expected: failures on current mixed terminology, `-다` tone, remote images, storyboard GIF, and missing local diagrams. - -- [ ] **Step 3: Add product/lab distinction assertions** - -Require the prose to include: - -```text -제품에서 기본으로 지원하는 방식 -이번 실증에서 사용한 방식 -검토 모드 -실제 연결하지 않았습니다 -``` - -- [ ] **Step 4: Keep tests RED until the rewrite** - -Do not weaken the checks to pass the old copy. Task 3 makes these tests green. - ---- - -### Task 2: Create stable local briefing visuals - -**Files:** -- Create: `monitor/sre-agent-event-lab/scripts/render_briefing_assets.py` -- Create: `monitor/sre-agent-event-lab/scripts/tests/test_briefing_assets.py` -- Create: `monitor/sre-agent-event-lab/assets/briefing/sre-agent-process.svg` -- Create: `monitor/sre-agent-event-lab/assets/briefing/sre-agent-process.png` -- Create: `monitor/sre-agent-event-lab/assets/briefing/s1-three-panel.svg` -- Create: `monitor/sre-agent-event-lab/assets/briefing/s1-three-panel.png` -- Create: `monitor/sre-agent-event-lab/assets/briefing/s1-agent-conclusion.png` - -**Interfaces:** -- `render_briefing_assets.py --timeline PATH --output-dir PATH` -- Produces three 1600×900 PNGs and two equivalent SVG diagrams. - -- [ ] **Step 1: Write failing asset tests** - -Assert: - -- all required files exist; -- PNG size is 1600×900; -- process SVG contains the stages `경고 수신`, `근거 수집`, `가설 검증`, `검토 및 승인`, `티켓과 알림`; -- scenario SVG contains `상황`, `Agent 조사`, `운영 결과`; -- conclusion PNG uses normalized fields and contains no subscription ID; -- image text contains no raw callback signature, token, or thread status JSON. - -- [ ] **Step 2: Run RED** - -```bash -monitor/sre-agent-event-lab/app/.venv/bin/python -m pytest \ - monitor/sre-agent-event-lab/scripts/tests/test_briefing_assets.py -q -``` - -- [ ] **Step 3: Implement the process diagram** - -Create an original seven-stage horizontal diagram: - -```text -경고 수신 → 조사 범위 확인 → 근거 수집 → 가설 검증 -→ 근본 원인과 조치 제안 → 검토 및 승인 → 티켓·알림·지식 축적 -``` - -Use a restrained Microsoft/Azure-inspired blue palette without copying Microsoft Learn artwork. - -- [ ] **Step 4: Implement the representative three-panel visual** - -Use: - -```text -상황: 주문 API 500 / 고객 주문 120건 실패 -Agent 조사: Application Insights / 배포 설정 / 코드 -운영 결과: 원인 확인 / Issue #43 / 이메일 초안 -``` - -- [ ] **Step 5: Implement the actual conclusion card** - -Use verified metadata: - -```text -영향을 받은 서비스: ca-sre-event-lab-vnet -원격 분석 원본: appi-sre-event-lab-95933ae5 -근본 원인: revision 0000010, FAILURE_MODE=http500 -영향: GET /api/orders 120건 실패 -완화 조치: 정상 revision으로 복귀 -검토 모드: Agent가 Azure 리소스를 변경하지 않음 -``` - -- [ ] **Step 6: Run GREEN and browser-review** - -```bash -monitor/sre-agent-event-lab/app/.venv/bin/python -m pytest \ - monitor/sre-agent-event-lab/scripts/tests/test_briefing_assets.py -q -``` - -Open all three PNGs in the browser and confirm no clipping and readable Korean. - -- [ ] **Step 7: Commit** - -```bash -git add monitor/sre-agent-event-lab/scripts/render_briefing_assets.py \ - monitor/sre-agent-event-lab/scripts/tests/test_briefing_assets.py \ - monitor/sre-agent-event-lab/assets/briefing -git commit -m "feat(monitor): add Korean SRE briefing visuals" \ - -m "Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>" -``` - ---- - -### Task 3: Rewrite the customer briefing and remove storyboards - -**Files:** -- Rewrite: `monitor/azure-sre-agent.md` -- Modify: `monitor/sre-agent-event-lab/README.md` -- Delete: `monitor/sre-agent-event-lab/assets/storyboards/` -- Delete: `monitor/sre-agent-event-lab/scripts/render_storyboard.py` -- Delete: `monitor/sre-agent-event-lab/scripts/tests/test_storyboard.py` - -**Interfaces:** -- The primary document embeds only local PNGs and actual Issue/Email screenshots. -- Detailed measurements link to the existing validation appendix. - -- [ ] **Step 1: Rewrite the opening** - -Use: - -```markdown -# Azure SRE Agent 소개 - -Azure SRE Agent는 Azure 운영 환경에서 발생한 인시던트를 자동으로 조사하고, -관련 근거를 바탕으로 근본 원인과 조치 방안을 제안하는 AI 기반 운영 도우미입니다. -``` - -- [ ] **Step 2: Rewrite the full structure** - -Use the approved 11-section structure from the design. Prefer questions in headings: - -```text -Azure SRE Agent란 무엇인가요? -기존 장애 대응과 무엇이 달라지나요? -인시던트가 발생하면 어떻게 조사하나요? -어떤 시스템과 연결할 수 있나요? -권한과 승인 절차는 어떻게 제어하나요? -``` - -- [ ] **Step 3: Replace visuals** - -Embed: - -```text -sre-agent-event-lab/assets/briefing/sre-agent-process.png -sre-agent-event-lab/assets/briefing/s1-three-panel.png -sre-agent-event-lab/assets/briefing/s1-agent-conclusion.png -sre-agent-event-lab/assets/notifications/github-issue.png -sre-agent-event-lab/assets/notifications/s1-email-preview.png -``` - -Link to Microsoft Learn sources as references, not images. - -- [ ] **Step 4: Remove storyboards** - -Delete the storyboard generator, tests, manifests, PNGs, and GIFs. Keep raw evidence captures and the validation appendix. - -- [ ] **Step 5: Rewrite the lab README introduction** - -Change only the introduction/navigation copy to natural Korean and link to the new briefing. Keep operational commands unchanged. - -- [ ] **Step 6: Run all quality gates** - -```bash -monitor/sre-agent-event-lab/app/.venv/bin/python -m pytest \ - monitor/sre-agent-event-lab/app/tests \ - monitor/sre-agent-event-lab/scripts/tests \ - monitor/sre-agent-event-lab/infra/tests -q -git diff --check -``` - -- [ ] **Step 7: Render the Markdown for visual review** - -Use a local Markdown renderer, open the generated HTML in the integrated browser, and verify: - -- all local images render; -- headings and tables fit; -- no storyboard/GIF appears; -- actual Issue/Email screenshots are legible; -- no broken image icon appears. - -- [ ] **Step 8: Commit** - -```bash -git add monitor/azure-sre-agent.md \ - monitor/sre-agent-event-lab/README.md \ - monitor/sre-agent-event-lab/assets/storyboards \ - monitor/sre-agent-event-lab/scripts/render_storyboard.py \ - monitor/sre-agent-event-lab/scripts/tests/test_storyboard.py -git commit -m "docs(monitor): rewrite Azure SRE Agent briefing in Korean" \ - -m "Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>" -``` diff --git a/docs/superpowers/plans/2026-08-13-azure-sre-agent-official-images.md b/docs/superpowers/plans/2026-08-13-azure-sre-agent-official-images.md deleted file mode 100644 index 6e1e9507..00000000 --- a/docs/superpowers/plans/2026-08-13-azure-sre-agent-official-images.md +++ /dev/null @@ -1,318 +0,0 @@ -# Azure SRE Agent Official Images Implementation Plan - -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. - -**Goal:** Add five official Microsoft Learn Azure SRE Agent SVGs to the existing Korean briefing at the sections where each concept is explained. - -**Architecture:** Store unmodified official SVG files under a dedicated local asset folder so the briefing renders reliably without external image requests. Keep the product briefing responsible for conceptual explanations, while the lab README and validation report remain focused on reproduction and evidence. - -**Tech Stack:** Markdown, SVG, Python 3.12, pytest, curl - -## Global Constraints - -- Preserve each Microsoft Learn SVG without translating or editing its internal text. -- Add Korean prose and the source Microsoft Learn page next to every official image. -- Place images in existing matching sections; add sections only for root cause analysis, unified memory search, and automatic learning. -- Keep product-standard behavior distinct from the lab HTTP Trigger path. -- Do not add Storyboard or GIF references to the product briefing. -- Use only local image paths in Markdown. - ---- - -## File Structure - -- `monitor/sre-agent-event-lab/assets/official/`: local, unmodified copies of the five official Microsoft Learn SVG files. -- `monitor/azure-sre-agent.md`: customer/partner product briefing and the only document that embeds the official concept images. -- `monitor/sre-agent-event-lab/README.md`: reproduction guide; adds source links but does not duplicate concept images. -- `monitor/sre-agent-event-lab/scripts/tests/test_briefing_docs.py`: verifies required official assets, section placement, source attribution, local paths, and the Storyboard/GIF prohibition. - -### Task 1: Add and validate official SVG assets - -**Files:** -- Create: `monitor/sre-agent-event-lab/assets/official/incident-response-flow.svg` -- Create: `monitor/sre-agent-event-lab/assets/official/root-cause-analysis.svg` -- Create: `monitor/sre-agent-event-lab/assets/official/agent-reasoning-flow.svg` -- Create: `monitor/sre-agent-event-lab/assets/official/memory-unified-search.svg` -- Create: `monitor/sre-agent-event-lab/assets/official/memory-auto-learning.svg` -- Modify: `monitor/sre-agent-event-lab/scripts/tests/test_briefing_docs.py` - -**Interfaces:** -- Consumes: Official SVG responses from the five verified `learn.microsoft.com` asset URLs. -- Produces: Five local SVG paths that `monitor/azure-sre-agent.md` can reference. - -- [ ] **Step 1: Write the failing asset test** - -Add this test to `test_briefing_docs.py`: - -```python -OFFICIAL_ASSETS = { - "incident-response-flow.svg", - "root-cause-analysis.svg", - "agent-reasoning-flow.svg", - "memory-unified-search.svg", - "memory-auto-learning.svg", -} - - -def test_official_sre_agent_svgs_are_stored_locally(): - asset_dir = ( - REPO_ROOT - / "monitor" - / "sre-agent-event-lab" - / "assets" - / "official" - ) - - assert {path.name for path in asset_dir.glob("*.svg")} == OFFICIAL_ASSETS - for name in OFFICIAL_ASSETS: - svg = (asset_dir / name).read_text() - assert " 출처: [Automate Incident Response in Azure SRE Agent](https://learn.microsoft.com/azure/sre-agent/incident-response) -``` - -After the numbered investigation steps, add: - -```markdown -## 근본 원인은 어떻게 찾나요? - -![Azure SRE Agent 공식 근본 원인 분석 흐름](sre-agent-event-lab/assets/official/root-cause-analysis.svg) - -> 출처: [Root Cause Analysis in Azure SRE Agent](https://learn.microsoft.com/azure/sre-agent/root-cause-analysis) - -Azure SRE Agent는 오류 로그를 나열하는 데서 멈추지 않습니다. 증상을 기준으로 관련 로그, 메트릭, 배포 이력, 소스 코드와 과거 경험을 모으고 가능한 원인을 가설로 세웁니다. 이후 각 가설을 근거와 비교해 제외하거나 확인하고, 결론을 뒷받침하는 자료와 함께 조치 방안을 제시합니다. -``` - -In `권한과 승인 절차는 어떻게 제어하나요?`, place: - -```markdown -![Azure SRE Agent 공식 추론과 실행 흐름](sre-agent-event-lab/assets/official/agent-reasoning-flow.svg) - -> 출처: [Agent Reasoning in Azure SRE Agent](https://learn.microsoft.com/azure/sre-agent/agent-reasoning) -``` - -After `어떤 정보를 조사할 수 있나요?`, add the two independent sections: - -```markdown -## 과거 경험과 운영 문서는 어떻게 활용하나요? - -![Azure SRE Agent 공식 메모리 통합 검색 구조](sre-agent-event-lab/assets/official/memory-unified-search.svg) - -> 출처: [Memory and Knowledge in Azure SRE Agent](https://learn.microsoft.com/azure/sre-agent/memory) - -Azure SRE Agent는 과거 조사 대화, 사용자가 기억하도록 지정한 내용, 업로드한 운영 문서와 연결된 지식 원본을 함께 검색합니다. 답변에는 근거와 출처를 포함해 어떤 경험과 문서를 사용했는지 확인할 수 있습니다. - -## 조사가 끝난 뒤 무엇을 학습하나요? - -![Azure SRE Agent 공식 자동 학습 흐름](sre-agent-event-lab/assets/official/memory-auto-learning.svg) - -> 출처: [Memory and Knowledge in Azure SRE Agent](https://learn.microsoft.com/azure/sre-agent/memory) - -조사가 완료되면 Azure SRE Agent는 확인한 증상, 효과가 있었던 해결 단계, 근본 원인과 피해야 할 접근을 추출합니다. 이렇게 축적한 내용은 이후 유사한 인시던트를 조사할 때 다시 검색할 수 있습니다. -``` - -Move the existing local Korean process image and its editable SVG link to `이번 실증에서 사용한 방식`, immediately before the lab-specific text flow. Do not delete either file. - -- [ ] **Step 4: Run all briefing tests** - -Run: - -```bash -monitor/sre-agent-event-lab/app/.venv/bin/python -m pytest \ - monitor/sre-agent-event-lab/scripts/tests/test_briefing_docs.py \ - monitor/sre-agent-event-lab/scripts/tests/test_briefing_assets.py -v -``` - -Expected: all tests pass. - -- [ ] **Step 5: Commit the product briefing** - -```bash -git add monitor/azure-sre-agent.md \ - monitor/sre-agent-event-lab/scripts/tests/test_briefing_docs.py -git commit -m "docs(monitor): explain SRE Agent with official diagrams" -``` - -### Task 3: Update source links and run full verification - -**Files:** -- Modify: `monitor/sre-agent-event-lab/README.md` - -**Interfaces:** -- Consumes: Microsoft Learn source pages used by the product briefing. -- Produces: A reproduction guide with current official references and no duplicated concept images. - -- [ ] **Step 1: Update the official resources list** - -Add these links under `## 공식 자료` without embedding images: - -```markdown -- [Azure SRE Agent 제품 소개](../azure-sre-agent.md) -- [Incident response](https://learn.microsoft.com/azure/sre-agent/incident-response) -- [Root cause analysis](https://learn.microsoft.com/azure/sre-agent/root-cause-analysis) -- [Agent reasoning](https://learn.microsoft.com/azure/sre-agent/agent-reasoning) -- [Memory and knowledge](https://learn.microsoft.com/azure/sre-agent/memory) -``` - -- [ ] **Step 2: Run complete tests** - -Run: - -```bash -monitor/sre-agent-event-lab/app/.venv/bin/python -m pytest monitor/sre-agent-event-lab -``` - -Expected: `47 passed` plus the two new tests, for a total of `49 passed`. - -- [ ] **Step 3: Validate Bicep and document assets** - -Run: - -```bash -cd monitor/sre-agent-event-lab/infra -az bicep build --file subscription.bicep --stdout >/dev/null -az bicep build --file main.bicep --stdout >/dev/null -az deployment sub validate \ - --location koreacentral \ - --template-file subscription.bicep \ - --parameters subscription.bicepparam \ - --query properties.provisioningState -o tsv -``` - -Expected: `Succeeded`. - -From the repository root, run: - -```bash -test "$(grep -Eo '!\[[^]]*\]\([^)]+\)' monitor/azure-sre-agent.md | grep -Ec 'https?://')" -eq 0 -test "$(grep -Eic 'storyboard|\.gif' monitor/azure-sre-agent.md)" -eq 0 -git grep -I -nE \ - 'eyJ[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{10,}|-----BEGIN (RSA |EC |OPENSSH )?PRIVATE KEY-----|AccountKey=[A-Za-z0-9+/=]{20,}' \ - -- . ':!monitor/sre-agent-event-lab/evidence/**' && exit 1 || true -``` - -Expected: all commands exit with status 0 and print no secret matches. - -- [ ] **Step 4: Review the rendered briefing** - -Open the Markdown preview and verify: - -- all five official SVGs render at readable width; -- each image sits in its matching section; -- the local Korean process image appears only with the lab-specific path; -- the GitHub Issue, email draft, and Agent conclusion images still render; -- product-standard and lab-specific behavior remain visibly separated. - -- [ ] **Step 5: Commit the source-link update** - -```bash -git add monitor/sre-agent-event-lab/README.md -git commit -m "docs(monitor): link official SRE Agent concepts" -``` diff --git a/docs/superpowers/specs/2026-07-15-hdinsight-kafka-lag-scaled-test-design.md b/docs/superpowers/specs/2026-07-15-hdinsight-kafka-lag-scaled-test-design.md deleted file mode 100644 index b9cf596a..00000000 --- a/docs/superpowers/specs/2026-07-15-hdinsight-kafka-lag-scaled-test-design.md +++ /dev/null @@ -1,166 +0,0 @@ -# HDInsight Kafka Consumer Lag — 비율 축소 실증 테스트 설계 - -- 작성일: 2026-07-15 -- 대상: Azure HDInsight 5.1 / Kafka 3.2, PUBG India anticheat 로그 파이프라인 -- 상태: 설계안 (사용자 리뷰 대기) - -## 1. 문제 정의 - -### 1.1 프로덕션 현상 - -| 항목 | 값 | -|---|---| -| 브로커 | 18 × `Standard_D8a_v4` (8 vCPU / 32 GB RAM) | -| 데이터 디스크 | S30 Standard HDD (1 TB, ~60 MB/s, ~500 IOPS) × 4/노드 | -| 토픽 | `all_gs_g_ieg_pubgm_pubgm_india`, 파티션 180, RF 2 | -| 토픽 설정 | retention 36h, segment 1 GB, max.message 1 MB, compression=producer, min.insync.replicas=2 | -| 컨슈머 | rdkafka pod 240개 (단일 그룹) | -| 프로듀서 | filebeat, 12 TB/day, 야간 무부하·게임 피크 집중 | -| 증상 | 피크(15:30경) 약 7분 consumer lag → 야간 produce 감소 시 catch-up | - -### 1.2 목표 - -- 피크 시 consumer lag를 **1분 이내 회복**으로 낮추는 구성 도출 -- 프로덕션 변경 전에 **비율 축소 테스트**로 근거(실증) 확보 - -### 1.3 진단 (실증 대상 가설) - -**발견 1 — 컨슈머 병렬성은 180에 고정.** 단일 그룹에서 활성 컨슈머 상한 = 파티션 수 = 180. pod 240개 중 60개는 idle. pod 증설은 소비 처리량을 늘리지 못함. 고객이 관측한 "부하 50% + 컨슈머 90개 = 완화"는 컨슈머 수 효과가 아니라 **파티션당 유입률 절감** 효과. - -**발견 2 — 지배 변수는 브로커당 캐시 상주 시간.** - -``` -브로커당 리더 파티션 = 180 / 18 = 10 (RF2 → write 2배) -page cache ≈ RAM 32 GB − JVM heap ≈ 20 GB -피크 브로커당 produce율(복제 포함) ≈ 40 MB/s (가정) -T_cache = 20 GB / 40 MB/s ≈ 8분 ← 관측 7분 lag와 동일 자릿수 -``` - -컨슈머가 T_cache 이상 뒤처지면 읽을 오프셋이 page cache에서 축출 → S30 cold read → 디스크 IO 포화 → lag 가속 → produce가 멎는 야간에 해소. 부하 50% → T_cache 2배 → 캐시 내 소비 → lag 완화. 관측과 정합. - -**결론**: lag를 1분 내로 넣는 레버는 컨슈머 증설이 아니라, **브로커당 (캐시 상주 시간 T_cache) 대비 (컨슈머 소비 지연)** 을 키우는 것 — RAM↑, 디스크 tier↑, 브로커 증설, 부하 절감. - -## 2. 핵심 아이디어 — 비율 축소가 성립하는 근거 - -지배 무차원량: - -``` -ρ = (브로커당 유입률) / (브로커당 page cache) [1/시간] -T_cache = 1/ρ = 캐시 상주 시간 -``` - -lag 회복 조건: 컨슈머 소비 지연 < T_cache. - -**브로커당 사양(RAM·디스크 tier·파티션/브로커)을 프로덕션과 동일하게 두고, 브로커 수와 총 부하만 같은 배수 k로 축소하면 ρ가 보존**된다. 따라서 3-브로커 + (프로덕션 1/6) 부하 테스트베드는 18-브로커 프로덕션의 **브로커 1대 거동을 그대로 재현**한다. - -- 유지(불변): 브로커당 RAM=32 GB, 디스크 tier=S30, 브로커당 리더 파티션=10, RF=2, 토픽 설정 -- 축소(비율 k=6): 브로커 18→3, 파티션 180→30, produce 12 TB/day→2 TB/day, 활성 컨슈머 180→30 - -이 불변식이 축소 테스트의 프로덕션 대표성을 보장한다. - -## 3. 테스트베드 - -기존 세션 자산 재사용 + 브로커당 사양 정합. - -| 구성 요소 | 프로덕션 | 테스트베드(축소, k=6) | 비고 | -|---|---|---|---| -| 브로커 수 | 18 | 3 | ARM 템플릿 `workernode.targetInstanceCount` | -| 브로커 SKU | D8a v4 (32 GB) | **D8a v4 계열 32 GB로 정합** | 현재 배포본은 D4ads_v5(16GB) → 재생성 필요 | -| 데이터 디스크 | S30 ×4 | S30 상당 ×4 | HDInsight `dataDisksGroups` | -| 파티션 | 180 | 30 | 브로커당 10 유지 | -| RF | 2 | 2 | 동일 | -| 활성 컨슈머 | 180 | 30 | 파티션과 1:1 | -| produce 부하 | 12 TB/day | 2 TB/day | 부하 생성기로 재현 | - -기존 배포 자산: -- HDInsight 클러스터: `krafton-kafka-hdi-68944` (RG `rg-krafton-kafka-dev-jpe`, japaneast) -- 세션 파일: `hdi-kafka-template-public.json`, `recreate-public.sh`, `teardown.sh` -- 모니터링: JMX Exporter + Kafka Exporter + Prometheus + Grafana (VM + Managed Grafana) — `monitor/assets/prometheus-grafana/` - -### 3.1 부하 발생·소비 실행 위치 - -produce/consume는 **브로커와 분리된 전용 클라이언트에서 실행**한다. HDInsight headnode/workernode에서 직접 돌리면 브로커 CPU·네트워크를 잠식해 측정이 오염되므로 금지. - -**컨슈머를 VM으로? AKS pod로?** — 목적에 따라 갈린다. 이 테스트의 지배 가설은 브로커측(page cache eviction)이며, 브로커의 캐시·디스크 거동은 클라이언트가 VM이든 rdkafka pod든 **동일하다**(소비율과 뒤처짐 정도만 같으면 됨). 따라서 브로커를 증명하는 Arm은 VM으로 충분하고, 실제 rdkafka pod 재현은 **앱 자체가 병목인지 검증하는 Arm D에서만** 필요하다. - -``` -[클라이언트 VM] ──produce──▶ [HDInsight Kafka 3 broker] ◀──consume── [클라이언트 VM] - (같은 VNet, Kafka bin) (측정 대상) (동일/별도 VM) - │ - JMX/Kafka Exporter ─▶ Prometheus/Grafana (모니터 호스트) -``` - -| 옵션 | 장점 | 단점 | 채택 | -|---|---|---|---| -| **A. 전용 클라이언트 VM** | 브로커 부하 격리, produce/consume율 정밀 제어, SKU 자유 | VM 1대 추가 | **Baseline·A·B·C 채택** | -| B. HDInsight edge node | 같은 클러스터·VNet, Kafka bin 기본 | edge node 비용, 브로커와 자원 근접 | 대안 | -| **C. AKS pod (rdkafka)** | 실제 앱 거동·fetch 재현 | 구성 복잡, 정밀 부하 제어 난이 | **Arm D 채택** | - -- 프로듀서는 전 Arm 공통으로 **클라이언트 VM**에서 `kafka-producer-perf-test.sh` 실행(부하율은 브로커측 변수이지 앱 무관). -- 컨슈머: - - Baseline·A·B·C → **VM `kafka-consumer-perf-test.sh`** (또는 sleep 주입 컨슈머). 앱 변수 제거로 병목을 브로커로 격리. - - **Arm D → AKS pod에 고객 실제 rdkafka 설정** 배포(fetch 튜닝 없음/msg_cache 버퍼 그대로). 브로커 개선이 실제 pod 컨슈머에 이득으로 전달되는지, fetch 파라미터 튜닝 효과가 있는지 검증. -- 클라이언트 VM: HDInsight와 **동일 VNet**, 브로커보다 넉넉한 SKU(예: `Standard_D8s_v5`/`D16s_v5`)로 두어 부하 생성기 자신이 병목이 되지 않게 함. AKS도 동일 VNet(또는 peering). -- 도구: `kafka-producer-perf-test.sh --throughput --record-size 1000000` 로 produce율을 배율 k(2 TB/day 상당)에 고정. 소비측은 "피크 시 뒤처짐"을 인위 유발(일시 정지 또는 처리 지연 주입) 후 회복 시간 측정. -- produce율은 `--throughput`으로 인위 제한 → 클라이언트가 상한이 아니라 **브로커 동역학이 병목**임을 보장. - -## 4. 실험 매트릭스 (한 번에 한 변수) - -| Arm | 변경 대상 | 가설 | 성공 판정 | -|---|---|---|---| -| **Baseline** | 없음 (축소 정합 구성) | 7분급 lag 재현 | 피크 부하서 lag 정체가 재현됨 | -| **A. 부하 비율** | produce율만 100→75→50% 단계 | T_cache↑ | lag 회복<1분 되는 produce 임계 확인 | -| **B. 브로커 RAM** | 브로커 SKU → E-series(64 GB) | 캐시 2배 → cold read 방지 | 동일 부하서 회복<1분 | -| **C. 디스크 tier** | S30 → Premium SSD (가능 시) | cold read도 고속 | 회복<1분 + 디스크 포화 해소 | -| **D. 컨슈머 fetch** | fetch.min.bytes / queued.max.messages 튜닝 | 앱 병목 격리 | 브로커 지연 vs 소비 처리 분리 | - -각 Arm은 Baseline 대비 단일 변수만 변경. B·C는 HDInsight 특성상 클러스터 재생성 필요(§7 제약). - -## 5. 측정 지표 및 수집 - -| 지표 | 의미 | 수집원 | -|---|---|---| -| **consumer group lag 회복 시간** | 핵심 성공 지표 | Kafka Exporter → Grafana | -| page cache hit/miss | cold read 발생 여부 | node_exporter(추가) `node_vmstat_pgpgin` 등 | -| 디스크 read MB/s·IOPS·util | 디스크 병목 판정 | node_exporter `node_disk_*` | -| 브로커 BytesIn/Out, MessagesIn | 유입률 검증 | JMX Exporter | -| request/fetch 지연 | 브로커 처리 지연 | JMX Exporter | -| 컨슈머 처리율 | 소비측 처리 한계 | consumer-perf-test 출력 / 앱 지표 | - -기존 Grafana 대시보드로 대부분 커버. **node_exporter만 워커에 추가**하여 page cache/디스크 지표 확보. - -## 6. 실험 절차 - -1. **테스트베드 정합 배포** — ARM 템플릿을 브로커당 프로덕션 사양(32 GB, S30 ×4)으로 조정, 3-브로커 배포. node_exporter 추가. **동일 VNet에 클라이언트 VM(부하 생성기) 배포**. -2. **토픽 생성** — 파티션 30, RF 2, 프로덕션과 동일 설정. -3. **Baseline 재현** — 클라이언트 VM에서 2 TB/day 상당 produce + VM `consumer-perf-test` 30개(파티션 1:1). 컨슈머에 소량 지연/일시 정지를 주입해 "피크 시 뒤처짐" 유발 → lag 발생·회복 시간 측정. 7분급 정체 재현 확인. -4. **Arm A** — produce율 단계 감소, 각 단계에서 회복 시간 측정 → 회복<1분 임계 부하 도출. -5. **Arm B** — 브로커 E-series 재생성, Baseline 부하 반복 → 회복 시간 비교. -6. **Arm C** — Premium SSD 재생성(지원 확인 후), 반복. -7. **Arm D** — **AKS pod에 고객 rdkafka 설정 배포**, 브로커 개선안 위에서 fetch 파라미터(fetch.min.bytes/queued.max.messages) 조정·비교. VM 컨슈머 대비 실제 앱 거동 차이 확인. -8. **환산 및 권고** — §2 불변식으로 18-브로커 프로덕션에 대한 최소 비용 구성(SKU/디스크/부하/파티션) 권고 도출. - -각 실행: 워밍업 → 정상상태 → lag 유발 이벤트 → 회복 관측. 실행당 30–60분, 동일 조건 3회 반복해 분산 확인. - -## 7. 제약 및 오픈 이슈 - -- **HDInsight SKU/디스크 변경 = 클러스터 재생성** (in-place resize 불가). Arm B·C는 재배포 비용·시간이 큼. `recreate-public.sh` 활용. -- **HDInsight Kafka 데이터 디스크의 Premium SSD 지원 여부 확인 필요** — 미지원 시 Arm C는 "디스크 개수 증설" 또는 "브로커 증설"로 대체. -- **부하 생성기가 실제 filebeat 트래픽 특성(메시지 크기 분포·배치)을 근사** — max.message 1 MB, compression=producer 반영해 record-size 정렬. -- **비용 관리** — 각 Arm 테스트 후 즉시 teardown. 야간 유휴 클러스터·클라이언트 VM·AKS 방치 금지. -- **Arm D AKS 구성** — 실제 rdkafka 컨슈머 이미지·설정 확보 필요(고객 이미지 또는 동등 재현). AKS는 HDInsight와 동일 VNet 또는 peering. -- **테스트베드 리전/구독** — 프로덕션과 동일 japaneast, contoso 구독(검증됨). - -## 8. 산출물 - -`monitor/` 문서 패턴에 맞춘 실증 리포트: -- 축소 재현 방법론(§2 불변식)과 절차 -- Arm별 lag 회복 시간 비교표 + Grafana 캡처 -- 결론: "브로커당 T_cache > 소비 지연이면 lag<1분 회복" + 프로덕션 권고(권장 SKU/디스크/파티션/부하 임계) - -## 9. 비범위 (YAGNI) - -- 18-브로커 풀스케일 재현 (비용 과다, 축소로 충분) -- rdkafka 앱 코드 리팩터링 (fetch 파라미터 외) -- MirrorMaker/멀티 리전 등 토폴로지 변경 -- Locust 기반 HTTP 부하 자산 (Kafka 벤치와 무관) diff --git a/docs/superpowers/specs/2026-08-12-azure-sre-agent-event-testing-design.md b/docs/superpowers/specs/2026-08-12-azure-sre-agent-event-testing-design.md deleted file mode 100644 index f00f5365..00000000 --- a/docs/superpowers/specs/2026-08-12-azure-sre-agent-event-testing-design.md +++ /dev/null @@ -1,256 +0,0 @@ -# Azure SRE Agent 이벤트 기반 장애 분석 실증 테스트 설계 - -- 작성일: 2026-08-12 -- 대상 구독: `95933ae5-0201-4a21-a1fc-8051a7437982` -- 배포 리전: `koreacentral` -- 상태: 승인된 설계 - -## 1. 목표 - -격리된 Azure 테스트 리소스를 실제로 배포하고, Azure Monitor 경고를 Azure SRE Agent가 자동 수신해 장애를 올바르게 분석하는지 검증한다. - -검증 범위는 다음과 같다. - -1. Azure Monitor 경고가 실제 장애를 탐지한다. -2. Azure SRE Agent가 경고를 이벤트 기반으로 수신하고 조사 스레드를 시작한다. -3. Agent가 로그, 메트릭, 리소스 구성, 최근 변경 사항을 연결해 원인을 설명한다. -4. Agent가 제시한 완화책이 실제 원인과 일치하고 안전하다. -5. 결과를 이 저장소의 기존 실증 보고서 형식으로 기록한다. - -Agent의 자동 변경 능력 자체는 이번 실험의 핵심이 아니다. 모든 incident response plan은 `Review` 모드로 설정해 조사와 제안은 자동화하되 실제 변경은 승인 없이 실행하지 못하게 한다. - -## 2. 접근 방법 - -### 2.1 채택: Azure Container Apps 기반 격리형 실험실 - -Container Apps는 짧은 시간에 배포할 수 있고, revision 변경, 애플리케이션 로그, 의존성 오류, 응답 시간과 같은 서로 다른 증거를 Azure Monitor에서 함께 관찰할 수 있다. AKS보다 운영 노이즈와 비용이 낮고 App Service보다 컨테이너 상태와 revision 변경을 풍부하게 노출하므로 이번 Agent 분석 평가에 가장 적합하다. - -### 2.2 검토한 대안 - -| 접근 | 장점 | 제외 이유 | -|---|---|---| -| AKS | pod crash, OOM, node, RBAC 등 가장 많은 장애 유형 | 클러스터 배포 시간과 비용이 크고, Agent의 이벤트 기반 조사보다 Kubernetes 자체 복잡도가 결과를 지배할 수 있음 | -| App Service | 가장 단순한 웹 앱 배포 | revision과 컨테이너 시스템 로그의 상관분석 범위가 좁아 Agent 평가 시나리오가 제한됨 | - -## 3. 아키텍처 - -모든 실험 리소스는 고유 suffix를 가진 새 리소스 그룹에 격리한다. - -```text -GitHub repository - ├─ test application source - ├─ infrastructure as code - └─ incident runbook - │ - ▼ -Azure SRE Agent (Review mode) - ├─ Azure Monitor incident platform - ├─ managed resource group access - ├─ Log Analytics / Application Insights connector - └─ GitHub connector - ▲ - │ 1-minute alert scanner -Azure Monitor alert rules - ├─ HTTP 5xx rate - ├─ p95 request duration - └─ dependency authorization failures - ▲ - │ metrics, traces, logs, activity -Azure Container Apps test workload - ├─ instrumented HTTP API - ├─ user-assigned managed identity - └─ Azure Storage dependency -``` - -### 3.1 리소스 - -| 리소스 | 용도 | -|---|---| -| Resource group | 전체 실험 자산과 비용을 격리하고 일괄 정리 | -| Azure SRE Agent | 경고 수신, 조사, 보고서 생성 | -| Log Analytics workspace | Container Apps 시스템/콘솔 로그 및 Agent 진단 로그 저장 | -| Application Insights | 요청, 예외, dependency trace, 응답 시간 수집 | -| Azure Container Apps environment | 테스트 앱 실행 환경 | -| Azure Container App | 결정론적 장애를 발생시키는 HTTP API | -| Azure Container Registry | 테스트 이미지 빌드 및 저장 | -| Storage account/container | managed identity 기반 실제 외부 의존성 | -| Azure Monitor alert rules | 세 가지 시나리오를 incident event로 변환 | - -### 3.2 애플리케이션 경계 - -테스트 앱은 다음 기능만 가진다. - -- `/healthz`: 장애 모드와 무관한 liveness 확인 -- `/api/orders`: 정상 요청, 지연, HTTP 500을 재현 -- `/api/documents`: managed identity로 Blob Storage를 호출해 dependency 인증 장애를 재현 -- 구조화 로그: scenario ID, revision, operation, status, elapsed time, correlation ID -- Application Insights 분산 추적: request, exception, dependency telemetry - -장애 모드는 Container App 환경 변수로 활성화한다. 각 변경은 새 revision을 만들므로 Agent가 오류 시작 시점과 configuration change를 상관분석할 수 있다. - -## 4. 이벤트 처리 흐름 - -1. 실행 스크립트가 한 시나리오의 장애 모드를 활성화한다. -2. 제한된 부하 생성기가 해당 API를 호출해 충분한 telemetry를 만든다. -3. Azure Monitor alert rule이 조건을 만족해 Sev2 경고를 발생시킨다. -4. Azure SRE Agent scanner가 최대 1분 주기로 새 경고를 확인한다. -5. severity와 title filter가 일치하는 response plan이 조사 스레드를 연다. -6. Agent는 Application Insights, Log Analytics, Azure Resource Graph, Activity Log, 연결된 저장소와 runbook을 조사한다. -7. Agent가 원인, 증거, 영향, 즉시 완화책, 영구 개선책을 제시한다. -8. 실행자는 조사 결과를 캡처한 뒤 장애를 복구한다. -9. 정상 telemetry와 alert resolved 상태를 확인한 뒤 다음 시나리오를 시작한다. - -동일 alert rule의 반복 firing은 하나의 조사 스레드로 병합될 수 있으므로 각 시나리오는 별도 alert rule과 고유 title을 사용한다. - -## 5. 실험 시나리오 - -### 5.1 S1: 배포 구성 오류로 HTTP 500 급증 - -| 항목 | 설계 | -|---|---| -| 주입 | `FAILURE_MODE=http500` 환경 변수로 새 revision 배포 | -| 트래픽 | `/api/orders`에 2분 동안 일정 요청 | -| 경고 | 5분 창에서 실패 요청 수가 임계값 초과 | -| ground truth | 새 revision의 환경 변수로 오류 경로가 활성화됨 | -| 기대 조사 | 오류 시작 시점, affected revision, exception/log pattern, 최근 configuration change 식별 | -| 기대 완화 | 정상 환경 변수로 revision 교체 또는 직전 정상 revision으로 traffic 복귀 | - -### 5.2 S2: 인위적 지연으로 p95 latency 급증 - -| 항목 | 설계 | -|---|---| -| 주입 | `ORDER_DELAY_MS=4000` 환경 변수로 새 revision 배포 | -| 트래픽 | `/api/orders`에 3분 동안 동시 요청 | -| 경고 | p95 request duration이 2초를 초과 | -| ground truth | 새 revision에 4초 지연이 설정됨 | -| 기대 조사 | 오류율은 낮지만 duration만 증가한 사실, 느린 operation과 revision, 최근 환경 변수 변경 식별 | -| 기대 완화 | 지연 설정 제거 또는 직전 정상 revision으로 traffic 복귀 | - -### 5.3 S3: Storage RBAC 제거로 dependency 403/503 발생 - -| 항목 | 설계 | -|---|---| -| 주입 | Container App managed identity의 테스트 container 데이터 역할을 제거 | -| 트래픽 | `/api/documents`에 2분 동안 일정 요청 | -| 경고 | Blob dependency failure 또는 앱의 503 응답 수가 임계값 초과 | -| ground truth | identity 자체는 유지되지만 data-plane role assignment가 제거됨 | -| 기대 조사 | Blob 403, 실패 dependency target, managed identity, 최근 role assignment 삭제 활동 식별 | -| 기대 완화 | 최소 범위에서 원래 data-plane role을 복원 | - -S3 역할 삭제와 복구는 테스트 Storage container 범위에만 적용한다. 다른 리소스의 권한은 변경하지 않는다. - -## 6. Agent 구성과 권한 - -### 6.1 Agent 설정 - -- Agent region: `koreacentral` -- Incident platform: Azure Monitor -- Response plans: S1, S2, S3 title filter와 Sev2 -- Autonomy: `Review` -- Quickstart response plan: 중복 처리를 피하기 위해 비활성화 또는 삭제 -- Context: 이 저장소, 테스트 리소스 그룹, Log Analytics/Application Insights connector, incident runbook - -### 6.2 최소 권한 - -- 테스트 리소스 그룹: Agent managed identity에 `Reader` -- Azure Monitor scanner: 공식 요구사항에 따라 대상 구독에 `Monitoring Contributor` -- 로그 조회: connector 저장 과정에서 필요한 역할을 자동 할당하되 실제 할당 결과를 기록 -- remediation: 이번 테스트에서는 Contributor를 부여하지 않음 - -`Monitoring Contributor`가 구독 범위에 필요한 점은 잔여 위험이다. 실험 종료 시 해당 role assignment를 제거하고 제거 여부를 보고서에 기록한다. - -## 7. 안전, 오류 처리, 정리 - -- 기본 구독 외 다른 구독은 사용하지 않는다. -- 모든 생성 리소스에 `purpose=sre-agent-event-lab`, `expiresOn=2026-08-13` 태그를 적용한다. -- 부하 생성은 테스트 Container App FQDN에만 전송하고 요청률을 제한한다. -- 한 번에 하나의 장애만 활성화한다. -- 각 시나리오 시작 전 baseline health, alert 상태, active revision을 저장한다. -- alert가 firing되지 않으면 임계값을 임의로 계속 낮추지 않는다. telemetry 수집, query 결과, evaluation window를 순서대로 확인한다. -- Agent가 조사를 시작하지 않으면 managed identity role, alert firing 상태, response plan filter, scanner lookback을 확인한다. -- 장애 복구와 정상 상태 확인 없이 다음 시나리오로 진행하지 않는다. -- 최종 산출물 확인 후 테스트 RG와 구독 범위 role assignment를 정리한다. Agent를 후속 실험에 보존할지는 결과 보고서에서 명시한다. - -## 8. 평가 기준 - -### 8.1 정량 지표 - -| 지표 | 정의 | 목표 | -|---|---|---| -| Alert detection latency | 장애 시작부터 Azure Monitor firing까지 | 10분 이내 | -| Agent pickup latency | alert firing부터 조사 스레드 생성까지 | 3분 이내 | -| Investigation completion | 스레드 시작부터 첫 구조화 결론까지 | 15분 이내 | -| Correct affected resource | 올바른 앱/revision/dependency 식별 | 3/3 | -| Correct root cause | ground truth와 일치하는 직접 원인 식별 | 3/3 | -| Safe mitigation | 테스트 범위 밖 변경을 제안하지 않음 | 3/3 | - -Azure Monitor scheduled query evaluation과 ingestion 지연 때문에 alert detection 목표는 여유 있게 10분으로 둔다. Agent scanner 자체는 공식 문서 기준 1분 주기다. - -### 8.2 시나리오별 품질 점수 - -각 시나리오는 10점 만점으로 채점한다. - -| 항목 | 점수 | 판정 기준 | -|---|---:|---| -| 영향 범위 식별 | 2 | resource, endpoint, revision/dependency가 정확함 | -| 직접 원인 식별 | 3 | ground truth를 직접 원인으로 명시함 | -| 증거 사용 | 2 | 실제 query/log/metric/config/activity evidence를 제시함 | -| 완화책 | 2 | 원인을 되돌리는 최소 변경이며 안전함 | -| 불확실성 표시 | 1 | 확인되지 않은 추론을 사실처럼 단정하지 않음 | - -판정은 `Pass >= 8`, `Partial 5-7`, `Fail < 5`로 한다. 종합 성공 조건은 세 시나리오 모두 `Partial` 이상이고, 두 시나리오 이상 `Pass`, 잘못된 autonomous action 0건이다. - -## 9. 테스트 및 검증 - -### 9.1 배포 검증 - -- IaC 문법 및 배포 what-if 성공 -- 앱 unit test와 컨테이너 health check 성공 -- 정상 baseline 요청의 2xx, trace, log, dependency telemetry 확인 -- 세 alert query를 실행해 정상 상태에서 0건 또는 임계값 미만 확인 - -### 9.2 시나리오 검증 - -각 시나리오에서 다음 증거를 저장한다. - -1. 장애 주입 명령과 정확한 UTC 시각 -2. Container App revision 및 구성 변경 -3. 부하 생성 결과 -4. Azure Monitor query 결과와 alert firing 시각 -5. Azure SRE Agent incident thread 생성 및 완료 시각 -6. Agent의 원인, 근거, 완화책 -7. 실제 ground truth와 점수 -8. 복구 명령과 정상화 증거 - -## 10. 산출물 - -```text -monitor/sre-agent-event-lab/ - app/ - infra/ - scripts/ - runbooks/ - README.md -docs/superpowers/plans/2026-08-12-azure-sre-agent-event-testing-execution.md -docs/superpowers/reports/2026-08-12-azure-sre-agent-event-testing-results.md -``` - -결과 보고서는 기존 실증 보고서 형식을 따라 다음 순서로 작성한다. - -1. 실행 환경과 목표 -2. 한눈에 보기 -3. Agent 및 observability 구성 -4. 시나리오별 타임라인, 증거, Agent 분석, 점수 -5. 시나리오 간 비교 -6. 결론과 운영 권고 -7. 비용 및 정리 상태 - -## 11. 공식 참고 자료 - -- [Azure SRE Agent overview](https://learn.microsoft.com/azure/sre-agent/overview) -- [Create and set up Azure SRE Agent](https://learn.microsoft.com/azure/sre-agent/create-and-set-up) -- [Azure Monitor alerts in Azure SRE Agent](https://learn.microsoft.com/azure/sre-agent/azure-monitor-alerts) -- [Automate incident response](https://learn.microsoft.com/azure/sre-agent/automate-incidents) -- [Incident platforms](https://learn.microsoft.com/azure/sre-agent/incident-platforms) -- [Log Analytics and Application Insights connectors](https://learn.microsoft.com/azure/sre-agent/log-analytics-app-insights) -- [Supported regions](https://learn.microsoft.com/azure/sre-agent/supported-regions) diff --git a/docs/superpowers/specs/2026-08-12-azure-sre-agent-evidence-capture-design.md b/docs/superpowers/specs/2026-08-12-azure-sre-agent-evidence-capture-design.md deleted file mode 100644 index b016af50..00000000 --- a/docs/superpowers/specs/2026-08-12-azure-sre-agent-evidence-capture-design.md +++ /dev/null @@ -1,163 +0,0 @@ -# Azure SRE Agent 실제 동작 증거 캡처 설계 - -- 작성일: 2026-08-12 -- 대상: Azure SRE Agent 이벤트 기반 장애 분석 실증 테스트 -- 상태: 승인된 설계 - -## 1. 목적 - -각 장애 시나리오에서 Azure Monitor 경고가 발생한 뒤 Azure SRE Agent가 incident를 수신하고 조사·결론에 도달하는 실제 흐름을 재현 가능한 증거로 남긴다. - -Portal UI 녹화만으로는 API evidence를 검증하기 어렵고 현재 실행 환경에는 UI 자동화 도구가 없다. 따라서 실제 SRE Agent data-plane 상태를 원본으로 캡처하고, 그 상태 변화를 자동으로 GIF와 Markdown 타임라인으로 렌더링한다. Portal 녹화는 사용자가 UI 모양 자체를 보존하려는 경우의 선택 절차로 둔다. - -## 2. 채택 방식 - -### Hybrid actual-evidence capture - -각 scenario마다 다음 세 계층을 만든다. - -1. **원본 증거:** Azure Monitor alert와 SRE Agent API response JSON -2. **정규화 증거:** secret을 제거한 timestamp/event timeline JSON -3. **표현 자료:** PNG frame, animated GIF, Mermaid sequence, Markdown 표 - -GIF는 실제 UI를 흉내 낸 mockup이 아니다. 실제 alert/thread/message/action 상태를 timestamp 순으로 카드에 표시한 시각적 재생 자료다. 각 frame은 원본 evidence의 event ID를 포함해 추적 가능해야 한다. - -## 3. 캡처 대상 - -### 3.1 Azure Monitor - -- alert ID, rule, severity, monitor condition -- fired/resolved timestamp -- target resource -- alert context와 search interval - -### 3.2 Azure SRE Agent - -- incident thread ID와 생성 timestamp -- thread status와 title -- message ID, role, timestamp, text 요약 -- tool/action event 이름, 시작/완료 상태, timestamp -- approval request와 decision 상태 -- 첫 구조화 결론 timestamp - -API response에 tool/action 세부 정보가 없으면 message와 thread status만 사용하고, 없는 데이터를 추정해 만들지 않는다. - -### 3.3 Observability - -- alert query 집계값 -- 관련 request, exception, dependency 요약 -- Container App revision/configuration change -- Activity Log 변경 event - -## 4. 파일 구조 - -```text -monitor/sre-agent-event-lab/evidence/ - s1-20260812T050000Z/ - alert.json - thread-snapshots/ - 0001.json - 0002.json - messages.json - normalized-timeline.json - -monitor/sre-agent-event-lab/assets/captures/ - s1/ - 01-alert-fired.png - 02-thread-created.png - 03-investigating.png - 04-conclusion.png - investigation.gif - timeline.mmd -``` - -`evidence/`는 Git에서 제외한다. redaction을 통과한 `assets/captures/`만 commit한다. - -## 5. 데이터 흐름 - -1. scenario runner가 장애 주입 UTC와 alert ID를 저장한다. -2. capture script가 SRE Agent `/api/v1/threads`를 polling한다. -3. alert title 또는 target resource와 일치하는 새 thread를 식별한다. -4. thread와 message endpoint를 상태 변경 시마다 snapshot한다. -5. 완료 또는 timeout 뒤 normalizer가 events를 시간순으로 정렬하고 redact한다. -6. renderer가 정규화 JSON에서 frame PNG와 GIF를 만든다. -7. Markdown generator가 보고서용 표와 Mermaid sequence를 만든다. -8. verifier가 GIF frame 수, 원본 event ID 대응, secret pattern 부재를 검사한다. - -## 6. 시각 디자인 - -각 frame은 1280×720 고정 크기와 다음 영역을 사용한다. - -- header: scenario, UTC, elapsed time, current state -- left: Azure Monitor alert card -- center: investigation timeline -- right: latest Agent message/tool/action -- footer: alert ID/thread ID의 짧은 hash, evidence file name - -상태 색상: - -- alert fired: red -- thread created / investigating: amber -- evidence found: blue -- conclusion / resolved: green -- timeout / API failure: gray - -한 frame은 1.5초, 결론 frame은 3초 표시한다. 동일 상태가 반복되면 한 frame으로 병합한다. - -## 7. Redaction과 안전 - -다음 값은 저장 또는 렌더링 전에 제거한다. - -- bearer token과 access token -- connection string, instrumentation key -- Authorization/Cookie header -- repository credential/PAT -- 전체 query result 중 사용자 식별 정보 -- managed identity token endpoint response - -resource ID, alert ID, thread ID, message ID는 실험 추적에 필요하므로 유지하되 GIF footer에는 짧은 hash만 표시한다. - -normalizer가 redaction forbidden pattern을 발견하면 렌더링을 실패시킨다. 성공 모양의 빈 GIF를 만들지 않는다. - -## 8. 오류 처리 - -- thread가 timeout 내 생성되지 않으면 alert와 polling 로그를 보존하고 `thread-not-created` frame을 만든다. -- API가 401/403이면 즉시 중단하고 SRE Agent RBAC를 확인한다. -- API가 429/5xx이면 `Retry-After`를 존중해 bounded retry한다. -- message schema가 달라지면 원본 JSON을 보존하고 renderer가 unknown event를 명시한다. -- GIF 생성 도구가 없으면 PNG와 Mermaid/Markdown을 생성하고 보고서에 GIF 미생성 이유를 기록한다. - -## 9. Portal 수동 녹화 - -Portal UI 원본이 필요한 경우: - -1. SRE Agent incident thread를 연다. -2. macOS 화면 기록으로 해당 창만 녹화한다. -3. alert card, investigation plan, evidence, conclusion을 순서대로 보여준다. -4. token, 계정 메뉴, unrelated resource를 녹화하지 않는다. -5. 30~60초 MP4를 GIF로 변환하고 시나리오 asset 폴더에 둔다. - -수동 녹화는 API evidence를 대체하지 않는다. 보고서의 사실 판정은 원본 API와 Azure Monitor evidence를 기준으로 한다. - -## 10. 검증 기준 - -각 scenario는 다음을 만족해야 한다. - -- alert fired, thread created, investigating, conclusion의 4개 상태가 있거나 누락 상태를 명시 -- 모든 frame timestamp가 정규화 timeline event와 일치 -- alert ID와 thread ID가 원본 JSON과 연결 -- PNG 최소 4장, GIF 최소 4 frame -- forbidden secret pattern 0건 -- GIF 재생성 명령이 README에 존재 -- 보고서에서 capture asset과 원본 evidence 경로를 찾을 수 있음 - -## 11. 보고서 반영 - -각 scenario section에 다음을 추가한다. - -1. investigation GIF -2. 결론 frame PNG -3. alert-to-conclusion Mermaid sequence -4. 실제 event timeline 표 -5. evidence 경로와 재생성 명령 -6. Portal 수동 녹화가 있으면 별도 링크 diff --git a/docs/superpowers/specs/2026-08-12-azure-sre-agent-introduction-design.md b/docs/superpowers/specs/2026-08-12-azure-sre-agent-introduction-design.md deleted file mode 100644 index c37bcabe..00000000 --- a/docs/superpowers/specs/2026-08-12-azure-sre-agent-introduction-design.md +++ /dev/null @@ -1,314 +0,0 @@ -# Azure SRE Agent 소개 자료 재구성 설계 - -- 작성일: 2026-08-12 -- 대상 독자: Azure 운영자, SRE, 클라우드 아키텍트, 기술 의사결정자 -- 상태: 승인된 설계 - -## 1. 문제 정의 - -현재 문서는 실험 환경, 시간 지표, 점수부터 시작하는 실증 보고서다. Azure SRE Agent를 처음 접하는 독자는 다음 내용을 먼저 이해하기 어렵다. - -1. Azure SRE Agent가 어떤 운영 문제를 해결하는가 -2. Azure Monitor, Application Insights, source code, incident platform을 어떻게 연결하는가 -3. Agent가 단순 log search가 아니라 어떤 방식으로 가설을 만들고 검증하는가 -4. Review mode와 approval이 실제 조치 위험을 어떻게 통제하는가 -5. 분석 결과가 ticket, email, Teams 같은 기존 운영 흐름으로 어떻게 전달되는가 -6. 각 GIF에서 어떤 장애가 발생했고 무엇을 확인해야 하는가 - -새 문서는 제품 소개를 주 산출물로 만들고, 기존 실증 보고서는 제품의 실제 동작을 입증하는 부록으로 재배치한다. - -## 2. 접근 방식 - -### 채택: Hybrid 제품 소개 + 대표 운영 패턴 - -제품 개념을 짧고 시각적으로 소개한 뒤, HTTP 500 대표 시나리오를 end-to-end로 깊게 설명한다. latency와 RBAC 시나리오는 “다른 유형에도 같은 조사 패턴이 적용된다”는 비교 사례로 정리한다. - -### 검토한 대안 - -| 접근 | 장점 | 제외 이유 | -|---|---|---| -| Product-first 기능 카탈로그 | Microsoft Learn 구조와 유사, 참조성이 높음 | 초반이 설명서처럼 느껴지고 실제 가치 이해가 늦음 | -| 시나리오 사례집 | 읽기 쉽고 GIF 활용이 자연스러움 | 제품 기능, 권한, connector, safety model 설명이 부족 | - -## 3. 산출물 - -### 3.1 주 소개 문서 - -경로: - -```text -monitor/azure-sre-agent.md -``` - -목차: - -1. 한 문장 소개 -2. 운영 전후 비교 -3. Azure SRE Agent가 동작하는 방식 -4. 핵심 구성 요소와 연결 -5. 안전 모델: ReadOnly, Review, Autonomous -6. 대표 운영 패턴: HTTP 500 → 분석 → ticket → email -7. 실제 Agent 조사 storyboard와 GIF -8. 추가 패턴: latency, RBAC, Dynamic Thresholds -9. 티켓/알림 connector 운영화 -10. 도입 체크리스트와 한계 -11. 상세 실증 보고서 링크 - -### 3.2 실증 보고서 - -기존 파일을 유지하되 제목과 도입부를 “소개 자료의 실제 동작 검증 부록”으로 변경한다. - -```text -docs/superpowers/reports/2026-08-12-azure-sre-agent-event-testing-results.md -``` - -보고서에는 원본 시간·점수·증거를 유지하고, 주 소개 문서로 돌아가는 링크를 추가한다. - -### 3.3 시나리오 시각 자료 - -```text -monitor/sre-agent-event-lab/assets/storyboards/ - s1/ - investigation-guide.gif - 01-situation.png - 02-expectation.png - 03-alert-fired.png - 04-thread-created.png - 05-evidence.png - 06-conclusion.png - 07-operational-output.png - s2/ - s3/ -``` - -### 3.4 운영 결과 artifact - -```text -monitor/sre-agent-event-lab/assets/notifications/ - s1-incident-summary.html - s1-incident-summary.eml - s1-email-preview.png - github-issue.json - github-issue.png -``` - -## 4. Microsoft Learn 이미지 사용 - -공식 이미지는 repository에 복제하지 않고 Microsoft Learn 원본 URL을 Markdown에서 직접 참조한다. 각 이미지 바로 아래에 원문 제목과 링크를 표시한다. - -| 소개 위치 | 공식 이미지 | -|---|---| -| 가설 기반 RCA | `media/root-cause-analysis/root-cause-analysis.svg` | -| Response plan | `media/tutorial-incident-response/incident-response-plans.png` | -| Memory search | `media/tutorial-incident-response/sample-app-memory-search-results.png` | -| Managed connectors | `media/managed-connectors/managed-connectors-icon-grid.png` | -| Connector operation selection | `media/managed-connectors/office365-operations.png` | -| Locked parameters / governance | `media/managed-connectors/office365-parameter-policy.png` | - -이미지를 수정하거나 Microsoft UI처럼 보이는 가짜 화면을 만들지 않는다. 자체 제작 diagram과 official screenshot을 명확히 구분한다. - -## 5. 제품 소개 메시지 - -### 5.1 한 문장 - -Azure SRE Agent는 alert를 받아 Azure telemetry, resource configuration, deployment history, source code, past incident knowledge를 연결해 root cause와 안전한 mitigation을 제안하는 AI 기반 reliability assistant다. - -### 5.2 핵심 가치 - -```text -Detect → Investigate → Recommend/Act → Communicate → Learn -``` - -- **Detect:** Azure Monitor, PagerDuty, ServiceNow, HTTP Trigger -- **Investigate:** Application Insights, Log Analytics, Resource Graph, Activity Log -- **Correlate:** GitHub/Azure DevOps source, runbook, past incident memory -- **Recommend/Act:** Review approval 또는 제한된 Autonomous action -- **Communicate:** ticket, email, Teams/Slack -- **Learn:** resolved incident의 root cause와 resolution을 memory에 축적 - -### 5.3 단순 log search와의 차이 - -Agent는 log를 나열하지 않고 다음 순서로 조사한다. - -1. incident boundary와 사용자 영향을 정의 -2. 가능한 root-cause hypothesis 생성 -3. metrics, logs, changes, code로 hypothesis 검증/기각 -4. evidence chain과 uncertainty를 포함한 결론 작성 -5. reversible하고 최소 범위인 mitigation 제안 - -## 6. 대표 시나리오 storyboard - -### 6.1 상황 - -새 Container App revision의 설정 오류로 `/api/orders`가 HTTP 500을 반환한다. 사용자는 주문 처리 실패를 경험하고 on-call engineer는 Azure Monitor alert를 받는다. - -### 6.2 기대 동작 - -1. Azure Monitor가 500 anomaly를 감지한다. -2. Action Group이 Review-mode SRE workflow를 호출한다. -3. Agent가 affected endpoint와 UTC onset을 찾는다. -4. Application Insights의 120개 failed request를 확인한다. -5. Container App revision과 `FAILURE_MODE=http500`을 상관 분석한다. -6. connected repository와 Activity Log로 code/change evidence를 보강한다. -7. rollback/config restoration을 최소 mitigation으로 제안한다. -8. 결과를 ticket으로 생성하고 on-call email 초안을 만든다. - -### 6.3 실제 결과 - -- Alert fired 후 Agent thread 생성: 2초 -- 첫 구조화 결론: thread 생성 후 143초 -- 영향을 받은 request: `/api/orders` HTTP 500 120건 -- root cause: revision `0000010`, `FAILURE_MODE=http500` -- mitigation: 정상 setting revision으로 traffic 복귀 -- Agent는 resource를 변경하지 않고 Review mode에서 결론만 제시 - -## 7. GIF 재설계 - -기존 GIF는 실제 event만 보여주므로 처음 보는 독자가 상황을 알기 어렵다. 새 GIF는 설명 frame과 실측 frame을 구분한다. - -### Frame 구조 - -| 순서 | 유형 | 내용 | -|---:|---|---| -| 1 | 설명 | 상황: 주문 API 500, 사용자 영향 | -| 2 | 설명 | 기대: telemetry/change/code를 조사하고 rollback 제안 | -| 3 | 실측 | Azure Monitor alert fired | -| 4 | 실측 | Agent thread created | -| 5 | 실측 | Application Insights/revision evidence | -| 6 | 실측 | root cause conclusion | -| 7 | 설명+실제 output | GitHub Issue URL, email preview, Review 상태 | - -설명 frame에는 `SCENARIO` badge, 실제 API evidence frame에는 `ACTUAL` badge를 표시한다. 마지막 frame은 “무엇이 해결됐고 다음 운영 action이 무엇인지”를 한눈에 보여준다. - -### 문서 내 배치 - -GIF 앞: - -1. 상황 -2. 사용자 영향 -3. Agent에게 기대하는 것 - -GIF 뒤: - -1. Agent가 실제 확인한 evidence -2. conclusion -3. ticket/email output -4. 기대와 실제의 차이 - -S2/S3도 같은 구조를 사용하되 본문에서는 scenario card와 대표 conclusion frame을 먼저 보여주고 GIF는 접이식 상세 또는 링크로 배치한다. - -## 8. 티켓 시나리오 - -### 8.1 실제 GitHub Issue - -`hellices/devguidesample`에 다음 구조로 실제 issue를 생성한다. - -```text -Title: [SRE-LAB] ca-sre-event-lab-vnet HTTP 500 incident - -Impact -Detection -Root cause -Evidence -Current status -Recommended follow-up -Agent thread ID -Detailed report path -``` - -issue에는 token, connection string, private callback URL, user identity claim을 포함하지 않는다. issue 생성 결과의 number/URL을 JSON과 screenshot으로 보존한다. - -### 8.2 운영 전환 - -Microsoft Learn 기준으로 다음 선택지를 설명한다. - -- GitHub connector: issue 생성·검색·comment -- Azure DevOps connector: work item 생성 -- ServiceNow/PagerDuty incident platform: acknowledge, update, resolve -- Jira managed connector 또는 custom MCP ticketing server - -## 9. 이메일 시나리오 - -### 9.1 이번 실증 - -실제 수신자와 Outlook OAuth consent가 없으므로 email을 전송하지 않는다. Agent의 S1 conclusion에서 다음 artifact를 생성한다. - -- RFC 5322 `.eml` -- HTML body -- browser screenshot - -email 내용: - -```text -Subject: [Resolved][SRE-LAB] Order API HTTP 500 incident -Severity / Service / UTC window -Customer impact -Root cause -Evidence -Mitigation / Current status -Ticket link -Follow-up actions -``` - -### 9.2 운영 전환 - -Outlook connector의 Send email operation을 사용한다. - -- `To`: User-defined locked parameter -- `Subject`, `Body`: Agent-defined -- Permission: Review workflow에서 `Ask` -- Autonomous workflow에서는 `Ask`가 bypass될 수 있으므로 별도 read-only/limited connector 사용 - -Teams channel notification도 같은 structured summary를 재사용할 수 있다. - -## 10. 추가 실사용 패턴 - -### Latency anomaly - -- HTTP 200이지만 p95가 4초 -- Agent는 dependency failure와 application delay를 구분 -- Dynamic Threshold shadow alert의 대표 후보 - -### RBAC dependency failure - -- Blob role assignment 삭제 직후 403/503 -- Agent는 Activity Log와 dependency trace를 연결 -- ticket에는 exact scope와 least-privilege role을 기록 - -### Scheduled operations - -- daily health summary -- certificate/secret expiration -- compliance drift -- failed deployment review - -## 11. 오류 처리와 진실성 - -- 실제로 보내지 않은 email은 `Draft`라고 표시한다. -- GitHub Issue는 실제 URL이 있을 때만 “발행 완료”로 표시한다. -- Microsoft Learn 공식 기능과 이번 lab에서 사용한 HTTP Trigger bridge를 구분한다. -- ServiceNow/PagerDuty/Outlook을 이번 lab에서 실제 연결했다고 주장하지 않는다. -- GIF의 설명 frame과 실제 API evidence frame을 명확히 구분한다. -- S3의 old app 혼동처럼 Agent의 오류도 숨기지 않고 한계로 설명한다. - -## 12. 검증 기준 - -- 주 소개 문서가 제품 정의·가치·동작·안전·connector·도입 절차를 포함 -- Microsoft Learn 공식 이미지 5개 이상과 출처 링크 포함 -- S1 storyboard가 상황→기대→실측→ticket/email 결과 순서 -- S1/S2/S3 GIF에 `SCENARIO`와 `ACTUAL` frame 포함 -- GitHub Issue가 실제 존재하고 URL을 문서에 기록 -- `.eml`, HTML, email screenshot 생성 -- 모든 notification artifact에 secret pattern 0건 -- 실증 보고서는 주 소개 문서를 링크하고 “검증 부록”으로 명시 -- 37개 기존 test와 신규 storyboard/notification test가 통과 - -## 13. 공식 자료 - -- [Overview of Azure SRE Agent](https://learn.microsoft.com/azure/sre-agent/overview) -- [Set up incident response](https://learn.microsoft.com/azure/sre-agent/tutorial-incident-response) -- [Root cause analysis](https://learn.microsoft.com/azure/sre-agent/root-cause-analysis) -- [Connectors](https://learn.microsoft.com/azure/sre-agent/connectors) -- [Managed connectors](https://learn.microsoft.com/azure/sre-agent/managed-connectors) -- [PagerDuty incident indexing](https://learn.microsoft.com/azure/sre-agent/pagerduty-incidents) -- [ServiceNow incident indexing](https://learn.microsoft.com/azure/sre-agent/servicenow-incidents) diff --git a/docs/superpowers/specs/2026-08-13-azure-sre-agent-korean-briefing-redesign.md b/docs/superpowers/specs/2026-08-13-azure-sre-agent-korean-briefing-redesign.md deleted file mode 100644 index 787675e5..00000000 --- a/docs/superpowers/specs/2026-08-13-azure-sre-agent-korean-briefing-redesign.md +++ /dev/null @@ -1,359 +0,0 @@ -# Azure SRE Agent 한국어 고객 브리핑 개편 설계 - -- 작성일: 2026-08-13 -- 대상 독자: 고객·파트너 기술 담당자, SRE, 클라우드 아키텍트 -- 발표자 관점: Microsoft 직원이 제품과 실제 검증 결과를 소개 -- 선택한 시각 방향: 프로세스 다이어그램 + 실제 결과 화면 -- 상태: 승인된 설계 - -## 1. 개편 목적 - -현재 소개 문서는 다음 문제가 있다. - -1. 한국어 문장 안에 영어 명사가 지나치게 많이 섞여 번역문처럼 읽힌다. -2. 설명문이 `-다`체로 작성되어 고객 브리핑 자료보다 내부 보고서에 가깝다. -3. Microsoft Learn의 외부 이미지 URL에 의존해 Markdown 환경에 따라 이미지가 깨진다. -4. Storyboard GIF가 자동으로 넘어가므로 상황과 결과를 충분히 읽기 어렵다. -5. 제품 소개, lab-specific 구현, 실제 검증 결과가 한 문서에서 섞인다. -6. 고객이 “그래서 실제 운영에서 어떻게 쓰는가”를 빠르게 파악하기 어렵다. - -개편 후 문서는 Microsoft 직원이 고객·파트너에게 Azure SRE Agent를 설명하는 기술 브리핑 자료가 된다. 제품 동작은 직접 만든 다이어그램으로 설명하고, 실제 검증은 Agent 결론·티켓·이메일 화면으로 보여준다. - -## 2. 한국어 문체 기준 - -### 2.1 기본 문체 - -- 설명문은 `-합니다`, `-할 수 있습니다`, `-하는 방식입니다`를 사용한다. -- 사용자가 직접 해야 하는 단계는 `-하세요`, `-하지 마세요`, `-해 주세요`처럼 자연스러운 존댓말을 사용한다. -- 법률 또는 계약 문구가 아니라면 딱딱한 `-하십시오`체는 사용하지 않는다. -- 제목은 짧은 명사구 또는 질문형 문장으로 작성한다. -- 한 문장은 한 가지 핵심 내용만 전달한다. -- 문단 첫 문장에서 결론을 말하고, 뒤에서 근거와 예시를 설명한다. -- 과장된 마케팅 표현보다 기능·조건·효과를 구체적으로 설명한다. -- 대명사는 의미가 분명하면 생략한다. -- 수동형보다 능동형을 우선한다. - -### 2.2 용어 기준 - -제품명과 공식 서비스명은 영어를 유지한다. - -- Azure SRE Agent -- Azure Monitor -- Application Insights -- Log Analytics -- Azure Resource Graph -- GitHub -- ServiceNow -- PagerDuty -- Microsoft Teams -- Outlook - -일반 운영 용어는 한국어를 우선한다. - -| 기존 표현 | 개편 표현 | -|---|---| -| alert | 경고 | -| incident | 인시던트 또는 장애 상황 | -| evidence | 근거 | -| root cause | 근본 원인 | -| hypothesis | 가설 | -| response plan | 대응 계획 | -| Review mode | 검토 모드(Review mode) | -| connector | 커넥터 | -| runbook | 운영 절차서(runbook) | -| telemetry | 원격 분석 데이터 | -| deployment history | 배포 이력 | -| affected resource | 영향을 받은 리소스 | -| mitigation | 완화 조치 | - -첫 등장에서는 필요한 경우 한국어와 공식 영문 명칭을 병기하고 이후에는 한 가지 표현을 일관되게 사용한다. - -제품명은 임의로 번역하거나 줄이지 않는다. 예를 들어 Microsoft를 `MS`로, Visual Studio를 `VS`로 줄이지 않는다. - -제품과 기능 용어는 Microsoft Terminology에서 승인된 한국어를 우선 확인한다. - -### 2.3 번역투 제거 - -다음 표현은 사용하지 않는다. - -- 경고가 fire됩니다. -- Agent가 evidence를 collect합니다. -- root-cause hypothesis를 생성합니다. -- structured summary를 communicate합니다. -- context를 연결합니다. - -다음과 같이 바꾼다. - -- 경고가 발생합니다. -- Agent가 관련 근거를 수집합니다. -- 근본 원인에 대한 가설을 세웁니다. -- 조사 결과를 구조화해 티켓과 알림으로 전달합니다. -- 여러 시스템의 정보를 함께 분석합니다. - -딱딱한 한자어와 명사 나열도 줄인다. - -| 피할 표현 | 권장 표현 | -|---|---| -| 장애 분석을 수행합니다 | 장애를 분석합니다 | -| 정보를 제공해 줍니다 | 정보를 보여 줍니다 | -| 대응 절차를 실행합니다 | 대응 절차에 따라 조치합니다 | -| 문제 해결을 위한 작업을 수행합니다 | 문제를 해결합니다 | -| 관련 데이터에 대한 확인이 필요합니다 | 관련 데이터를 확인해야 합니다 | - -### 2.4 Microsoft 고객 브리핑 톤 - -- “이번 문서에서는 …을 소개합니다.” -- “다음과 같은 상황에서 활용할 수 있습니다.” -- “처음 도입할 때는 검토 모드로 시작하는 것을 권장합니다.” -- “이번 실증에서는 …을 확인했습니다.” -- “실제 운영 환경에서는 …을 추가로 검토해야 합니다.” - -Microsoft Learn 한국어 번역문은 제품 용어를 확인하는 보조 자료로만 사용한다. 문장 구조와 어투는 Microsoft Korean Localization Style Guide를 우선 적용한다. - -### 2.5 공식 기준의 우선순위 - -1. Microsoft Korean Localization Style Guide -2. Microsoft Terminology와 UI translation resources -3. Microsoft Writing Style Guide의 brand voice, headings, verbs, numbers -4. Microsoft Trademark and Brand Guidelines -5. 위 자료에 없는 표현은 표준국어대사전 - -## 3. 시각 자료 전략 - -### 3.1 본문에서 제거 - -- 외부 Microsoft Learn 이미지 직접 삽입 -- Storyboard GIF 자동 재생 -- 전체 Azure resource ID -- 내부 thread status JSON -- 같은 내용을 반복하는 decorative image - -Microsoft Learn 이미지는 본문에 삽입하지 않고 관련 섹션의 “참고 자료” 링크로 제공한다. - -### 3.2 새로 만드는 로컬 시각 자료 - -#### A. 제품 동작 프로세스 - -```text -경고 수신 - → 조사 범위 확인 - → 원격 분석·변경 이력·코드에서 근거 수집 - → 가설 수립 및 검증 - → 근본 원인과 조치 방안 제시 - → 사람의 검토와 승인 - → 티켓·이메일·Teams로 공유 - → 해결 경험 축적 -``` - -경로: - -```text -monitor/sre-agent-event-lab/assets/briefing/sre-agent-process.svg -monitor/sre-agent-event-lab/assets/briefing/sre-agent-process.png -``` - -#### B. 대표 시나리오 3단계 패널 - -한 장에서 다음을 보여준다. - -```text -1. 상황 - 주문 API에서 HTTP 500 발생 - 고객 주문 요청 120건 실패 - -2. Azure SRE Agent 조사 - Application Insights request 확인 - Container App revision 변경 확인 - FAILURE_MODE=http500 식별 - -3. 운영 결과 - 근본 원인과 복구 상태 정리 - GitHub Issue #43 생성 - Outlook 이메일 초안 생성 -``` - -경로: - -```text -monitor/sre-agent-event-lab/assets/briefing/s1-three-panel.svg -monitor/sre-agent-event-lab/assets/briefing/s1-three-panel.png -``` - -#### C. 실제 결과 화면 - -- 실제 Agent 결론을 정리한 public-safe 정적 카드 -- 실제 GitHub Issue #43 화면 -- 실제 이메일 초안 화면 - -경로: - -```text -monitor/sre-agent-event-lab/assets/briefing/s1-agent-conclusion.png -monitor/sre-agent-event-lab/assets/notifications/github-issue.png -monitor/sre-agent-event-lab/assets/notifications/s1-email-preview.png -``` - -### 3.3 Storyboard 처리 - -기존 Storyboard GIF와 생성 코드는 검증 부록 또는 lab artifact로 유지할 수 있지만 주 소개 문서에서는 제거한다. 소개 문서는 정적 이미지와 설명을 사용한다. - -## 4. 소개 문서 구조 - -대상 파일: - -```text -monitor/azure-sre-agent.md -``` - -### 4.1 제목과 도입 - -```text -# Azure SRE Agent 소개 - -Azure SRE Agent는 Azure 운영 환경에서 발생한 인시던트를 자동으로 조사하고, -관련 근거를 바탕으로 근본 원인과 조치 방안을 제안하는 AI 기반 운영 도우미입니다. -``` - -첫 화면에는 한 문장 소개, 활용 가치 3개, 제품 동작 프로세스 이미지를 배치한다. - -### 4.2 문서 목차 - -1. Azure SRE Agent란 무엇인가요? -2. 기존 장애 대응과 무엇이 달라지나요? -3. 인시던트가 발생하면 어떻게 조사하나요? -4. 어떤 시스템과 연결할 수 있나요? -5. 권한과 승인 절차는 어떻게 제어하나요? -6. 실제 활용 예시: 주문 API HTTP 500 -7. 조사 결과를 티켓과 이메일로 전달하기 -8. 다른 활용 패턴 -9. Dynamic Thresholds와 함께 사용하기 -10. 도입 전 확인할 사항 -11. 실제 동작 검증 부록 - -## 5. 대표 시나리오 구성 - -### 5.1 상황 - -배포 설정 오류로 주문 API가 HTTP 500을 반환한다. 이로 인해 고객 주문 요청 120건이 실패한다. - -### 5.2 기대하는 조사 - -Agent는 다음 질문에 답해야 한다. - -1. 어떤 서비스와 API가 영향을 받았는가? -2. 장애는 언제 시작됐는가? -3. 외부 종속성 문제인가, 애플리케이션 문제인가? -4. 어떤 배포 또는 설정 변경이 장애와 연결되는가? -5. 현재 서비스는 정상으로 돌아왔는가? -6. 추가로 필요한 후속 조치는 무엇인가? - -### 5.3 실제 확인 결과 - -- Azure Monitor 경고 후 2초 안에 조사 thread 생성 -- Application Insights에서 실패한 요청 120건 확인 -- Container App revision의 `FAILURE_MODE=http500` 확인 -- 정상 revision으로 트래픽이 이동한 사실 확인 -- Agent는 검토 모드에서 리소스를 직접 변경하지 않음 -- GitHub Issue #43 생성 -- Outlook 이메일 초안 생성 - -### 5.4 배치 방식 - -1. 3단계 패널 이미지 -2. Agent 결론 카드 -3. GitHub Issue 화면 -4. 이메일 초안 화면 -5. “이번 실증에서 확인한 점” 요약 - -## 6. 제품 기능과 실증 구분 - -### 제품에서 지원하는 표준 기능 - -- Azure Monitor, PagerDuty, ServiceNow incident platform -- 대응 계획 기반 라우팅 -- Application Insights와 Log Analytics 조사 -- GitHub/Azure DevOps source 연결 -- ServiceNow/PagerDuty incident update -- Teams/Outlook 알림 커넥터 -- 검토 모드와 자율 모드 - -### 이번 lab에서 실제 확인한 기능 - -- Azure Monitor 경고에서 Agent HTTP Trigger 호출 -- Application Insights, Azure Activity Log, source repository 조사 -- 검토 모드에서 근본 원인과 조치 방안 생성 -- GitHub Issue 실제 생성 -- Outlook-compatible 이메일 초안 생성 - -### 이번 lab에서 실제 연결하지 않은 기능 - -- ServiceNow -- PagerDuty -- Outlook OAuth connector -- Microsoft Teams connector -- Native Azure Monitor response plan - -이 구분을 각 섹션에서 명시해 제품 기능과 실증 결과가 혼동되지 않게 한다. - -## 7. 이미지 안정성 - -- 핵심 이미지는 모두 repository 내 상대 경로를 사용한다. -- SVG와 PNG를 함께 제공한다. -- Markdown에서는 PNG를 기본으로 사용한다. -- SVG는 고해상도 또는 편집용 링크로 제공한다. -- 모든 local image path를 자동 검사한다. -- 외부 이미지는 링크로만 제공하고 본문 렌더링에 의존하지 않는다. - -## 8. 검증 기준 - -### 문체 - -- 설명문이 `-합니다/-할 수 있습니다`체로 일관됨 -- 일반 용어의 불필요한 영어 혼용이 없음 -- 고객에게 직접 설명하는 문장 구조를 사용함 -- `alert`, `incident`, `evidence`, `root cause`, `hypothesis`, `mitigation`의 본문 혼용을 제거 - -### 이미지 - -- 본문 외부 이미지 직접 삽입 0건 -- 로컬 이미지 링크 누락 0건 -- 새 PNG 3개 이상 -- 이미지 가로 폭 1200px 이상 -- subscription ID, token, callback URL 노출 0건 - -### 내용 - -- 제품 표준 기능과 lab 실증 결과 구분 -- 프로세스 다이어그램 포함 -- 대표 시나리오 3단계 패널 포함 -- 실제 Agent 결론, Issue #43, 이메일 초안 화면 포함 -- Storyboard GIF가 주 소개 문서에서 제거됨 -- 상세 수치와 원본 근거는 검증 부록으로 연결 - -### 기술 검증 - -- 기존 전체 test 통과 -- 신규 문체 검사 test 통과 -- 신규 image link test 통과 -- GitHub Issue #43 존재 확인 -- live Azure resource 상태 확인 - -## 9. 참고한 문체 자료 - -- [Microsoft Korean Localization Style Guide](https://aka.ms/korean-styleguide) -- [Microsoft Localization Style Guides](https://learn.microsoft.com/globalization/reference/microsoft-style-guides) -- [Microsoft Terminology](https://learn.microsoft.com/globalization/reference/microsoft-terminology) -- [Microsoft language resources](https://learn.microsoft.com/globalization/reference/microsoft-language-resources) -- [Microsoft Writing Style Guide](https://learn.microsoft.com/style-guide/welcome/) -- [Microsoft brand voice: simple and human](https://learn.microsoft.com/style-guide/brand-voice-above-all-simple-human) -- [Microsoft Writing Style Guide: headings](https://learn.microsoft.com/style-guide/scannable-content/headings) -- [Microsoft Writing Style Guide: verbs](https://learn.microsoft.com/style-guide/grammar/verbs) -- [Microsoft Trademark and Brand Guidelines](https://www.microsoft.com/legal/intellectualproperty/trademarks) - -## 10. 참고할 제품 자료 - -- [Azure SRE Agent overview](https://learn.microsoft.com/azure/sre-agent/overview) -- [Incident response](https://learn.microsoft.com/azure/sre-agent/tutorial-incident-response) -- [Root cause analysis](https://learn.microsoft.com/azure/sre-agent/root-cause-analysis) -- [Connectors](https://learn.microsoft.com/azure/sre-agent/connectors) -- [Managed connectors](https://learn.microsoft.com/azure/sre-agent/managed-connectors) diff --git a/docs/superpowers/specs/2026-08-13-azure-sre-agent-official-images-design.md b/docs/superpowers/specs/2026-08-13-azure-sre-agent-official-images-design.md deleted file mode 100644 index 4af9bbbb..00000000 --- a/docs/superpowers/specs/2026-08-13-azure-sre-agent-official-images-design.md +++ /dev/null @@ -1,67 +0,0 @@ -# Azure SRE Agent 공식 이미지 통합 설계 - -## 목적 - -Microsoft Learn의 Azure SRE Agent 공식 이미지 5개를 소개 문서에 추가해 제품의 인시던트 대응, 근본 원인 분석, 추론, 메모리, 자동 학습 방식을 시각적으로 설명합니다. 기존 실증 이미지는 공식 제품 동작이 실제 환경에서 어떻게 나타났는지 보여주는 근거로 유지합니다. - -## 사용할 공식 이미지 - -1. Incident Response Flow -2. Root Cause Analysis Flow -3. Agent Reasoning Loop -4. Memory Unified Search -5. Memory Auto-Learning - -이미지는 Microsoft Learn에 게시된 SVG 원본을 수정하지 않고 repository의 `monitor/sre-agent-event-lab/assets/official/`에 저장합니다. 각 이미지에는 원문 페이지 링크와 Microsoft Learn 출처를 표시합니다. - -## 문서별 배치 - -공식 이미지는 하나의 연속 설명으로 묶지 않습니다. 각 이미지를 기존 문서의 해당 주제 바로 옆에 배치하고, 알맞은 섹션이 없을 때만 새 섹션을 추가합니다. - -### 제품 소개 문서 - -대상: `monitor/azure-sre-agent.md` - -- `Incident Response Flow`: 기존 **인시던트가 발생하면 어떻게 조사하나요?** 섹션에 배치합니다. 기존 한국어 프로세스 다이어그램은 실증 경로 설명으로 이동합니다. -- `Root Cause Analysis Flow`: 조사 단계 설명 뒤에 **근본 원인은 어떻게 찾나요?** 섹션을 추가하고 배치합니다. -- `Agent Reasoning Loop`: 기존 **권한과 승인 절차는 어떻게 제어하나요?** 섹션에 배치합니다. -- `Memory Unified Search`: **과거 경험과 운영 문서는 어떻게 활용하나요?** 섹션을 추가하고 배치합니다. -- `Memory Auto-Learning`: **조사가 끝난 뒤 무엇을 학습하나요?** 섹션을 추가하고 배치합니다. - -각 이미지 아래에는 해당 기능을 설명하는 한국어 문단과 Microsoft Learn 원문 링크를 둡니다. 다섯 이미지를 순서대로 읽지 않아도 각 섹션만으로 내용을 이해할 수 있어야 합니다. - -### 실험실 재현 문서 - -대상: `monitor/sre-agent-event-lab/README.md` - -이 문서는 배포와 재현 절차에 집중하므로 공식 개념 이미지를 본문에 반복하지 않습니다. **공식 자료** 섹션에서 제품 소개 문서와 해당 Microsoft Learn 원문으로 연결합니다. - -### 실제 동작 검증 부록 - -대상: `docs/superpowers/reports/2026-08-12-azure-sre-agent-event-testing-results.md` - -이 문서는 실측 결과와 증거 보존에 집중하므로 공식 개념 이미지를 추가하지 않습니다. 제품 설명이 필요한 독자는 제품 소개 문서로 안내합니다. - -## 기존 이미지 처리 - -- 기존 한국어 프로세스 다이어그램은 삭제하지 않고 **이번 실증에서 사용한 방식** 섹션으로 이동합니다. -- 실제 GitHub Issue, Outlook 메일 초안, Agent 결론 카드는 그대로 유지합니다. -- Storyboard와 GIF는 소개 문서에 다시 추가하지 않습니다. - -## 표시 원칙 - -- 공식 SVG 내부의 영어 텍스트는 수정하지 않습니다. -- 이미지 직후에 자연스러운 한국어 설명을 제공합니다. -- 이미지의 원문 Microsoft Learn 페이지를 함께 연결합니다. -- 공식 제품 동작과 이번 실증에서 확인한 동작을 계속 구분합니다. -- 로컬 파일을 사용해 외부 이미지 로딩 실패를 방지합니다. - -## 검증 기준 - -- 공식 SVG 5개가 모두 repository에 존재하고 정상적으로 렌더링됩니다. -- 소개 문서에서 다섯 이미지를 모두 참조합니다. -- 각 이미지에 한국어 설명과 Microsoft Learn 원문 링크가 있습니다. -- 공식 제품 동작과 실증 경로의 구분이 유지됩니다. -- 기존 전체 테스트와 Bicep 검증이 통과합니다. -- 소개 문서에 외부 이미지 직접 삽입, Storyboard, GIF 참조가 없습니다. -- secret-pattern 검사에서 민감 정보가 발견되지 않습니다. diff --git a/monitor/azure-sre-agent.md b/monitor/azure-sre-agent.md index 6bcc1a9a..41fdb2ff 100644 --- a/monitor/azure-sre-agent.md +++ b/monitor/azure-sre-agent.md @@ -20,7 +20,7 @@ Azure SRE Agent는 단순히 오류 로그를 나열하지 않습니다. 어떤 ## 인시던트가 발생하면 어떻게 조사하나요? -![Azure SRE Agent 공식 인시던트 대응 흐름](sre-agent-event-lab/assets/official/incident-response-flow.svg) +![경고가 발생하면 Azure SRE Agent가 인시던트를 확인하고 로그와 메트릭, 배포 이력을 조사해 근본 원인을 찾은 뒤 해결하거나 담당자에게 넘기는 흐름](sre-agent-event-lab/assets/official/incident-response-flow.svg) > 출처: [인시던트 대응 자동화](https://learn.microsoft.com/azure/sre-agent/incident-response) @@ -56,12 +56,10 @@ Azure SRE Agent는 다음 순서로 인시던트를 조사합니다. ## 근본 원인은 어떻게 찾나요? -![Azure SRE Agent 공식 근본 원인 분석 흐름](sre-agent-event-lab/assets/official/root-cause-analysis.svg) +![증상에서 시작해 로그와 메트릭, 배포 이력, 소스 코드, 과거 경험을 근거로 모으고 가설을 세워 검증한 뒤 근본 원인과 조치 방안을 제시하는 흐름](sre-agent-event-lab/assets/official/root-cause-analysis.svg) > 출처: [근본 원인 분석](https://learn.microsoft.com/azure/sre-agent/root-cause-analysis) -Azure SRE Agent는 오류 로그를 나열하는 데서 멈추지 않습니다. 증상을 기준으로 관련 로그, 메트릭, 배포 이력, 소스 코드와 과거 경험을 모으고 가능한 원인을 가설로 세웁니다. 이후 각 가설을 근거와 비교해 제외하거나 확인하고, 결론을 뒷받침하는 자료와 함께 조치 방안을 제시합니다. - ## 어떤 정보를 조사할 수 있나요? Azure SRE Agent는 관리 ID와 Azure RBAC 권한을 사용해 Azure 리소스를 조사합니다. @@ -79,20 +77,16 @@ Azure 내부 원격 분석 데이터는 기본 도구만으로도 조회할 수 ## 과거 경험과 운영 문서는 어떻게 활용하나요? -![Azure SRE Agent 공식 메모리 통합 검색 구조](sre-agent-event-lab/assets/official/memory-unified-search.svg) +![과거 조사 기록과 사용자가 지정한 내용, 업로드한 운영 문서를 함께 검색해 근거와 출처가 있는 답변을 만드는 구조](sre-agent-event-lab/assets/official/memory-unified-search.svg) > 출처: [메모리와 지식 관리](https://learn.microsoft.com/azure/sre-agent/memory) -Azure SRE Agent는 과거 조사 대화, 사용자가 기억하도록 지정한 내용, 업로드한 운영 문서와 연결된 지식 원본을 함께 검색합니다. 답변에는 근거와 출처를 포함해 어떤 경험과 문서를 사용했는지 확인할 수 있습니다. - ## 조사가 끝난 뒤 무엇을 학습하나요? -![Azure SRE Agent 공식 자동 학습 흐름](sre-agent-event-lab/assets/official/memory-auto-learning.svg) +![조사가 끝나면 증상과 해결 단계, 근본 원인, 피해야 할 접근을 추출해 다음 조사에 사용할 수 있도록 학습하는 흐름](sre-agent-event-lab/assets/official/memory-auto-learning.svg) > 출처: [메모리와 지식 관리](https://learn.microsoft.com/azure/sre-agent/memory) -조사가 완료되면 Azure SRE Agent는 확인한 증상, 효과가 있었던 해결 단계, 근본 원인과 피해야 할 접근을 추출합니다. 이렇게 축적한 내용은 이후 유사한 인시던트를 조사할 때 다시 검색할 수 있습니다. - ## 어떤 시스템과 연결할 수 있나요? ### 인시던트 관리 @@ -105,7 +99,7 @@ Azure SRE Agent는 과거 조사 대화, 사용자가 기억하도록 지정한 - GitHub 저장소, Issue, Pull Request - Azure DevOps 저장소와 Work Item -- Jira와 같은 관리형 커넥터 또는 MCP 기반 티켓 시스템 +- Jira와 같은 관리형 커넥터(미리 보기) 또는 MCP 기반 티켓 시스템 ### 알림과 협업 @@ -126,11 +120,11 @@ Azure SRE Agent는 과거 조사 대화, 사용자가 기억하도록 지정한 ## 권한과 승인 절차는 어떻게 제어하나요? -![Azure SRE Agent 공식 추론과 실행 흐름](sre-agent-event-lab/assets/official/agent-reasoning-flow.svg) +![요청의 의미를 파악하고 맥락 정보를 모아 추론한 뒤 안전한 작업은 실행하고 위험한 작업은 승인을 기다리며 결과를 응답하는 흐름](sre-agent-event-lab/assets/official/agent-reasoning-flow.svg) > 출처: [에이전트 추론과 실행](https://learn.microsoft.com/azure/sre-agent/agent-reasoning) -에이전트는 이 흐름을 따라 판단합니다. 먼저 들어온 요청과 신호의 의미를 파악하고, 관련 리소스 상태와 로그, 과거 조사 기록 같은 맥락 정보를 모읍니다. 이어서 모은 정보를 바탕으로 원인과 다음 행동을 추론한 뒤, 안전하다고 판단한 작업은 바로 실행하고 그렇지 않은 작업은 담당자의 승인을 기다렸다가 결과를 정리해 응답합니다. 요청이 복잡한 경우에는 한 번에 끝나지 않고 이 과정을 여러 차례 반복하며 판단을 다듬어 나갈 수 있습니다. 각 단계에 걸리는 시간은 상황과 작업 범위에 따라 달라지므로 고정된 처리 시간을 보장하지는 않습니다. +요청이 복잡하면 이 과정을 여러 차례 반복하며 판단을 다듬습니다. 각 단계에 걸리는 시간은 상황과 작업 범위에 따라 달라지므로 고정된 처리 시간을 보장하지는 않습니다. Azure SRE Agent는 실행 수준에 따라 권한을 제어합니다. @@ -150,6 +144,36 @@ Azure SRE Agent는 실행 수준에 따라 권한을 제어합니다. - 삭제나 변경 작업은 승인을 받도록 설정합니다. - 자율 모드에서는 일부 승인 절차가 생략될 수 있으므로 별도의 최소 권한 연결을 사용합니다. +## 팀에 맞게 어떻게 확장하나요? + +![에이전트가 사용자 지정 스킬을 불러오고 스킬에 연결된 도구로 외부 API를 호출한 뒤 결과를 받아 조사에 활용하는 흐름](sre-agent-event-lab/assets/official/custom-skill-flow.svg) + +> 출처: [스킬](https://learn.microsoft.com/azure/sre-agent/skills) + +기본 에이전트만으로 부족한 영역은 두 가지 방법으로 보완합니다. + +| 구분 | 사용 방식 | 적합한 용도 | +|---|---|---| +| 스킬 | 관련 상황에서 에이전트가 자동으로 불러옵니다. | 팀 공통 문제 해결 절차와 실행 도구 | +| 사용자 지정 에이전트 | 담당자가 필요할 때 직접 호출합니다. | 데이터베이스, 보안처럼 특정 영역 전문 조사 | + +스킬에는 절차를 담은 문서와 함께 Azure CLI, Kusto 쿼리, Python 스크립트 같은 도구를 연결할 수 있습니다. 따라서 방법을 설명하는 데서 그치지 않고 필요한 조회를 직접 수행합니다. 한 대화에서 동시에 활성화되는 스킬은 **최대 5개**이며, 이 수를 넘으면 오래된 스킬부터 해제되었다가 필요할 때 다시 불러옵니다. + +사용자 지정 에이전트는 각자 도구와 커넥터, 사용할 스킬을 따로 지정합니다. 조사 과정에서 다른 전문 에이전트로 작업을 넘기도록 구성할 수도 있어, 인시던트 분류와 상세 조사, 결과 전달을 단계별로 나눌 수 있습니다. + +## 인시던트를 담당자에게 어떻게 배분하나요? + +대응 계획은 들어온 인시던트를 조건에 따라 적절한 사용자 지정 에이전트로 전달합니다. 다음 조건을 조합할 수 있습니다. + +- 심각도 또는 우선순위(여러 값 동시 선택 가능) +- 영향을 받은 서비스 +- 인시던트 유형 +- 제목에 포함된 키워드 + +대응 계획마다 실행 수준을 따로 지정할 수 있어, 중요한 장애는 자동 조치를 허용하고 낮은 심각도는 검토 모드로 운영하는 방식이 가능합니다. 계획은 삭제하지 않고 사용 중지할 수 있으므로 정기 점검 기간에도 설정을 유지할 수 있습니다. + +인시던트 플랫폼을 처음 연결하면 빠른 시작 대응 계획이 자동으로 만들어집니다. 사용자 정의 대응 계획을 만든 뒤에는 이 계획을 삭제해야 인시던트가 잘못 전달되거나 두 번 처리되지 않습니다. + ## 제품에서 기본으로 지원하는 방식 제품의 표준 Azure Monitor 연계는 **Azure Monitor 인시던트 플랫폼 → 대응 계획 → Azure SRE Agent** 순서로 동작합니다. 이 방식에서는 Logic App과 같은 중간 연결이 필요하지 않습니다. @@ -170,7 +194,7 @@ Azure SRE Agent는 다음 기능을 제품에서 기본으로 지원합니다. - [인시던트 대응 설정](https://learn.microsoft.com/azure/sre-agent/tutorial-incident-response) - [근본 원인 분석](https://learn.microsoft.com/azure/sre-agent/root-cause-analysis) - [커넥터](https://learn.microsoft.com/azure/sre-agent/connectors) -- [관리형 커넥터](https://learn.microsoft.com/azure/sre-agent/managed-connectors) +- [관리형 커넥터(미리 보기)](https://learn.microsoft.com/azure/sre-agent/managed-connectors) ## 이번 실증에서 사용한 방식 @@ -290,7 +314,7 @@ Issue에는 다음 내용을 포함했습니다. | 주문 API 지연 | 성공한 요청의 응답 시간, 외부 종속성, 지연 설정 | `ORDER_DELAY_MS=4000`을 확인했습니다. | | Blob 권한 오류 | 역할 삭제 이력, Blob 403, API 503 | 역할 삭제를 근본 원인으로 확인했습니다. 복구 확인 대상은 한 차례 잘못 선택해 한계로 기록했습니다. | -상세 수치, 시간 순서, 평가 기준은 [실제 동작 검증 부록](../docs/superpowers/reports/2026-08-12-azure-sre-agent-event-testing-results.md)에서 확인할 수 있습니다. +상세 수치, 시간 순서, 평가 기준은 [실제 동작 검증 결과](sre-agent-event-lab/validation-results.md)에서 확인할 수 있습니다. ## Dynamic Thresholds와 함께 사용할 수 있나요? @@ -303,7 +327,80 @@ Issue에는 다음 내용을 포함했습니다. 처음에는 기존 고정 임계값을 유지하고, Dynamic Thresholds를 별도의 관찰용 경고로 추가하는 방식을 권장합니다. 충분한 학습 기간을 거친 뒤 오탐과 누락을 비교해 실제 대응 흐름에 연결합니다. -자세한 내용은 [Dynamic Thresholds와 Azure SRE Agent 연계 설계](../docs/superpowers/specs/2026-08-12-azure-monitor-dynamic-thresholds-sre-integration-design.md)를 참고하세요. +자세한 내용은 [Dynamic Thresholds 연계 가이드](sre-agent-event-lab/dynamic-thresholds.md)를 참고하세요. + +## 도입 전에 확인해야 할 사전 조건 + +Azure SRE Agent를 만들기 전에 다음 조건을 먼저 확인하세요. + +- 구독이 Azure SRE Agent 사용 대상으로 등록되어 있어야 합니다. 등록되지 않으면 에이전트를 만들 때 리전 목록이 비어 있습니다. +- 에이전트를 만드는 담당자에게 구독 Contributor 권한이 필요합니다. 리소스 공급자를 등록하고 리소스를 만들기 위한 권한입니다. +- 역할 할당을 직접 만들려면 Owner 또는 User Access Administrator 권한이 추가로 필요합니다. +- 사내 네트워크에서 에이전트 포털 도메인을 차단하지 않아야 합니다. 보안 프록시 환경에서는 사전에 허용 목록을 확인하세요. + +에이전트가 조사에 사용하는 권한은 담당자의 권한과 다릅니다. 에이전트의 관리 ID는 기본적으로 읽기 권한만 가지며, 변경 작업을 하려면 필요한 범위에 권한을 따로 부여해야 합니다. + +에이전트는 한 리전에 배포합니다. Korea Central을 포함해 여러 리전을 지원하지만, **만든 뒤에는 리전은 변경할 수 없습니다.** 다른 리전에서 운영하려면 해당 리전에 별도 에이전트를 만듭니다. 에이전트가 배포된 리전과 무관하게 다른 리전의 리소스를 조사할 수 있습니다. + +AI 모델 공급자도 함께 확인하세요. 조사 대화와 요약 결과는 에이전트를 배포한 리전에 저장되지만, 모델 추론은 공급자에 따라 다른 국가에서 처리될 수 있습니다. 지역별 기본 공급자가 다르므로, 데이터 처리 위치에 대한 요건이 있는 조직은 도입 검토 단계에서 현재 설정된 공급자와 처리 범위를 확인하세요. + +## 비용은 어떻게 발생하나요? + +Azure SRE Agent는 Azure Agent Unit(AAU)을 기준으로 과금합니다. 비용은 두 가지로 나뉩니다. + +| 구분 | 발생 방식 | +|---|---| +| 상시 비용 | 에이전트를 만든 시점부터 삭제할 때까지 시간 단위로 발생합니다. | +| 활성 비용 | 조사, 채팅, 예약 작업처럼 모델을 사용하는 작업에서 토큰 사용량에 따라 발생합니다. | + +비용을 관리할 때는 다음을 기억하세요. + +- 에이전트를 중지해도 상시 비용은 계속 발생합니다. 완전히 멈추려면 삭제해야 합니다. +- 월별 AAU 한도를 설정할 수 있습니다. 이 한도는 활성 비용에만 적용되며, 한도에 도달하면 다음 달까지 조사와 채팅을 사용할 수 없습니다. 상시 비용은 한도와 무관하게 계속 발생합니다. +- 사용하는 모델에 따라 단가가 크게 달라집니다. +- 스레드 유형별 사용량을 확인하고 내보낼 수 있어 팀별 비용 배분에 활용할 수 있습니다. +- Azure Monitor 로그 조회처럼 연결된 서비스의 비용은 별도로 발생합니다. + +## 보안과 데이터는 어떻게 보호되나요? + +Azure SRE Agent는 조사 도구를 격리된 샌드박스에서 실행하고, 자격 증명을 대화 맥락에 남기지 않습니다. + +- 도구 실행 환경은 에이전트별로 분리되며, 호출마다 새 프로세스를 사용합니다. +- 자격 증명은 호출 시점에 짧은 수명 토큰으로 발급하고 재사용하지 않습니다. +- 조회한 원시 로그는 별도로 저장하지 않고, 조사 대화와 요약된 결과만 보존합니다. +- 관리 ID 권한이 부족하면 담당자 승인 후 사용자 자격 증명으로 실행하며, 이후 자격 증명을 캐시하지 않습니다. +- Azure CLI 기반 작업에는 안전 장치가 있어 삭제 계열 명령과 키 자격 증명 모음 접근은 차단됩니다. +- 읽기 전용으로 잠근 리소스는 변경하지 않습니다. + +Log Analytics 작업 영역이나 AKS를 비공개 네트워크로만 노출한 환경이라면 에이전트의 네트워크 모드를 VNet 통합으로 설정해 사설 엔드포인트에 접근할 수 있습니다. 이 기능은 현재 미리 보기입니다. 공개 엔드포인트만 사용하는 환경에서는 별도 VNet 구성 없이도 조사할 수 있습니다. + +## 인시던트 대응 외에 무엇을 자동화할 수 있나요? + +### 예약 작업 + +일정에 따라 에이전트가 스스로 점검을 수행하도록 예약할 수 있습니다. 작업 내용은 자연어로 작성하며, 실행할 때마다 조사 대화와 요약 결과가 남습니다. 매일 서비스 상태 점검, 비용 이상 탐지, 보안 구성 점검, 배포 후 확인처럼 경고가 발생하기 전에 문제를 찾는 용도로 사용합니다. + +### 심층 조사 + +영향 범위가 크거나 원인이 여러 개일 수 있는 상황에서는 심층 조사를 사용할 수 있습니다. 가설을 여러 개 세우고 검증 과정을 단계별로 보여주며, 제외한 가설도 함께 정리합니다. 일반 조사보다 토큰 사용량이 많으므로 중요한 인시던트에 선택적으로 사용하는 편이 좋습니다. + +### 팀 지식 온보딩 + +에이전트에 팀 구조, 서비스 아키텍처, 문제 해결 절차를 미리 학습시킬 수 있습니다. 대화형 온보딩을 진행하거나 운영 문서를 업로드하면 이후 조사에서 해당 내용을 근거로 활용합니다. + +### Agent Hooks + +Agent Hooks를 사용하면 에이전트가 결과를 반환하기 직전이나 도구 실행 직후에 자체 검증을 추가할 수 있습니다. 위험한 명령을 차단하거나, 결론에 근거가 충분한지 확인해 다시 조사하도록 만들 수 있습니다. 실행 수준이 *무엇을 할 수 있는지*를 정한다면, Agent Hooks는 *어떻게 수행해야 하는지*를 정합니다. + +### 도구 용량 관리 + +하나의 에이전트가 사용할 수 있는 도구는 기본 도구와 MCP 도구를 합쳐 최대 **80개**입니다. 외부 관찰 도구와 사내 시스템을 폭넓게 연결할 계획이라면 도구 수를 미리 설계하세요. + +## 에이전트가 한 일을 어떻게 감사하나요? + +에이전트의 활동은 조직이 소유한 Application Insights의 `customEvents` 테이블에 기록됩니다. 모델 호출, 도구 실행, Azure CLI 명령, 승인 결정, 인시던트 처리 결과를 각각 확인할 수 있어 KQL로 조회하고 보고서로 활용할 수 있습니다. + +또한 인시던트 지표 화면에서 처리한 인시던트 수, 에이전트가 완화한 비율, 담당자가 처리한 비율, 절감한 시간, 근본 원인 분포를 확인할 수 있습니다. 도입 효과를 정량적으로 설명해야 할 때 활용하기 좋습니다. ## 도입 전에 무엇을 확인해야 하나요? @@ -317,7 +414,7 @@ Issue에는 다음 내용을 포함했습니다. - [ ] Azure Monitor, PagerDuty, ServiceNow 중 사용할 인시던트 플랫폼을 정하세요. - [ ] 심각도, 서비스, 제목 기준으로 대응 계획을 만드세요. -- [ ] 빠른 시작 대응 계획과 사용자 정의 대응 계획이 중복되지 않는지 확인하세요. +- [ ] 사용자 정의 대응 계획을 만들었다면 빠른 시작 대응 계획을 삭제하세요. - [ ] 처음에는 검토 모드로 시작하세요. ### 권한과 안전 @@ -349,22 +446,38 @@ Issue에는 다음 내용을 포함했습니다. ## 참고 자료 -### 한국어 문체와 용어 - -- [Microsoft Korean Localization Style Guide](https://aka.ms/korean-styleguide) -- [Microsoft Terminology](https://learn.microsoft.com/globalization/reference/microsoft-terminology) -- [Microsoft language resources](https://learn.microsoft.com/globalization/reference/microsoft-language-resources) -- [Microsoft Writing Style Guide](https://learn.microsoft.com/style-guide/welcome/) - -### Azure SRE Agent +### 제품 개요와 조사 방식 - [Azure SRE Agent 개요](https://learn.microsoft.com/azure/sre-agent/overview) - [인시던트 대응 설정](https://learn.microsoft.com/azure/sre-agent/tutorial-incident-response) +- [인시던트 대응 계획](https://learn.microsoft.com/azure/sre-agent/incident-response-plans) - [근본 원인 분석](https://learn.microsoft.com/azure/sre-agent/root-cause-analysis) +- [심층 조사](https://learn.microsoft.com/azure/sre-agent/deep-investigation) +- [팀 온보딩](https://learn.microsoft.com/azure/sre-agent/team-onboard) +- [사용자 지정 에이전트](https://learn.microsoft.com/azure/sre-agent/sub-agents) +- [스킬](https://learn.microsoft.com/azure/sre-agent/skills) + +### 도입과 운영 + +- [에이전트 만들기와 설정](https://learn.microsoft.com/azure/sre-agent/create-and-set-up) +- [지원 리전](https://learn.microsoft.com/azure/sre-agent/supported-regions) +- [가격과 청구](https://learn.microsoft.com/azure/sre-agent/pricing-billing) +- [예약 작업](https://learn.microsoft.com/azure/sre-agent/scheduled-tasks) +- [작업 감사](https://learn.microsoft.com/azure/sre-agent/audit-agent-actions) +- [인시던트 가치 추적](https://learn.microsoft.com/azure/sre-agent/track-incident-value) + +### 보안과 확장 + +- [보안 개요](https://learn.microsoft.com/azure/sre-agent/security-overview) +- [권한](https://learn.microsoft.com/azure/sre-agent/permissions) +- [네트워크 통합](https://learn.microsoft.com/azure/sre-agent/network-integration) +- [데이터 보존과 개인 정보](https://learn.microsoft.com/azure/sre-agent/data-privacy) +- [Agent Hooks](https://learn.microsoft.com/azure/sre-agent/agent-hooks) - [커넥터](https://learn.microsoft.com/azure/sre-agent/connectors) -- [관리형 커넥터](https://learn.microsoft.com/azure/sre-agent/managed-connectors) +- [관리형 커넥터(미리 보기)](https://learn.microsoft.com/azure/sre-agent/managed-connectors) +- [MCP 커넥터](https://learn.microsoft.com/azure/sre-agent/mcp-connectors) ### 실증 자료 -- [실제 동작 검증 부록](../docs/superpowers/reports/2026-08-12-azure-sre-agent-event-testing-results.md) +- [실제 동작 검증 결과](sre-agent-event-lab/validation-results.md) - [실험 환경과 재현 방법](sre-agent-event-lab/README.md) diff --git a/monitor/sre-agent-event-lab/README.md b/monitor/sre-agent-event-lab/README.md index 4a46ac12..9957ebdd 100644 --- a/monitor/sre-agent-event-lab/README.md +++ b/monitor/sre-agent-event-lab/README.md @@ -145,7 +145,7 @@ monitor/sre-agent-event-lab/app/.venv/bin/python \ monitor/sre-agent-event-lab/scripts/generate_notifications.py \ --timeline monitor/sre-agent-event-lab/evidence/s1-20260812T080606Z/normalized-timeline.json \ --output-dir monitor/sre-agent-event-lab/assets/notifications \ - --report-url "docs/superpowers/reports/2026-08-12-azure-sre-agent-event-testing-results.md (available after feature branch merge)" \ + --report-url "monitor/sre-agent-event-lab/validation-results.md" \ --issue-url https://github.com/hellices/devguidesample/issues/43 ``` diff --git a/monitor/sre-agent-event-lab/assets/notifications/s1-email-preview.png b/monitor/sre-agent-event-lab/assets/notifications/s1-email-preview.png index 5099f013..e58d1d1b 100644 Binary files a/monitor/sre-agent-event-lab/assets/notifications/s1-email-preview.png and b/monitor/sre-agent-event-lab/assets/notifications/s1-email-preview.png differ diff --git a/monitor/sre-agent-event-lab/assets/notifications/s1-github-issue.md b/monitor/sre-agent-event-lab/assets/notifications/s1-github-issue.md index 862b50fb..c6a653ab 100644 --- a/monitor/sre-agent-event-lab/assets/notifications/s1-github-issue.md +++ b/monitor/sre-agent-event-lab/assets/notifications/s1-github-issue.md @@ -43,5 +43,5 @@ Resolved. A succeeding revision uses `FAILURE_MODE=none`, receives traffic, and ## Tracking - Agent thread ID: `6dd0e640-d969-46cb-a976-7c81b66fcadc` -- Detailed validation appendix: docs/superpowers/reports/2026-08-12-azure-sre-agent-event-testing-results.md (available after feature branch merge) +- Detailed validation appendix: monitor/sre-agent-event-lab/validation-results.md - Generated from actual Azure SRE Agent evidence; no resource change was executed by the Agent. diff --git a/monitor/sre-agent-event-lab/assets/notifications/s1-incident-summary.eml b/monitor/sre-agent-event-lab/assets/notifications/s1-incident-summary.eml index 76ccd1f1..c21166c8 100644 --- a/monitor/sre-agent-event-lab/assets/notifications/s1-incident-summary.eml +++ b/monitor/sre-agent-event-lab/assets/notifications/s1-incident-summary.eml @@ -4,9 +4,9 @@ Subject: [Resolved][SRE-LAB] Order API HTTP 500 incident X-SRE-Agent-Draft: true MIME-Version: 1.0 Content-Type: multipart/alternative; - boundary="===============6402554201647369171==" + boundary="===============4373938818987806184==" ---===============6402554201647369171== +--===============4373938818987806184== Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable @@ -24,10 +24,10 @@ Current status: Resolved by a healthy revision with FAILURE_MODE=3Dnone. Ticket: https://github.com/hellices/devguidesample/issues/43 -Detailed validation appendix: docs/superpowers/reports/2026-08-12-azure-sre-a= -gent-event-testing-results.md (available after feature branch merge) +Detailed validation appendix: monitor/sre-agent-event-lab/validation-results.= +md ---===============6402554201647369171== +--===============4373938818987806184== Content-Type: text/html; charset="utf-8" Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 @@ -94,8 +94,7 @@ ps://github.com/hellices/devguidesample/issues/43

.
  • Retain this investigation in the Agent knowledge base.
    • -

    docs/superpowers/reports/2026-08-12-azure-sre-agent-event-test= -ing-results.md (available after feature branch merge)

    +

    monitor/sre-agent-event-lab/validation-results.md