architecture reporting pipeline

Daily Reporting Pipeline 아키텍처

기준일: 2026-06-09
구현 기준: infra/reporting/, apps/daily-report-generator/

책임 경계

Daily Reporting Pipeline은 전일의 S3 processed 데이터를 집계해 Factory 보고서와 Cloud Infra 보고서를 생성하고 S3에 저장한다. Dashboard는 생성 과정에 참여하지 않고 저장된 report.md를 읽어 표시한다.

단계	책임 주체
실행 예약	EventBridge Scheduler
실행 계획과 병렬 제어	Step Functions Standard Workflow
시간별/일별 집계	Reporting Lambda
자연어 초안 생성	Amazon Bedrock
수치 표 렌더링과 검증	Reporting Lambda
정본 데이터 저장	기존 S3 data bucket
보고서 조회	Dashboard Backend
화면 렌더링과 DOCX/PDF 내보내기	Dashboard Web 브라우저

LLM이 만든 문장은 장애 원인이나 운영 판단의 정본이 아니다. 보고서는 report-context.json을 근거로 작성되는 운영자 검토용 초안이며, 원본 관측값과 집계 결과가 운영 근거다.

현재 구성과 검증 범위

Terraform local.lambda_functions와 Step Functions 정의 기준 Lambda는 총 7개다. 초기 Factory 전용 설계의 4개에서 Cloud Infra 전용 3개가 추가되었다.

운영 검증 문서는 2026-05-28 factory-b 수동 실행 성공과 S3 산출물 확인을 기준으로 한다. factory-a/c와 Cloud Infra branch, 통합본 기준 전체 scheduler smoke는 별도 검증 대상으로 둔다.

Lambda	대상	역할
PrepareReportWindow	공통	KST 기준일, UTC 조회 범위, 24개 hour item, report target 생성
AggregateFactoryHour	Factory	공장 1개, 시간 1개의 processed 데이터 집계
MergeFactoryDaily	Factory	24개 시간별 summary 병합, context 생성
GenerateFactoryReport	Factory	Bedrock 호출, 표 삽입, 불변값 검증, Markdown 저장
AggregateCloudInfraHour	Cloud Infra	fast/slow snapshot 시간별 집계
MergeCloudInfraDaily	Cloud Infra	24개 summary 병합, context 생성
GenerateCloudInfraReport	Cloud Infra	Bedrock 호출, 표 삽입, 불변값 검증, Markdown 저장

State machine 이름은 AEGIS-DailyFactoryReportStateMachine이지만 현재는 Factory와 Cloud Infra 보고서를 모두 처리한다.

전체 흐름

EventBridge Scheduler
  cron(30 15 * * ? *) = 매일 00:30 KST
  -> Step Functions Standard
      -> PrepareReportWindow
      -> ReportTargetMap (MaxConcurrency=4)
          -> Choice: SelectReportTarget
              -> factory branch
                  -> FactoryHourMap, 24시간 (MaxConcurrency=6)
                      -> AggregateFactoryHour
                  -> MergeFactoryDaily
                  -> GenerateFactoryReport
              -> cloud_infra branch
                  -> CloudInfraHourMap, 24시간 (MaxConcurrency=6)
                      -> AggregateCloudInfraHour
                  -> MergeCloudInfraDaily
                  -> GenerateCloudInfraReport

ReportTargetMap의 논리 branch는 factory, cloud_infra 2개다. 기본 실행 target은 factory-a, factory-b, factory-c, cloud-infra 4개이며 Factory branch는 공통 Lambda를 입력 파라미터만 바꾸어 3회 실행한다.

재시도나 실패가 없을 때 기본 일일 호출량은 다음과 같다.

구분	호출 수
Prepare	1
Factory hourly aggregate	3 x 24 = 72
Factory daily merge/generate	3 + 3
Cloud Infra hourly aggregate	24
Cloud Infra daily merge/generate	1 + 1
합계	105

