프론트엔드와 백엔드 오류 추적: JavaScript 및 API 트레이스 상관관계

중요한 상충 관계는 충실도(fidelity) 대 운영 부하(operational weight)입니다. API 실패 및 AI 호출 비용에 대한 시스템 기록소(system of record)로 백엔드 오류 파이프라인을 사용하고, 컴팩트한 브라우저 오류 요약을 그 백엔드를 통해 동일한 trace_id 또는 request_id와 함께 전달합니다. 간단히 말해: 이 방법은

AI 루프의 경우, 오류 횟수로부터 나중에 추정하기보다는 호출 경계(call boundary)에서 비용을 기록해야 합니다. 유용한 이벤트 필드에는 안정적인 트레이스 값(stable trace value), 에이전트 실행 ID(agent run ID), 모델 및 공급업체(model and vendor), cost_usd, latency_ms, 결과(outcome), 그리고 classify, plan, 또는 validate와 같은 낮은 카디널리티(low-cardinality)의 단계가 포함될 수 있습니다. 프롬프트, 액세스 토큰, 고객 주소 또는 임의의 예외 텍스트를 메트릭 레이블에 넣지 마십시오. 로그는 신중하게 검열된 세부 정보를 담을 수 있지만, 메트릭은 무한정 증가하는 시리즈 카운트를 만들지 않으면서 용량 계획(capacity planning)을 지원해야 합니다.

그렇지 않으면 짧은 사고 하나가 브라우저 오류, API 예외, 실패한 모델 호출이라는 세 가지 숫자를 독립적으로 부풀릴 수 있습니다. 조인 키(join key)는 지원팀이 순서를 재구성할 수 있게 해주며, 에이전트 실행 ID는 재무팀이 지출을 워크플로우에 할당할 수 있게 합니다. 둘 다 유지하십시오.

React 프론트엔드와 Node.js 백엔드는 어떻게 오류를 상관관계화해야 하나요?

백엔드는 유효한 상관관계 값(correlation value)을 발행하거나 수락하고, 이를 응답 헤더에 반환하며, 구조화된 로그에 포함해야 합니다. 브라우저의 전역 오류 핸들러는 관련 API 응답에서 보존된 값을 읽어 애플리케이션 소유 엔드포인트로 정리된 요약본(sanitized summary)을 POST합니다. 이 엔드포인트가 브라우저가 아니라 데이터를 선택한 오류 서비스로 전달하므로, 클라이언트 코드에 어떤 수집 자격 증명(ingestion credential)도 노출되지 않습니다.

이 실행 가능한 Go 서비스는 서버 측 계약을 시연합니다. 표준 라이브러리만을 사용하고, 크기 제한을 적용하며, 잘못된 형식의 입력을 거부하고, trace_id로 결합할 수 있는 JSON을 기록합니다. 또한 명시적인 메서드, 상태 확인 및 제한된 속도 제한 재시도를 통해 실제 인증된 로그 검색을 수행하는 내부 핸들러를 노출합니다. 검색 필터가 나타나지 않는 이유는 해당 경로의 디스커버리 매개변수가 선언되지 않았기 때문입니다. 편리한 trace_id 쿼리 매개변수를 발명하면 샘플이 더 좋아 보일 것이지만, 지원되지 않는 계약을 가르치게 됩니다. 브라우저 캡처 코드는 이 기사의 코드 규칙이 Go 전용이기 때문에 의도적으로 생략되었습니다. 와이어 계약(wire contract)은 프론트엔드 프레임워크 전반에 걸쳐 안정적으로 유지되어야 하는 부분입니다.

package main

