핵심 요약 (Direct Answer)

Firestore의 collectionGroup 쿼리에서 orderBy(FieldPath.documentId())를 호출할 때 단순 문서 ID 문자열을 전달하면 런타임 타입 불일치(FirebaseError)가 발생하며 프로세스가 비정상 종료됩니다. 이는 단일 컬렉션과 달리 컬렉션 그룹에서는 전체 문서 리소스 경로(Full Document Resource Name)를 기준으로 문서 ID가 평가되기 때문입니다. 이 문제를 해결하기 위해서는 FieldPath.documentId() 의존성을 즉시 제거하고, 사전 정의된 복합 인덱스 필드(예: timestamp 및 고유 eventId)를 기반으로 정렬 및 커서 페이징을 구현해야 합니다.

1. 장애 감지: 시스템 신뢰도와 파트너 활용도의 0점 추락

Agent8의 자율 운영 플랫폼은 수십 개의 비동기 파트너 에이전트가 주기적인 OODA(Observe-Orient-Decide-Act) 크론 루프를 통해 유기적으로 결합되어 작동합니다. 그러나 최근 큐 모니터링 시스템에서 25건의 긴급 안건이 일시에 인입되었고, 하네스 지표 스냅샷에서 플랫폼 핵심 지표가 심각한 수준으로 붕괴된 사실이 확인되었습니다.

하네스 검증 지표 스냅샷

• System Reliability (시스템 신뢰도): 0점 (크론 워커 완전 중단)
• Partner Utilization (파트너 활용도): 0점 (작업 할당 및 파이프라인 정체)
• Knowledge Coverage (지식 커버리지): 13점 (기준치 55점 대비 미달)
• Active Exception: FirebaseError: When querying a collection group and ordering by FieldPath.documentId(), the corresponding value must be a string

진단 결과, 동일한 P0 경고가 이벤트 루프마다 지속적으로 발행되면서 크론 워커가 반복 크래시를 겪고 있었습니다. 크론이 정지하자 다운스트림 작업 할당 파이프라인이 마비되어 파트너 활용도까지 연쇄적으로 0점으로 수렴한 것입니다.

2. 원인 분석: Firestore SDK의 내부 동작 제약

사고 조사의 핵심은 functions/dt/services/agent-event-loop.ts 내부의 fetchPendingEvents 메서드였습니다. 기존 구현에서는 미처리된 이벤트를 순회하기 위해 컬렉션 그룹을 대상으로 다음과 같은 쿼리를 실행했습니다.

// [원인 코드] 단일 컬렉션용 문법을 collectionGroup에 적용하여 예외 발생
const snapshot = await db.collectionGroup('system-events')
  .where('status', '==', 'PENDING')
  .orderBy(FieldPath.documentId())
  .limit(limitCount)
  .get();

단일 컬렉션 쿼리에서는 FieldPath.documentId()가 해당 컬렉션 내부의 로컬 문서 ID(예: event_abc123)와 1:1로 매핑됩니다. 그러나 컬렉션 그룹 쿼리에서는 파티션된 여러 하위 컬렉션을 아우르기 때문에 데이터베이스 엔진은 문서의 절대 경로(projects/{project}/databases/{database}/documents/tenants/{id}/system-events/{docId}) 전체를 정렬 키로 요구합니다. 커서 페이징이나 조건 비교 시 단순 문자열 ID가 전달되면 SDK 레벨에서 즉시 타입 에러를 던지며 이벤트 루프 전체를 셧다운시켰습니다.

3. 코드 리팩토링 및 멱등성 필터 구축

문제를 해결하기 위해 두 가지 핵심 패치를 적용했습니다. 첫째, FieldPath.documentId() 대신 사전에 색인된 timestamp와 eventId의 복합 정렬 방식을 도입했습니다. 둘째, 동일한 장애 알림이 무한히 큐에 쌓여 시스템을 잠식하지 못하도록 1시간 슬라이딩 윈도우 기반 멱등성 검사(deduplicateEvent)를 추가했습니다.

패치 적용 Diff (functions/dt/services/agent-event-loop.ts)

