RCA: SiteTrackPreprocessorRunner::loadAllElementRecords | match failed (primary + fallback)

Overview#

What Happened#

2026-06-24 20:17 KST 경 cupixworks-sitetrack-preprocessor-agent가 facility dwwuda (bim_id 16250) sitetrack 전처리를 수행하면서 서버에서 받은 ElementRecord 40건을 로컬 cpElementRecordMap과 매칭하지 못해 match failed (primary + fallback) error 로그가 1분 사이에 burst로 기록되었다. 같은 run에서 fallback 매칭은 12,725건 성공했으므로 sitetrack 처리 자체는 진행되었지만, 40개 element record의 oid/task 동기화가 누락되었다.

Quick Facts#

Affected Teams#

Timeline#

1. 2026-06-24 20:14:59 KST — PreprocessorService::createCPSitetrack | begin - sitetrackId: 20051 (run 시작)
2. 2026-06-24 20:17:20 KST — loadAllElementRecords에서 첫 match failed (error) 발생 — first_seen
3. 2026-06-24 20:18:10 KST — 동일 패턴 마지막 발생 — last_seen, 총 40건
4. 2026-06-24 20:18:12 KST — loadAllElementRecords | fallback matches: 12725 info 로그 출력 (run 정상 진행)

Error Log#

Datadog Logs

SiteTrackPreprocessorRunner::loadAllElementRecords | match failed (primary + fallback) - facility_key: dwwuda, server ElementRecord: { revisioned_keys: [17832::::4/0/710], bim_id: 16250, element_id: 8897738, category_id: 1027977, texture_id: none, level_id: 54149 } | tried primary_keys: [16250-17832::::4/0/710-null], fallback_key: 8897738-null

Impact#

• Service: cupixworks-sitetrack-preprocessor-agent
• Team: clark-vdc
• 발생 횟수: 40
• 최초 발생: 2026-06-24 20:17 KST
• 최근 발생: 2026-06-24 20:18 KST

Root Cause Summary#

SiteTrackPreprocessorRunner.loadAllElementRecords는 facility dwwuda / bim 16250 의 server ElementRecord 집합을 로컬 cpElementRecordMap (primary key ${bimId}-${bimRevisionId}::::${bimExternalId}-${textureId}) 또는 fallback cpFallbackRecordMap (key ${cpElement.id}-${textureId}, TSLA-12370 에서 추가) 와 매칭한다. 12,725 건은 fallback 으로 매칭되었으나 40 건은 server ElementRecord 가 가리키는 element_id (예: 8897738, 12621421~12622866) 가 로컬 cpElements 집합에 존재하지 않아 primary 와 fallback 모두 실패했다. 즉 element.getAll(facilityKey, cpBim.id=16250, cpCategory.id, levelIds) 응답에서 누락된 Element를 server-side siteinsights.getElementRecords 가 반환했기 때문에, 어떤 키로도 매칭할 수 없는 상태였다. 동일 burst의 모든 미매칭 record가 같은 bim_id=16250, level_id=54149, category_id(1027977 또는 1030269)에 속하므로, server-side ElementRecord와 element.getAll API 가 보는 Element 집합 사이의 일관성 깨짐 이 root cause다 (예: 일부 Element 가 server-side에서 archived / soft-deleted / 다른 bim_revision 으로 옮겨졌으나 ElementRecord 는 그대로 남아 있는 데이터 상태).

Technical Analysis#

Code Path#

Entry point: applications/agents/packages/cupix-sitetrack-preprocessor-agent/src/runner/sitetrack-preprocessor-runner.ts:28 — await this.loadAllElementRecords(cpSitetrack, cpElements, uniqueLevelIds)

전처리 흐름:

1. createCPElements (line 130) — bim×category 조합으로 element.getAll(facilityKey, cpBim.id, cpCategory.id, levelIds) 호출하여 로컬 cpElement 집합을 빌드. 각 cpElement는 DB id (cpElement.id) 와 bimRevisionedKey = ${bimRevisionId}::::${bimExternalId} 를 가진다.
2. loadAllElementRecords (line 295) — 각 cpElement에 대해 makeElementRecords() 로 가능한 CPElementRecord 들을 생성하고 primary key identifierKey 로 cpSitetrack.cpElementRecordMap 에 등록.
3. 동일 메서드에서 siteinsights.getElementRecords(facilityKey, categoryIds chunk, uniqueLevelIds, recordCapturedAt) 로 server ElementRecord 를 가져와 두 단계 매칭:
   • Primary: ${elementRecord.bim?.id}-${revisionKey}-${textureId} 가 cpElementRecordMap 에 있는지.
   • Fallback (TSLA-12370): primary 실패 시 cpFallbackRecordMap 을 lazy 빌드 후 ${elementRecord.element?.id}-${textureId} 로 조회.
