[TRACE-6] Outbox Dispatcher runtime 계측 및 오류 정제 #257

목적 (Why)

무엇을 추가/변경하나?

• outbox process 하위에 Dispatcher child span을 추가한다.
• Notification 조회·FCM 전송·상태 저장 결과를 계측한다.
• 성공/스킵/재시도/영구 실패 결과 속성을 추가한다.
• 상위 Outbox span의 예외 메시지를 정제하고, 원본 예외는 업무 호출자에게 재전파한다.
• SQL parameter, FCM token, notificationId 등 민감·고카디널리티 값은 기록하지 않는다.
• JDBC 오류 정제 핸들러와 Outbox 오류 정제 책임을 분리한다.

왜 필요한가? (User value / Problem)

• TRACE-5로 처리 시도별 outbox process root span은 생기지만, Dispatcher 내부의 조회·FCM·상태 저장 구간과 처리 결과는 Trace에서 구분되지 않는다.
• Dispatcher 예외가 OutboxTracing까지 전파되면 span.error(exception)가 원본 예외를 기록하므로, JDBC child span이 정제되어도 notificationId가 상위 span에 남을 수 있다.

비즈니스/기술적 배경

• 재시도 가능 실패와 영구 실패를 Trace에서 구분해야 Outbox 처리 장애 원인을 좁힐 수 있다.
• 현재 SanitizingQueryTracingObservationHandler는 JDBC query span만 정제하므로, 이름과 책임이 공통 Trace 예외 정제로 오해될 수 있다.

전체 설계 (How)

핵심 아이디어/접근법

• OutboxEventDispatcher 실행 구간을 child span으로 나누고 결과 속성을 기록한다.
• 기존 catch 범위를 벗어난 예외는 상위 span에 일반화된 메시지와 error.type만 기록하고 원본 예외를 재전파한다.
• 기존 FirebaseMessagingException 분류, 재시도 횟수, backoff, 트랜잭션 전파 정책은 변경하지 않는다.
• SanitizingQueryTracingObservationHandler를 JdbcQueryErrorSanitizingObservationHandler로 이름 변경하고 JDBC 범위를 유지한다.

주요 컴포넌트/모듈

• OutboxEventDispatcher: child span 경계와 결과 속성
• OutboxTracing: 상위 span 오류 정제와 원본 예외 재전파
• OutboxFirebaseConfig: tracing 컴포넌트 주입
• JdbcQueryErrorSanitizingObservationHandler: JDBC query span 오류 정제 (이름 변경)

데이터 흐름/상태 변화

outbox process [CONSUMER root, TRACE-5, Link -> producer]
├── outbox dispatch [INTERNAL]
│   ├── outbox notification lookup [INTERNAL]
│   ├── outbox fcm send [CLIENT]
│   └── outbox state update [INTERNAL]
└── 오류/결과 attributes

PR 분할 전략 (300라인 초과 시 필수)

• Single PR (production 80140, 테스트 160260, 문서·계약 30~60 LOC 예상)
• Stacked PR (의존성 체인)
• Parallel Change (Expand-Migrate-Contract)
• Branch by Abstraction

Single PR 근거

• child span, 결과 속성, 상위 span 정제가 같은 처리 경로에 있어 함께 검증해야 한다.
• 예상 범위를 넘거나 Collector/agent 도입, DB 정책 변경이 필요해지면 별도 작업으로 분리한다.

부분 머지 안전성

• 전체 머지: ✅ 업무 정책 변경 없이 계측과 오류 정제 활성화

전체 Acceptance Criteria (AC)

• AC1: outbox dispatch, outbox notification lookup, outbox fcm send, outbox state update span을 확인한다.
• AC2: 정상/스킵/재시도/영구 실패 결과가 구분된다.
• AC3: 상위 span에 원본 예외·식별자·SQL 값이 노출되지 않는다.
• AC4: ./gradlew test --tests 'com.beachcheck.outbox.*' --tests 'com.beachcheck.global.tracing.*'가 통과한다.
• AC5: ./gradlew check가 통과한다.
• AC6: dev Tempo에서 정상·실패 처리 시도를 확인한다.

영향 범위

• API 스펙 변경
• DB 스키마 변경
• 설정/환경변수 변경
• 라이브러리 추가/업그레이드
• 캐시/큐/외부 연동 영향: Outbox 처리·FCM 전송 구간 계측 추가, 업무 처리 정책은 유지
• UX/UI 변경

Breaking Changes / 호환성

• Breaking change 없음

• Breaking change 있음

• TRACE-5의 outbox process root span과 Span Link 계약은 변경하지 않는다.

• 원본 예외는 기존과 동일하게 업무 호출자에게 전파된다.

롤아웃/관측 (배포 전략)

Feature Flag / 단계적 배포

• 사용 안함
• 사용함

성공 지표/메트릭

• 한 번의 처리 시도에서 Dispatcher 실행 구간과 최종 결과를 Tempo waterfall로 구분할 수 있다.

모니터링/알림

• 확인 위치: Grafana Explore -> Tempo
• span 계약: outbox process 하위 outbox dispatch, outbox notification lookup, outbox fcm send, outbox state update
• 오류 확인: status description이 일반화된 메시지이고 exception event에 notificationId, SQL parameter, constraint 원문이 없다.

리스크 & 롤백

리스크

• 예외 경로에서 span 종료나 scope 복구가 누락되면 다음 이벤트로 trace context가 누수될 수 있음
• 오류 정제 과정에서 원본 예외가 바뀌면 트랜잭션 롤백과 Outbox 상태 전이가 달라질 수 있음
• 이미 정책으로 처리된 FCM 예외를 상위 span에 ERROR로 중복 기록할 수 있음

완화 및 롤백 전략

• 애플리케이션 변경은 단일 PR로 revert 가능

• Feature flag로 비활성화 가능

• 데이터 롤백 필요

• 원본 예외 재전파, span 종료, 민감값 미기록을 테스트로 검증한다.

의존성

• 선행 이슈/PR: [feat] TRACE-5 Outbox Span Link 구축 #251 TRACE-5 Outbox Span Link
• 블로킹 이슈: [bug] Outbox 조건부 Bean 등록 순서로 알림 폴링 미실행 #253 dev 서버 Outbox 폴링 미실행 (AC6 dev Tempo 검증 전 해결 필요)

증빙/참고 자료

설계/기획

• Trace 계약: docs/TRACING_CONTRACT.md
• OpenTelemetry Span Status: https://opentelemetry.io/docs/specs/otel/trace/api/#span-status
• OpenTelemetry Exception Semantic Conventions: https://opentelemetry.io/docs/specs/semconv/exceptions/exceptions-spans/
• Micrometer Tracing API: https://docs.micrometer.io/tracing/reference/api.html
• Grafana Tempo TraceQL: https://grafana.com/docs/tempo/latest/traceql/

구현 완료 후

• Tempo Dispatcher span 화면:
• 테스트 결과:
• dev 배포 결과: