operations daily report

Daily Report 운영

기준일: 2026-06-09
대상: Factory Daily Report, Cloud Infra Daily Report

운영 원칙

• 보고서는 S3 processed 집계와 Bedrock 문장을 결합한 운영자 검토용 초안이다.
• 장애 원인, 배포 변경, 자동 조치의 정본으로 사용하지 않는다.
• Dashboard는 보고서를 생성하지 않고 S3의 report.md를 읽는다.
• reporting stack을 삭제해도 기존 S3 processed 입력과 report 산출물은 보존된다.
• 기본 Region은 ap-south-1, 운영 기준 timezone은 Asia/Seoul이다.

Build

선행 조건:

• Foundation의 aegis-bucket-data가 존재해야 한다.
• AWS CLI/MFA와 Terraform backend 접근이 가능해야 한다.
• 선택한 Bedrock model이 ap-south-1에서 호출 가능해야 한다.

scripts/build/build-reporting.sh [MFA_OTP]

스크립트는 infra/reporting/terraform.tfvars가 없으면 terraform.tfvars.example을 복사하고 init, validate, plan, apply를 실행한다. 현재 example은 Region과 bucket만 지정하므로 model은 Terraform 기본값인 Sonnet을 쓴다.

생성 대상:

• EventBridge Scheduler 1개
• Step Functions Standard state machine 1개
• Reporting Lambda 7개
• Lambda/Step Functions log group
• Scheduler, Step Functions, Lambda IAM role/policy

과거 build 문서의 “Lambda 4개” 표기는 Cloud Infra branch 추가 전 기준이다.

Destroy

scripts/destroy/destroy-reporting.sh [MFA_OTP]

destroy 스크립트는 state 접근 가능 여부와 resource 존재 여부를 먼저 검사한다. 삭제되는 것은 Scheduler, Step Functions, 7개 Lambda, 관련 IAM/CloudWatch 리소스다.

보존:

s3://aegis-bucket-data/processed/
s3://aegis-bucket-data/reports/daily/

2026-05-28 실검증 후 stack은 비용 방지를 위해 destroy한 이력이 있다. 현재 배포 여부는 문서가 아니라 Terraform state와 AWS resource를 조회해 판단한다.

Bedrock Model Access

현재 코드와 Terraform 기본 model:

anthropic.claude-3-sonnet-20240229-v1:0

초기 ADR/계획에는 Haiku가 남아 있으나 현재 기본값이 아니다. 2026-05-28 실검증 metadata도 Sonnet이었다.

배포 전 확인:

1. ap-south-1의 Bedrock model catalog/access에서 대상 model 사용 가능 여부를 확인한다.
2. terraform plan에서 bedrock_model_id와 IAM model ARN을 확인한다.
3. 배포 후 Lambda의 BEDROCK_MODEL_ID를 확인한다.
4. 첫 성공 후 generation-metadata.json.model_id를 확인한다.

저장소에는 model을 바꾸는 checked-in 배포 override가 없다. 로컬 terraform.tfvars, TF_VAR_bedrock_model_id, CLI -var는 운영 환경에만 존재할 수 있으므로 실제 배포값 확인이 필요하다.

Bedrock AccessDenied이면 다음을 분리해 확인한다.

• account/region에서 model 호출 가능 여부
• Lambda role의 bedrock:InvokeModel
• IAM resource ARN의 model ID와 Lambda 환경변수의 model ID 일치 여부

수동 실행

State machine ARN은 Terraform output으로 가져온다.

cd infra/reporting
terraform output -raw state_machine_arn

특정 날짜와 Factory 1개만 실행하는 예:

aws stepfunctions start-execution \
  --region ap-south-1 \
  --state-machine-arn "$(terraform output -raw state_machine_arn)" \
  --name "manual-daily-report-$(date -u +%Y%m%dT%H%M%SZ)" \
  --input '{
    "report_date": "2026-05-27",
    "timezone": "Asia/Seoul",
    "factories": ["factory-b"],
    "report_type": "daily_factory_operations_draft"
  }'

주의: PrepareReportWindow는 전달된 Factory 목록과 무관하게 cloud-infra target도 추가한다. 따라서 위 실행은 factory-b와 cloud-infra 두 보고서를 처리한다. Cloud Infra 입력이 없는 날짜라도 24개 empty hourly summary가 생성될 수 있다.

기본 Factory 3개를 실행하려면 factories를 생략하거나 세 ID를 모두 전달한다. report_date를 생략하면 실행 시점 KST 기준 전일이 선택된다.

실행 확인:

aws stepfunctions describe-execution \
  --region ap-south-1 \
  --execution-arn EXECUTION_ARN

KST와 UTC

보고서 날짜는 KST, S3 partition은 UTC다.

report_date=2026-05-27
KST window: 2026-05-27T00:00:00+09:00~2026-05-27T23:59:59+09:00
UTC window: 2026-05-26T15:00:00Z~2026-05-27T14:59:59Z

날짜 장애를 조사할 때 KST 날짜의 yyyy/mm/dd prefix 하나만 확인하면 안 된다. 앞날 15:00 UTC부터 당일 14:59 UTC까지 걸치는 partition을 확인한다.

S3 검증

Factory:

aws s3 ls \
  s3://aegis-bucket-data/reports/daily/yyyy=2026/mm=05/dd=27/factory-b/ \
  --recursive \
  --region ap-south-1

필수 파일:

intermediate/hourly/hh=00.json ... hh=23.json
factory-daily-summary.json
report-context.json
report.md
generation-metadata.json

Cloud Infra:

aws s3 ls \
  s3://aegis-bucket-data/reports/daily/yyyy=2026/mm=05/dd=27/cloud-infra/ \
  --recursive \
  --region ap-south-1

필수 파일은 동일하되 daily summary가 cloud-infra-daily-summary.json이다.

본문과 metadata 확인:

aws s3 cp \
  s3://aegis-bucket-data/reports/daily/yyyy=2026/mm=05/dd=27/factory-b/generation-metadata.json \
  -

aws s3 cp \
  s3://aegis-bucket-data/reports/daily/yyyy=2026/mm=05/dd=27/factory-b/report.md \
  -

검증 항목:

• context의 KST/UTC window가 의도한 날짜인지
• Factory와 Cloud Infra output prefix가 섞이지 않았는지
• hourly file이 00~23까지 존재하는지
• metadata의 model_id, context/report key가 실제 object와 일치하는지
• report에 날짜/target과 핵심 검증 수치가 포함됐는지
• processed 기반, raw 미사용, LLM 초안 검토 필요 문구가 있는지

report-context.json은 있는데 report.md가 없으면 Bedrock 호출 또는 invariant validation 실패 가능성이 높다.

Dashboard 조회

Dashboard Backend API:

GET /reports
GET /reports/{report_date}/{factory_id}

Backend는 reports/daily/를 read-only로 List/Get한다. 생성 endpoint는 없다.

• Factory 보고서: 사용자의 factory 접근 권한 적용
• cloud-infra: can_view_system 권한 적용
• object 없음: HTTP 404
• S3 timeout/오류: HTTP 504

Dashboard Web /reports에서 Factory/Cloud Infra와 날짜를 선택해 Markdown을 조회한다. Cloud Infra selector는 system view 권한이 있는 사용자에게만 보인다.

내보내기:

• Word: 브라우저가 Markdown을 실제 .docx OOXML로 변환
• PDF: 브라우저 print dialog 사용

두 형식 모두 backend나 reporting pipeline에서 생성하지 않으며 S3에도 자동 저장되지 않는다.

Backfill

1. Inventory부터 실행

python apps/daily-report-generator/scripts/inventory_daily_report_backfill.py \
  --bucket aegis-bucket-data \
  --targets factory-a,factory-b,factory-c,cloud-infra \
  --date-from 2026-05-01 \
  --date-to 2026-05-31

기본 출력은 /tmp/aegis-reporting-backfill/inventory.json과 inventory.md다. 날짜별 object 수, partial day, 기존 report/metadata, 예상 Bedrock 호출 수를 확인한다.