4. 둘 다 실패하면 logElementRecordMatchFailure 가 error 로깅. 이 함수는 isTargetBim 인 경우(즉 cpSitetrack.cpBims 에 해당 bim.id 가 존재)에만 error를 남긴다 — 이번 케이스는 bim_id 16250 이 target bim에 포함되어 있어 error가 발생한 것.

Primary key는 bim_revision_id 가 다르면 매칭 실패함:

const textureId = this._cpPhase.srvTextureId || null;
this._identifierKey = `${this._cpElement.cpBim.id}-${this._cpElement.bimRevisionedKey}-${textureId}`;
// ...
get fallbackKey(): string {
    const textureId = this._cpPhase.srvTextureId || null;
    return `${this._cpElement.id}-${textureId}`;
}

매칭 로직 (실패 지점은 line 344):

for (const elementRecord of srvElementRecords) {
    if (!elementRecord.revisioned_keys?.length) continue;

    const textureId = elementRecord.texture?.id ?? null;
    let cpElementRecord: CPElementRecord | undefined = undefined;

    for (const revisionKey of elementRecord.revisioned_keys) {
        const key = `${elementRecord.bim?.id}-${revisionKey}-${textureId}`;
        if (cpSitetrack.cpElementRecordMap.has(key)) {
            cpElementRecord = cpSitetrack.cpElementRecordMap.get(key);
            break;
        }
    }

    if (!cpElementRecord) {
        populateFallbackMap(cpFallbackRecordMap, cpSitetrack.cpElementRecordMap, 'SiteTrackPreprocessorRunner', 'loadAllElementRecords');
        const fKey = buildFallbackKey(elementRecord.element?.id, textureId);
        cpElementRecord = cpFallbackRecordMap.get(fKey);
        if (cpElementRecord) {
            fallbackMatchCount += 1;
        }
    }

    if (cpElementRecord) {
        cpElementRecord.setFromSrvElementRecord(elementRecord);
        setFromSrvElementRecordCount += 1;
    } else {
        // WARN: Server ElementRecord not found by full key match
        logElementRecordMatchFailure(elementRecord, cpSitetrack, 'SiteTrackPreprocessorRunner');
    }
}

Failure 로깅 (target bim 인 경우에만 error):

export function logElementRecordMatchFailure(
    elementRecord: TESLA.ElementRecord,
    cpSitetrack: CPSitetrack,
    className: string
): void {
    const bimId = elementRecord.bim?.id;
    const isTargetBim = cpSitetrack.cpBims.some(cpBim => cpBim.id === bimId);
    if (!isTargetBim) return;
    // ...
    logger.error(
        '%s::loadAllElementRecords | match failed (primary + fallback) - facility_key: %s, ...',
        ...
    );
}

기대 동작: TSLA-12370 도입 후 bim_revision_id 가 달라지더라도 element.id 가 동일하면 fallback 매칭이 성공해야 함. 실제 동작: server ElementRecord 가 가리키는 element.id (예: 8897738, 12621421) 가 로컬 cpFallbackRecordMap (= cpElement.id 기반) 에도 존재하지 않아 fallback 도 실패. 즉 cpElements 집합 자체에 이 element id 들이 빠져 있다.

Log Evidence#

Datadog 쿼리 (재현용):

service:cupixworks-sitetrack-preprocessor-agent "SiteTrackPreprocessorRunner::loadAllElementRecords" "dwwuda"

미매칭 record 패턴 (모두 같은 sitetrack run, bim 16250, level 54149, texture none):

2026-06-24 20:17:20 KST — error
match failed (primary + fallback) - facility_key: dwwuda, server ElementRecord:
  { revisioned_keys: [17832::::4/0/710], bim_id: 16250, element_id: 8897738,
    category_id: 1027977, texture_id: none, level_id: 54149 }
  | tried primary_keys: [16250-17832::::4/0/710-null], fallback_key: 8897738-null

2026-06-24 20:18:10 KST — error
match failed (primary + fallback) - facility_key: dwwuda, server ElementRecord:
  { revisioned_keys: [17832::::4/0/452], bim_id: 16250, element_id: 12621431,
    category_id: 1030269, texture_id: none, level_id: 54149 }
  | tried primary_keys: [16250-17832::::4/0/452-null], fallback_key: 12621431-null

같은 run에서 fallback 다수 성공:

2026-06-24 20:18:12 KST — info
SiteTrackPreprocessorRunner::loadAllElementRecords | fallback matches: 12725

Run-context (begin):

2026-06-24 20:14:59 KST — info
PreprocessorService::createCPSitetrack | begin - sitetrackId: 20051
PreprocessorService::createCPSitetrack | end