import (
...

운영 환경에서는 임의의 텍스트를 허용하는 대신, 들어오는 W3C traceparent 헤더를 검증하거나 신뢰할 수 있는 엣지에서 값을 생성해야 합니다. 지원 직원이 복사 가능한 식별자가 필요하다면 별도의 간단한 X-Trace-ID를 반환하세요. 브라우저 보고서에는 마스킹(redaction) 후 메시지, 페이지, 릴리스, 타임스탬프 및 상관관계 값이 포함되어야 합니다. 스택 수집은 유용하지만, 소스맵 처리 없이는 난독화된 스택이 해석하기 어려울 것입니다.

또한 재시도 트랩(retry trap)도 있습니다. 브라우저는 서버가 첫 번째 보고서를 수락했음에도 불구하고 시간 초과 후 다시 전송할 수 있으므로, 보고서에 클라이언트 생성 이벤트 ID를 부여하고 수집 시 중복을 제거해야 합니다. 이는 추적 시각화만큼 화려하지는 않지만, 불안정한 연결 하나가 다섯 개의 명백한 실패로 변하는 것을 방지합니다.

중복은 발생합니다.

제품 선택 전에 소유권 테스트하기

결정은 '어떤 관측 가능성 벤더가 최고인가?'가 아닙니다. 그것은 디스패치 SLO(Service Level Objective)의 응답 창 동안 어떤 증거가 사용 가능해야 하는지, 그리고 플랫폼 팀이 얼마나 많은 온콜 메커니즘을 소유할 것인지에 대한 문제입니다.

더 가벼운 REST 옵션은 더 좁은 운영 모델에 적합합니다: 백엔드 및 API 오류 캡처, 검색 가능한 로그, 저장된 식별자를 사용한 수동 상관관계(manual correlation). 이는 서버를 통해 프론트엔드의 요약 정보를 받을 수 있습니다. 임계값(threshold)이 없고 전화, SMS 또는 웹훅 알림 경로가 없기 때문에, 팀은 쿼리 표면을 폴링하고 자체 경고 디스패처를 운영해야 합니다. 합성 검사(synthetic check)나 하트비트 모니터가 없으므로, '디스패치 작업이 실행되지 않은' 실패에 대해서는 Healthchecks.io와 같은 서비스를 사용해야 합니다. 이러한 것들은 각주가 아니라 중요한 온콜 비용입니다.

브라우저가 재시도하기 전의 여덟 가지 이벤트

오류 예산(error budget)부터 시작하십시오. 만약 디스패치 에이전트가 99.9% 성공적인 실행이라는 서비스 수준 목표(service-level objective, SLO)를 가지고 있다면, 월간 백만 번의 실행은 1,000회의 실패한 실행이라는 오류 예산을 남깁니다. 이 산술 계산은 어떤 제품의 가동 시간(uptime)에 대한 주장이 아니라 설명적인 용량 계획입니다. 대시보드가 여러분을 위해 결정을 내리기 시작하기 전에, 한 번의 모델 재시도 후 사용 가능한 플랜을 반환하는 실행이 성공인지, 저하되었는지, 아니면 실패했는지를 정의하십시오.

따라서 초당 평균 요청 수(average requests per second)가 아닌 실행별 이벤트(events per run)로 데이터 수집 규모를 측정하십시오. 애플리케이션이 의도적으로 하나의 실행 요약(run summary), 최대 6개의 모델 호출 이벤트(model-call events), 그리고 하나의 터미널 오류 이벤트(terminal error event)를 기록한다고 가정해 봅시다. 1,000,000회의 실행을 기준으로 할 때, 브라우저 중복 및 재시도(browser duplicates and retries)를 제외하고 월별 상한 계획 한계는 8,000,000개의 이벤트입니다. 피크 디스패치 기간이 월평균보다 더 중요하므로, 버스트율(burst rate)로 데이터 수집 경로를 부하 테스트하여 백프레셔(backpressure) 상황에서 어떤 일이 발생하는지 확인해야 합니다.

비용 할당(Cost attribution)은 신뢰성(reliability)에 사용된 것과 동일한 계층 구조를 따라야 합니다. 즉, 테넌트 또는 사업 단위(tenant or business unit), 워크플로우(workflow), 에이전트 실행(agent run), 호출(call) 순서입니다. 제공업체에서 보고하는 호출 비용(provider-reported call cost)은 사용 가능한 경우 기록한 다음 집계해야 하며, 지연 시간(latency), 토큰 추정치(token guesses), 또는 예외 발생 여부만으로 지출액을 유추해서는 안 됩니다. 실패한 루프에는 성공적인 유료 호출이 포함될 수 있고, 성공한 루프라도 다섯 번 재시도했기 때문에 낭비일 수 있습니다.

루프를 측정하십시오.

여기서 표면적으로 간단해 보이는 설정이 운영하기에 비용이 많이 들게 됩니다. 오류를 폴링(Polling)하려면 스케줄, 페이지네이션 규율(pagination discipline), 영속적인 커서(durable cursor), 중복 제거(deduplication), 그리고 자체 데드맨 체크(dead-man check)가 필요합니다. 팀이 해당 경로와 실패 시 페이지 처리를 테스트하겠다는 약속을 할 수 없다면, 이를 소유한 플랫폼에서 알림 전송 서비스(alert delivery)를 구매하십시오.

두 가지 종류의 침묵 (Two different kinds of silence)

사용자에게 보이는 오류(user-visible failure)와 API 로그 및 AI 호출 비용(AI-call cost)을 상관관계 분석해야 하는 것이 주된 목적이고, 수동 트레이스 조회(manual trace lookup)가 허용되는 경우 백엔드 우선 패턴(backend-first pattern)을 사용하십시오. 또한 이는 과도기적 아키텍처로도 작동합니다. 현재 W3C 트레이스 컨텍스트(W3C trace context)를 보존하고, 나중에 트레이스 백엔드를 추가하되 조인 의미론(join semantics)을 변경하지 않을 수 있습니다.

이 패턴을 단독으로 소비자 대상 브라우저 애플리케이션에 사용해서는 안 됩니다. 왜냐하면 축소된 스택 디코딩(minified stack decoding), 릴리스 상태(release health), 브레드크럼(breadcrumbs), 또는 세션 재생(session replay) 기능이 평균 복구 시간(mean time to recovery, MTTR)을 실질적으로 감소시키기 때문입니다. 식별자 검색(identifier search)이 분산 트레이싱(distributed tracing)이라고 착각해서는 안 됩니다. 일치하는 텍스트가 포함된 로그 목록으로는 부모-자식 타이밍(parent-child timing), 누락된 스팬(missing spans), 또는 중요 경로(critical path)를 보여줄 수 없습니다.

마지막으로, 능동적인 실패와 조용한 부재를 분리해야 합니다. 오류 포착(Error capture)은 무언가 발생한 것을 관찰합니다. 누락된 물류 조정 작업(logistics reconciliation job)은 아무것도 방출하지 않기 때문에, 하트비트 모니터는 해당 작업 외부, 그리고 동일한 실패 영역 외부에 있어야 합니다. 각 도구가 명확한 책임(crisp responsibility)을 가지고 있을 때, 세 가지 도구가 하나의 임시 플랫폼보다 더 간단할 수 있습니다.

제가 로드맵에 넣을 결정 규칙은 단도직입적입니다: 프론트엔드 진단이 사고를 유발한다면 전용 브라우저 모니터를 선택하고; 서비스 간 트레이스 탐색(cross-service trace exploration)이 원인이라면 전체 관측 가능성 스위트(full observability suite) 또는 OpenTelemetry 기반 스택을 선택하며; 백엔드 오류 포착, AI 호출 비용 귀속(AI-call cost attribution), 수동 ID 상관관계가 SLO를 충족한다면 가벼운 REST 파이프라인을 선택합니다. 수동 조인(manual joins)이 통합이 원래 절약했던 시간보다 더 많은 응답 시간을 소모하게 되면 이 선택을 재검토해야 합니다.

참고 자료 (Sources)

• W3C Trace Context
• OpenTelemetry documentation
• Sentry JavaScript source maps
• Sentry Session Replay
• Datadog Real User Monitoring
• Datadog APM tracing
• Honeycomb observability documentation
• Healthchecks.io documentation
• RFC 5424: The Syslog Protocol