현재 Step Functions 정의에는 명시적 Retry/Catch가 없다. 한 target branch의 처리되지 않은 오류는 Map과 전체 execution 실패로 전파된다.

Scheduler와 시간 창

Scheduler의 기본 표현식은 cron(30 15 * * ? *)이고 timezone 설정은 UTC다. 15:30 UTC는 다음 날 00:30 KST이며, report_date를 넣지 않으면 PrepareReportWindow가 실행 시점의 Asia/Seoul 전일을 선택한다.

예를 들어 report_date=2026-05-27이면:

운영 기준: 2026-05-27 00:00:00~23:59:59 Asia/Seoul
S3 조회:   2026-05-26T15:00:00Z~2026-05-27T14:59:59Z

각 KST hour는 start_kst, end_kst, start_utc, end_utc를 가진다. Reader는 UTC hour partition 후보를 나열하고 reducer가 start <= timestamp < end_exclusive로 다시 필터링한다. 따라서 KST 날짜와 S3 UTC partition 날짜를 동일하다고 가정하지 않는다.

Factory Branch

입력

기본 dataset:

processed/{factory_id}/factory_state/yyyy=YYYY/mm=MM/dd=DD/hh=HH/
processed/{factory_id}/risk_score/yyyy=YYYY/mm=MM/dd=DD/hh=HH/
processed/{factory_id}/infra_state/yyyy=YYYY/mm=MM/dd=DD/hh=HH/

보조 dataset:

processed/{factory_id}/state_snapshot/yyyy=YYYY/mm=MM/dd=DD/hh=HH/

시간별 집계는 중복/잘못된 record를 제외하고 수집률, 결측 구간, Risk Score, 센서/AI 통계, 노드/워크로드 상태, pipeline 상태와 이벤트를 계산한다. 이벤트에는 severity 기본 점수, 지속 시간, magnitude를 합친 severity_score가 부여된다.

Daily merge는 24개 hourly summary를 합치고 hour 경계에서 120초 이내로 이어지는 동일 이벤트를 병합한다. Factory profile도 context에 포함한다.

Factory	환경	해석
factory-a	physical-rpi	production edge
factory-b	vm-mac	dummy/testbed
factory-c	vm-windows	dummy/testbed

산출물

reports/daily/yyyy=YYYY/mm=MM/dd=DD/{factory_id}/
  intermediate/hourly/hh=00.json
  ...
  intermediate/hourly/hh=23.json
  factory-daily-summary.json
  report-context.json
  report.md
  generation-metadata.json

Cloud Infra Branch

Cloud Infra는 Factory dataset을 재사용하지 않고 collector가 저장한 두 stream을 읽는다.

processed/cloud_infra/fast/yyyy=YYYY/mm=MM/dd=DD/hh=HH/
processed/cloud_infra/slow/yyyy=YYYY/mm=MM/dd=DD/hh=HH/

기대 빈도는 fast 시간당 60개, slow 시간당 12개다. 집계 대상은 Backend ECS/ALB, Data Pipeline Lambda와 DynamoDB, Scheduler, EKS node/pod, ArgoCD, Factory/Storage freshness다. fast/slow는 prefix의 수집 주기 구분이며 각 객체 본문은 통합 Cloud Infra snapshot으로 해석한다.

reports/daily/yyyy=YYYY/mm=MM/dd=DD/cloud-infra/
  intermediate/hourly/hh=00.json
  ...
  intermediate/hourly/hh=23.json
  cloud-infra-daily-summary.json
  report-context.json
  report.md
  generation-metadata.json

Factory와 Cloud Infra는 최종 report.md 계약은 공유하지만 입력 schema, reducer, prompt, renderer, validation은 분리되어 있다.