미매칭 element_id 들의 분포(샘플): 8897738, 12621421, 12621422, 12621423, 12621425, 12621426, 12621428, 12621431, 12621466, 12621469, 12621471, 12621499, 12621505, 12621575, 12621577, 12621606, 12622203, 12622538, 12622863, 12622866 등. 큰 묶음(12621xxx~12622xxx)이 연속되어 있어 동일 시점에 server-side 에 일괄 생성된 element 그룹으로 보이며, 로컬 element.getAll 응답에서만 누락되었다는 의미.

Hypotheses Considered#

Fix Recommendation#

즉시 조치 (Critical)#

• 운영 영향이 제한적이므로 긴급 핫픽스는 불필요. 단, 데이터 정합성 영향을 가시화하기 위해:
  • applications/agents/packages/cupix-sitetrack-preprocessor-agent/src/runner/sitetrack-preprocessor-runner.ts:344 의 미매칭을 logger.warn 으로 강등하는 것을 검토 (다음 항목 참고). 현재 error 레벨은 운영자 알람을 유발하지만 sitetrack run 자체는 정상 완료된다 (fallback matches: 12725 info 가 같은 run에 기록됨).
• facility dwwuda / bim 16250 의 미매칭 element_id 목록 (위 Log Evidence) 을 clark-vdc 팀에 공유하여 server-side DB 상태 확인 요청:
  • Element 테이블에서 해당 id 들이 존재하는지, bim_id=16250 인지, discarded_at 이 set 되었는지.
  • 동일 element_id 가 다른 bim_revision_id 로 옮겨졌는지, 옮겨진 경우 ElementRecord 의 stale reference 인지.

단기 개선 (1주 이내)#

• 로그 레벨 재조정 — cpFallbackRecordMap 에도 매칭되지 않는 케이스는 "server-side ElementRecord 가 로컬 element 집합 밖을 참조" 라는 데이터 상태이며, agent 코드가 자체적으로 복구할 수 없다. error → warn 으로 강등하고, log 메시지에 "likely server-side stale ElementRecord referencing missing/archived Element" 같은 hint 추가. 위치: applications/agents/packages/siteinsights/src/util/element-record.util.ts:68-80.
• 결과 요약 메트릭 추가 — loadAllElementRecords 종료 시 (line 349-357 부근) primaryMatchCount, fallbackMatchCount, unmatchedCount 를 info 로그로 함께 출력해 미매칭 비율을 추적할 수 있게 한다. 현재는 fallback 성공 카운트만 info 로 남고 unmatched 는 row-level error 로만 남아 burst 시 알람만 시끄럽다.
• pagination 확인 (H5) — applications/agents/packages/api/.../element.ts 의 getAll 이 모든 페이지를 합쳐서 반환하는지 검증. 연속 element_id 묶음이 누락되는 패턴이 pagination boundary 가능성을 시사한다.

장기 개선 (재발 방지)#

• Server-side siteinsights.getElementRecords 응답과 element.getAll 응답 간의 일관성 계약 정의. 둘 다 동일한 bim_id + bim_revision_id + level_ids 필터로 동작하지 않으면 본 RCA 같은 mismatch 가 반복된다. 가능한 방향:
  1. ElementRecord 에 element_id 외에 bim_revision_id 를 함께 저장하고 server 가 현재 active revision 의 record 만 반환.
  2. Element 가 archive/migrate 되면 관련 ElementRecord 도 cleanup 하는 데이터 lifecycle 보장.
• Sitetrack postprocessor 에서 unmatched ElementRecord 가 후속 trace 생성에 끼치는 영향을 정량화하는 별도 audit job — 정합성 손실을 빨리 감지하기 위함.

Monitoring#

• 시계열 위젯: loadAllElementRecords unmatched error 비율
  textCopy

  sum:trace.sitetrack_preprocessor.errors\{service:cupixworks-sitetrack-preprocessor-agent,resource_name:loadAllElementRecords\}.as_count()
  

• 시계열 위젯: facility 별 burst 감시 (현재 alert 의 잡음 줄이기)
  textCopy

  count:cupixworks-sitetrack-preprocessor-agent.logs\{status:error,@function:loadAllElementRecords\} by \{facility_key\}.as_count()
  

• 시계열 위젯: fallback 매칭 성공 vs 실패 비율 (단기 개선 메트릭 도입 후)
  textCopy

  sum:cupixworks-sitetrack-preprocessor-agent.element_records.unmatched\{service:cupixworks-sitetrack-preprocessor-agent\} by \{facility_key\}.as_count()
  

Risk Assessment#

• Risk level: low
• 예상 복잡도: standard
• 운영 영향: 단일 sitetrack run 의 일부 ElementRecord 가 oid/task 동기화를 누락한다는 데이터 정합성 영향이 존재하지만 sitetrack run 자체는 정상 종료되었다. 동일 패턴이 다른 facility/run 으로 확산되는지 7일 추세 모니터링 후 코드 변경(log downgrade + audit metric)을 적용하는 것이 안전하다.