trex-core/docs/srs/Exception/req-093_dlq-visibility-and-emit-error-alert.md

req-093: DLQ 가시성/경보 + emit 실패 경보 (trex.events.dlq 관측성)

• Status: Implemented
• Type: Exception
• Priority: High
• Owner: project maintainers

Intent

• trex.events.dlq(unroutable + 발행 실패 양쪽)는 현재 durable 큐로 보존되지만 소비/알림 주체가 없어 운영에서 조용히 누적된다. 또한 _make_event_emitter의 발행 실패는 warning 로그로 삼켜져 운영자가 인지하지 못한다. DLQ 유입/깊이를 관측 가능하게 만들고, 최종 실패 시 식별 가능한 경보 레벨 로그를 남겨 운영 피드백 루프를 닫는다.

Requirement

• trex.events.dlq 유입(unroutable + 발행 실패 양쪽)과 깊이(queue depth)를 운영에서 관측·경보 가능하게 한다. 구현 방식(메트릭 노출 / 로그 기반 / 소비자 데몬)은 draft-batch-design에서 OQ-3 기준으로 결정한다.
• unroutable 이벤트: mandatory=True → UnroutableError → _publish_dlq로 trex.events.dlq에 보존하는 기존 경로는 유지하되, DLQ 유입이 관측 가능해야 한다.
• 발행 실패 이벤트: REQ-091의 재시도까지 실패한 경우 TransportUnavailableError가 올라오면, 해당 실패를 DLQ(또는 별도 실패 경보 채널)에 추적 가능한 형태로 기록하거나 메트릭을 카운트한다. 구체 경로는 OQ-3 결정에 따른다.
• _make_event_emitter(runtime/daemon.py)의 발행 실패 처리를 보강한다: REQ-091 재시도 후에도 실패 시 단순 WARNING 삼킴이 아니라 ERROR 또는 그에 준하는 경보 레벨 로그를 남긴다. 로그에는 routing key, 슬롯 ID(또는 correlation 정보), 실패 사유가 포함되어 식별 가능해야 한다.
• _publish_dlq의 best-effort 실패(DLQ 자체 발행 실패)도 ERROR 수준 로그를 남긴다.
• 이 변경은 adapters/messaging/rabbitmq.py(_publish_dlq)와 runtime/daemon.py(_make_event_emitter) 및 관측성 메커니즘 추가 범위에 국소화한다. wire 계약·consume/RPC 경로·슬롯 도메인 불변(NFR-1·NFR-3 흡수).

Acceptance Criteria

1. Given unroutable 이벤트가 trex.events.dlq에 유입될 때, When 관측 지표(로그/메트릭/소비자)를 확인하면, Then DLQ 유입이 운영자가 인지 가능한 형태로 노출된다(S-3 연결).
2. Given trex.events.dlq 큐의 깊이(depth)를 확인할 때, When 유입 이벤트가 누적되면, Then 운영자가 접근 가능한 지표(로그/메트릭/RabbitMQ 관리 API 등)로 깊이를 파악할 수 있다(S-3 연결).
3. Given REQ-091 재시도 후에도 발행이 실패한 경우, When _make_event_emitter에서 TransportUnavailableError를 처리할 때, Then WARNING 수준이 아닌 ERROR(또는 이상) 수준 로그가 남고, routing key와 슬롯 식별 정보가 포함된다(FR-4 연결).
4. Given _publish_dlq의 DLQ 재발행 자체가 실패한 경우, When 예외가 발생하면, Then ERROR 수준 로그가 남고 메시지 유실이 silent하게 처리되지 않는다.
5. Given DLQ 가시성 구현 방식이 설계 단계에서 확정된 후, When batch design 문서를 확인하면, Then OQ-3(DLQ 가시성 구현 방식 — 메트릭/로그/소비자 데몬 중 택1)이 명시적으로 결정되어 있다(OQ-3 종료 조건 추적).
6. Given DLQ 유입/경보 메커니즘이 추가된 상태에서, When consumer 경로(intent/slots/control RPC)를 확인하면, Then 해당 경로의 동작·큐 바인딩·토폴로지에 변화가 없다(consume/RPC 무회귀, NFR-1).

Impacted Area