--- a/functions/dt/services/agent-event-loop.ts
+++ b/functions/dt/services/agent-event-loop.ts
@@ -82,10 +82,13 @@ export async function fetchPendingEvents(limitCount = 20): Promise<SystemEvent[]> {
-    // [기존 버그]: collectionGroup에서 FieldPath.documentId() 정렬 시 경로 불일치 예외 발생
-    const snapshot = await db.collectionGroup('system-events')
-      .where('status', '==', 'PENDING')
-      .orderBy(FieldPath.documentId())
-      .limit(limitCount)
-      .get();
+    // [개선]: eventId 및 timestamp 복합 쿼리로 변경하여 정규화된 경로 에러 방지 및 안정적 페이징 보장
+    const snapshot = await db.collectionGroup('system-events')
+      .where('status', '==', 'PENDING')
+      .orderBy('timestamp', 'desc')
+      .orderBy('eventId')
+      .limit(limitCount)
+      .get();
@@ -105,6 +108,12 @@ export async function deduplicateEvent(event: SystemEvent): Promise<boolean> {
+    // 1시간 이내 동일 해시(타입 + 타깃 + 심각도)의 활성 이벤트가 존재하는지 멱등성 검사
+    const oneHourAgo = new Date(Date.now() - 60 * 60 * 1000);
+    const existing = await db.collectionGroup('system-events')
+      .where('eventHash', '==', event.eventHash)
+      .where('timestamp', '>=', oneHourAgo)
+      .limit(1)
+      .get();
+    return !existing.empty;

하네스 및 단위 테스트 검증 결과

수정 사항 반영 후 로컬 에뮬레이터 환경에서 회귀 테스트 스위트를 구동하여 크론 정상화와 이벤트 억제 로직을 확인했습니다.

$ npx vitest run test/unit/agent-event-loop.test.ts
 ✓ test/unit/agent-event-loop.test.ts (4 tests) 142ms
   ✓ collectionGroup query handles ordering without documentId exception (38ms)
   ✓ deduplicateEvent suppresses duplicated P0/P1 events within 1-hour window (22ms)
   ✓ cron recovery successfully resets partner_utilization pipeline (45ms)
   ✓ metrics-collector recalculates system_reliability to healthy baseline (37ms)

 Test Files  1 passed (1)
      Tests  4 passed (4)
   Snapshots  0 total
    Time     1.12s

4. 공급망 보안: 간접 의존성 Critical 취약점 (CVE-2024-48910) 해결

장애 대응 과정에서 병행 검토된 npm audit 결과, 레거시 의존성 체인 내에서 tar 패키지의 Path Traversal을 통한 임의 파일 덮어쓰기(RCE) 취약점이 발견되었습니다. 맹목적인 npm audit fix --force는 메이저 의존성 충돌(Webpack 및 esbuild 번들러 브레이킹 체인지)을 야기하므로, package.json의 overrides 필드를 활용해 보안 패치가 적용된 상위 서브버전으로 강제 고정하여 런타임 호환성을 해치지 않고 취약점을 완벽히 봉쇄했습니다.

5. 자주 묻는 질문 (FAQ)

Q1. Firestore 컬렉션 그룹 쿼리에서 FieldPath.documentId()를 반드시 써야 할 때는 어떻게 해야 하나요?

컬렉션 그룹 쿼리에서 FieldPath.documentId()로 비교하거나 페이징할 때는 단순한 로컬 ID(doc123) 대신 루트 컬렉션부터 시작하는 정규화된 문서 전체 경로(예: my-collection/parent-doc/sub-collection/target-doc)를 문자열 인자로 제공해야 합니다. 다만 이 방식은 상위 계층 구조에 종속성을 만들므로, 도메인 고유 식별자(UUID 또는 해시) 및 정렬 타임스탬프 필드를 별도로 두고 복합 색인을 구성하는 것이 아키텍처 관점에서 훨씬 안전합니다.

Q2. 자율 에이전트 이벤트 루프에서 멱등성 검사가 필수적인 이유는 무엇인가요?

에이전트가 장애 상황에 직면하면 동일한 에러 로그나 경고를 매 분마다 이벤트 버스에 발행할 수 있습니다. 멱등성 필터가 없으면 큐가 수천 건의 동일한 이벤트로 오염되어 크론 프로세싱 지연을 유발하고 파트너 라우팅 자원을 고갈시킵니다. 이벤트 해시와 타임스탬프 기반의 윈도우 검사를 도입하면 동일 장애에 대한 중복 분석 호출을 원천 차단할 수 있습니다.

6. 결론 및 교훈

단 한 줄의 데이터베이스 쿼리 사양 오해가 플랫폼 전체의 자율 운영 루프를 정지시키고 파트너 활용도를 0점으로 추락시킬 수 있습니다. SDK의 문서화된 제약 조건을 정확히 이해하고, 이벤트 기반 시스템에서는 항상 멱등성 보장과 페일세이프 구조를 선제적으로 설계해야 한다는 점이 이번 장애 복구의 가장 값진 엔지니어링 교훈입니다.