분리한 이유는 두 도메인의 입력 구조와 서술 맥락이 근본적으로 다르기 때문이다. Factory 보고서는 센서 이상, AI 이벤트, K8s workload 장애처럼 물리 현장과 edge 플랫폼 상태를 다룬다. Cloud 보고서는 ECS/ALB 가용성, Lambda 오류율, EKS 노드 상태처럼 AWS managed service 운영 상태를 다룬다. 같은 reducer와 prompt를 쓰면 두 도메인의 특이점을 하나의 조건 분기로 처리해야 하고, Bedrock에 전달하는 context 구조도 타협된 형태가 된다. branch를 분리해 각자 최적화된 집계와 프롬프트를 유지한다.

Bedrock 생성과 검증

Bedrock은 S3 raw 객체나 하루치 processed 객체를 직접 받지 않는다. Daily merge가 만든 compact report-context.json만 prompt에 포함된다.

생성 후 Lambda가 다음 작업을 수행한다.

1. Bedrock의 한국어 Markdown 초안을 받는다.
2. context 값으로 만든 핵심/섹션별 표를 코드에서 삽입한다.
3. Factory ID 또는 target ID, 날짜, 수집량, Risk 또는 인프라 핵심 수치가 결과에 존재하는지 검증한다.
4. 검증 성공 시에만 report.md와 generation-metadata.json을 저장한다.

검증 실패 시 report-context.json과 daily summary는 이미 남아 있지만 report.md는 쓰지 않는다. generation-metadata.json에는 생성 시각, 실제 client의 model_id, context/report key가 기록된다. 현재 token usage와 input object count는 기록하지 않는다.

모델 값 구분

구분	확인된 값	근거와 해석
애플리케이션 코드 기본값	anthropic.claude-3-sonnet-20240229-v1:0	bedrock_client.py, backfill CLI
Terraform 기본값	anthropic.claude-3-sonnet-20240229-v1:0	variables.tf; Lambda 환경변수와 IAM model ARN에 전달
초기 ADR/계획 기본값	anthropic.claude-3-haiku-20240307-v1:0	과거 선택안이며 현재 실행 코드보다 우선하지 않음
2026-05-28 실검증 모델	anthropic.claude-3-sonnet-20240229-v1:0	S3 generation-metadata.json 검증 기록
실제 배포 override	저장소에서 별도 값 확인 안 됨	checked-in terraform.tfvars.example에는 model 항목이 없음

즉 현재 저장소만으로 확인되는 effective 기본값과 과거 배포 검증값은 Sonnet이다. 운영자가 로컬 terraform.tfvars, TF_VAR_bedrock_model_id, CLI -var로 바꾸면 그 값이 실제 배포 override가 된다. 이 파일들은 저장소에 없으므로 배포 시 terraform plan, Lambda BEDROCK_MODEL_ID, 생성 후 generation-metadata.json을 함께 확인해야 한다.

S3에서 Dashboard까지

Dashboard Backend는 보고서를 생성하지 않는다.

GET /reports
  -> ListObjectsV2 Prefix=reports/daily/
  -> report.md key만 목록화

GET /reports/{report_date}/{factory_id}
  -> GetObject
  -> reports/daily/yyyy=YYYY/mm=MM/dd=DD/{factory_id}/report.md
  -> text/markdown

Factory 보고서는 factory 접근 권한, cloud-infra 보고서는 system view 권한으로 필터링한다. Dashboard Web은 Markdown을 자체 parser로 표시한다.

내보내기도 생성 파이프라인과 분리된다.

형식	실제 처리 위치
Markdown	Reporting Lambda가 생성해 S3 저장
DOCX	Dashboard Web이 docx 라이브러리를 lazy import해 브라우저에서 변환
PDF	Dashboard Web이 HTML print window를 열어 브라우저 인쇄/PDF 저장

백엔드나 Reporting Lambda가 DOCX/PDF 파일을 생성하거나 S3에 저장하지 않는다.

관련 문서

• Daily Report Generator
• Daily Report 운영
• 클라우드 스토리지
• Dashboard Backend
• Dashboard Web