• Docs: docs/operations.md(DLQ 가시성/경보 운영 절차 신규 기재, REQ-094에서 함께 갱신 검토). docs/runtime-flows.md(슬롯 이벤트 발행/구독 DLQ 경로 설명 보강, REQ-094에서 갱신).
• Modules: trex_core/adapters/messaging/rabbitmq.py(_publish_dlq L199-216 — DLQ best-effort 실패 ERROR 로그 + 가시성 훅). trex_core/runtime/daemon.py(_make_event_emitter L238-248 — 발행 실패 ERROR 경보). 관측성 구현(OQ-3 결정 후 추가). wire 계약·consume/RPC 경로·슬롯 도메인 불변.
• Tests: tests/adapters/messaging/ — DLQ 유입 관측 지표 확인(AC-1), DLQ 깊이 노출(AC-2), emit 실패 ERROR 로그(AC-3), DLQ 재발행 실패 ERROR(AC-4), consume 경로 회귀(AC-6). tests/application/test_messaging_event_publisher.py 기존 회귀 유지.

Notes

• 출처: dcy-031 FR-3(D), FR-4, A-3(dcy-029 관측성 자산 재사용 여부 검토), S-3.
• OQ-3(DLQ 가시성 구현 방식 — 메트릭/로그/소비자 중 택1): 설계 단계 결정. AC-5에서 추적. 종료 조건: batch design에 명시되면 Answered. dcy-029(REQ-084~090) 관측성 자산(구조화 로깅 인프라) 재사용 가능성을 설계 단계에서 검토한다.
• FR-4(emit 실패 경보)는 독립 REQ로 승격하지 않고 본 REQ에 흡수한다 — FR-3(DLQ 가시성)과 같은 코드 경로(_make_event_emitter, _publish_dlq)를 공유하며 독립 구현·검증 시 오버헤드 대비 가치가 낮다.
• _publish_dlq best-effort 정책(실패 시 silent log → ERROR로 강화)은 기존 wire 계약 변경 없이 로그 레벨 조정만으로 구현 가능해 설계 결정 없이도 확정 가능하다.
• 본 변경은 DLQ 소비자 데몬(별도 상시 프로세스)을 강제하지 않는다 — 관측 방식은 OQ-3에서 결정.

Change Log

CHG-20260619-01

• Date: 2026-06-19
• Author: trex-core-dev

Change Summary

• dcy-031 FR-3(D) + FR-4로부터 최초 생성(Proposed). NFR-1·NFR-3 흡수. FR-4를 본 REQ에 흡수. OQ-3 설계 인계. A-3(dcy-029 자산 재사용) 인계. S-3 연결.

Intent

• DLQ 가시성/경보 + emit 실패 경보 정책을 backlog에 정규화하고, OQ-3 설계 결정 추적을 AC-5로 고정한다.

Acceptance Criteria Delta

• Added:
  • AC-1: DLQ 유입 관측 가능
  • AC-2: DLQ 깊이 파악 가능
  • AC-3: emit 실패 ERROR 수준 경보
  • AC-4: DLQ 재발행 실패 ERROR
  • AC-5: OQ-3 종료 조건 추적
  • AC-6: consume/RPC 경로 무회귀
• Updated: 없음
• Removed: 없음

Impacted Area Delta

• Docs:
  • docs/operations.md, docs/runtime-flows.md
• Modules:
  • trex_core/adapters/messaging/rabbitmq.py, trex_core/runtime/daemon.py
• Tests:
  • tests/adapters/messaging/ (DLQ/emit 경보/회귀)

Delivery Trace Delta

• Batches:
  • none (draft-req 단계, batch 미편성)
• Releases:
  • none

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current
• Follow-up Action: confirm-req 후 REQ-091·092와 함께 단일 batch 편성 예정

Validation Plan

• 로그 캡처 기반으로 DLQ 유입 로그/ERROR 레벨 확인. mock _publish_dlq 실패 시나리오로 AC-4 검증. OQ-3 결정 후 구현 방식에 맞는 통합 검증 추가.

CHG-20260619-02

• Date: 2026-06-19
• Author: 팀장 (confirm-req)

Change Summary

• Proposed → Approved. 필수 필드 충족, AC 구체, source dcy-031(confirmed, Open OQ 0) 정합. FR-4 흡수 승인(동일 emit 경로). OQ-3(DLQ 가시성 구현 방식)은 AC-5에서 design 인계 추적 — 승인 비차단.

Intent

• delivery input 승인. DLQ 가시성 구현 방식(메트릭/로그/소비자)은 draft-batch-design에서 dcy-029 관측성 자산 재사용성과 함께 확정.

Acceptance Criteria Delta

• Added: 없음
• Updated: 없음
• Removed: 없음

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current
• Follow-up Action: REQ-091·092와 함께 단일 batch 편성 예정