2. Dry-run과 호출 상한

python apps/daily-report-generator/scripts/backfill_daily_reports.py \
  --target-dates factory-a:2026-05-27,cloud-infra:2026-05-27 \
  --only-missing \
  --max-bedrock-calls 2 \
  --dry-run

3. 실제 실행

--dry-run을 제거한다. 기존 산출물을 덮어써야 할 때만 --force를 사용한다. Factory와 Cloud Infra를 모두 지원하는 경로는 backfill_daily_reports.py다.

배포 Lambda 직접 호출 스크립트 invoke_reporting_lambdas_backfill.py는 Factory만 지원한다. 또한 이 경로는 Step Functions orchestration을 거치지 않는다.

비용

실측 기반 기준은 2026-05-28 Factory B 보고서 1개다.

항목	1개 Factory 보고서 추정
Lambda	약 0.044 USD
S3 GET/LIST/PUT	약 0.026~0.027 USD
Step Functions	약 0.003~0.004 USD
Bedrock Sonnet	약 0.05~0.09 USD
Logs/Scheduler	0.001 USD 미만
합계	약 0.12~0.18 USD

3개 Factory를 30일 생성하면 당시 가정으로 약 10.8~16.2 USD/month다. 이 수치는 Cloud Infra branch 추가 비용을 포함한 완전한 현재 월간 실측이 아니다.

비용의 주요 변수:

1. Bedrock output token
2. Lambda billed duration
3. 작은 S3 object의 GetObject 수
4. Step Functions transition

현재 metadata에는 token usage가 없고 S3 reader도 순차 요청이다. 비용을 정밀하게 관리하려면 Cost Explorer/CloudWatch와 함께 input object 수와 token usage를 별도로 수집해야 한다. AWS 가격은 변할 수 있으므로 운영 시점의 공식 가격을 다시 적용한다.

실패 대응

증상	우선 확인
execution이 시작되지 않음	Scheduler enabled, target ARN, scheduler role states:StartExecution
전체 execution 실패	Step Functions failed state와 해당 Lambda log
특정 target에서 실패	SelectReportTarget 이후 Factory/Cloud Infra branch 확인
hourly summary가 empty	KST/UTC 범위, 해당 processed prefix, timestamp schema
처리 시간이 수분 단위	state_snapshot object 수, 순차 S3 GetObject, Lambda timeout
S3 AccessDenied	bucket List, processed/report Get, reports/daily Put policy
Bedrock AccessDenied	Region/model access, IAM model ARN, BEDROCK_MODEL_ID
context는 있고 report 없음	Bedrock 오류 또는 invariant validation 실패
Dashboard 404	정확한 report key와 선택 날짜/target 확인
Dashboard 504	ECS task role, S3 timeout/network, bucket/region 설정
Cloud Infra 보고서가 안 보임	can_view_system, cloud-infra/report.md 존재 여부
DOCX 실패	브라우저 console, dynamic docx chunk 로드, Markdown parser

현재 state machine에는 명시적 retry/catch가 없다. 일시적 Bedrock throttling이나 S3 오류도 자동 복구되지 않을 수 있으므로 원인 해소 후 새 execution 또는 backfill로 재실행한다. 같은 execution name은 재사용할 수 없다.

배포 후 점검표

• Terraform output에서 state machine, scheduler, Lambda 7개 확인
• Scheduler가 cron(30 15 * * ? *)와 UTC timezone인지 확인
• Factory 3개와 Cloud Infra branch가 실행되는지 확인
• Factory/Cloud Infra S3 key 계약 확인
• generation-metadata.json.model_id 확인
• Dashboard Factory 권한과 system 권한 분리 확인
• DOCX가 브라우저 생성이고 PDF가 print 경로인지 확인
• 보고서가 운영자 검토용 초안임을 본문에서 확인

관련 문서

• Reporting Pipeline
• Daily Report Generator
• Dashboard Backend
• Dashboard Web
• 클라우드 스토리지