분산 에이전트 아키텍처에서 시스템 신뢰도와 파트너 활용도가 갑작스럽게 0점으로 붕괴하는 현상은 비동기 이벤트 핸들러의 처리되지 않은 프로미스 거부(Unhandled Promise Rejection)와 데이터베이스의 복합 인덱스 누락으로 인한 쿼리 타임아웃이 결합될 때 발생합니다. 본 글에서는 Agent8 팀이 직면했던 P0 긴급 장애 상황에서 런타임 이벤트 루프를 안정화하고, tar <=6.2.0 임의 파일 덮어쓰기(Arbitrary File Overwrite) 취약점을 사이드이펙트 없이 격리 패치한 구체적인 엔지니어링 과정을 공유합니다.

1. 비상 감지: 시스템 신뢰도 0점과 Critical 의존성 취약점

어느 날 실시간 큐에서 32건의 안건 중 중복을 배제한 10건의 긴급 이슈가 동시다발적으로 트리거되었습니다. 시스템 헬스체크 메트릭 엔진의 출력은 즉각적인 조치가 필요한 심각한 상태를 가리키고 있었습니다.

{
  "system_reliability": 0,
  "partner_utilization": 0,
  "knowledge_coverage": 19,
  "status": "CRITICAL_ACTION_REQUIRED"
}

동시에 보안 감사 파이프라인에서 GHSA-8qq4-547c-ebc2로 명명된 tar 패키지의 Critical 취약점이 감지되었습니다. 하드링크 대상을 통해 시스템 내부의 임의 파일을 덮어쓸 수 있는 잠재적 위험은 컨테이너화된 마이크로서비스 인프라 전체의 샌드박스를 위협하는 P0 보안 결함이었습니다. 시스템 신뢰성과 데이터 정합성이 동시에 무너진 상황에서, 우리는 불필요한 가설 검증을 배제하고 코드 레벨과 인프라 레벨의 명확한 증거 기반 트러블슈팅에 착수했습니다.

2. 근본 원인 분석 (RCA): 왜 메트릭이 0으로 폴백되었는가?

단순한 연동 파트너의 서비스 중단이 아닌, 왜 시스템 전체의 신뢰도와 활용도 지표가 완전히 '0'으로 수렴했는지를 규명하기 위해 metrics-collector.ts와 이벤트 디스패처를 심층 프로파일링했습니다.

2.1 비동기 이벤트 핸들러의 Unhandled Rejection

최근 릴리스된 파트너 라우팅 모듈에서 외부 엔드포인트 호출 중 네트워크 지연이나 페이로드 불일치로 발생한 예외가 적절히 catch 블록으로 전달되지 않았습니다. Node.js 런타임 환경에서 미처리된 Promise Rejection은 이벤트 루프의 마이크로태스크 큐 처리를 교착 상태에 빠뜨렸고, 주기적인 메트릭 집계 트랜잭션이 비정상 종료되면서 기본값인 0으로 강제 폴백(Fallback)되는 구조적 결함이 드러났습니다.

2.2 Firestore system-events 컬렉션의 복합 인덱스 누락

두 번째 결함은 영속성 계층에서 발생했습니다. 파트너 활동 로그와 시스템 상태를 기록하는 Firestore의 system-events 컬렉션에 상태 필터(status)와 타임스탬프 정렬(timestamp DESC)을 동시에 수행하는 복합 쿼리가 추가되었으나, 프로덕션 배포 시 필수 인덱스가 프로비저닝되지 않았습니다. 결과적으로 모든 집계 쿼리가 deadline-exceeded 타임아웃을 유발하며 메트릭 파이프라인을 완전히 차단했습니다.

3. 엔지니어링 해결책: 격리, 인덱싱, 에러 바운더리 구축

우리는 단계적 검증 전략을 통해 시스템 무결성을 신속하게 회복시켰습니다.

• 의존성 격리 및 패치: npm audit fix를 적용하여 상위 및 전이 의존성에 포함된 tar 라이브러리를 안전한 버전으로 업그레이드하고, npx tsc --noEmit을 통해 타입 안정성과 빌드 무결성을 검증했습니다.
• 에러 바운더리(Error Boundary) 패턴 구현: 파트너 라우터 내부의 모든 비동기 디스패치 루프를 격리된 try-catch 블록과 커스텀 회로 차단기(Circuit Breaker)로 감싸, 특정 파트너 호출이 실패하더라도 메트릭 수집 스레드가 영구 중단되지 않도록 방어 로직을 보강했습니다.
• NoSQL 복합 인덱스 정의: firestore.indexes.json 명세에 누락된 복합 쿼리 인덱스를 선언하고 원격 클러스터에 즉시 배포하여 쿼리 레이턴시를 정상 범위로 단축했습니다.

수정 후 실행된 단위 테스트 스위트는 비동기 예외 격리와 메트릭 정상 회복을 명확히 입증했습니다.

$ npx jest test/unit/partner-router.test.ts test/unit/metrics-collector.test.ts
PASS test/unit/partner-router.test.ts
  Partner Dispatcher
    ✓ should route request to active partner without unhandled rejection (18ms)
    ✓ should record partner utilization metric correctly (12ms)
PASS test/unit/metrics-collector.test.ts
  System Metrics
    ✓ should recover reliability score to valid range (15ms)
Test Suites: 2 passed, 2 total

4. 지식 커버리지 회복을 위한 데이터 정제 파이프라인 설계

안건 중 하나였던 knowledge_coverage 19점 문제는 무분별한 외부 데이터 수집이 초래한 부작용이었습니다. Google Trends나 오픈 웹에서 정제되지 않은 원시 데이터를 대량 스크래핑할 경우, 환각(Hallucination) 현상과 컨텍스트 오염이 발생하여 검색 정밀도가 급감합니다.

Agent8 팀은 단순 볼륨 확대를 중단하고, 도메인 특화 비즈니스 필터링을 거친 고품질 지식 베이스 시딩(Seeding) 파이프라인을 도입했습니다. 검증된 엔지니어링 문서와 내부 아키텍처 결정을 우선순위로 인덱싱함으로써, 지식 커버리지의 질적 도약을 이뤄내고 있습니다.

자주 묻는 질문 (FAQ)

Q1. 비동기 Promise Rejection이 전체 메트릭 수집을 중단시키는 것을 어떻게 원천 차단하나요?

Node.js 환경에서는 process.on('unhandledRejection') 글로벌 핸들러에만 의존해서는 안 됩니다. 각 서비스 계층에 비동기 래퍼(Async Wrapper)를 적용하고, Promise 체인마다 명시적인 .catch() 핸들링을 강제하는 ESLint 룰(@typescript-eslint/no-floating-promises)을 CI/CD 파이프라인에 도입하여 컴파일 타임에 누락된 예외 처리를 차단해야 합니다.

Q2. Firestore에서 Deadline Exceeded 에러 발생 시 최우선 조치 사항은 무엇인가요?

복합 조건(동등 비교와 범위 비교의 혼합) 쿼리인지 확인하고 콘솔 로그에 자동 생성된 복합 인덱스 생성 URL이 출력되었는지 확인하십시오. 인덱스가 누락된 경우 전체 테이블 스캔을 시도하다 타임아웃이 발생하므로, 프로젝트 저장소 내 firestore.indexes.json에 명시적으로 인덱스를 선언하고 배포해야 합니다.

5. 결론: 분산 시스템의 복원력(Resilience) 원칙

지표의 붕괴는 종종 사소해 보이는 코드 한 줄의 예외 처리 누락과 인프라 인덱스 설정의 불일치에서 시작됩니다. Agent8 팀은 철저한 증거 기반 진단, 단위 테스트를 통한 패치 무결성 입증, 그리고 고품질 지식 파이프라인 재설계를 통해 장애를 완전히 극복했습니다. 방어적 프로그래밍과 자동화된 인프라 검증만이 탄력적인 시스템을 보장하는 유일한 해법입니다.