에러 트래킹

브라우저 오류 수집

기존 analytics script 태그에 data-capture-errors를 추가하면 전역 오류와 처리되지 않은 Promise 거부를 수집합니다. 릴리스와 환경은 각각 data-release, data-environment로 전달합니다.

<script defer data-domain="example.com" data-api="https://crm.theseeker.io" data-capture-errors
  data-release="web-1.2.3" data-environment="production"
  src="https://cdn.theseeker.io/js/script.js"></script>

릴리스는 최대 200자, 환경은 최대 64자입니다. 브라우저 tracker는 같은 오류를 60초 동안 중복 수집하지 않습니다. 브라우저 오류 이벤트에는 stack 최대 5,000자, message 최대 2,000자, type 최대 200자가 실립니다.

Breadcrumbs와 개인정보

tracker는 최근 30개의 breadcrumb를 오류에 함께 보냅니다. 페이지 이동, 클릭, console warn/error, 실패한 fetch/XHR과 custom event를 기록합니다. Network breadcrumb는 URL query와 hash를 제거합니다. 입력 필드의 값은 수집하지 않습니다. 클릭 텍스트는 링크·버튼 등에서만 최대 40자 기록하고, [data-feedback-mask] 또는 contenteditable 내부는 제외합니다.

Breadcrumb 문자열에서 이메일 주소는 [email], Bearer 자격증명은 Bearer [redacted], 12자리 이상 연속 숫자는 [number]로 바뀝니다. 메시지는 최대 200자, data는 최대 10개 scalar 값입니다. 폼 입력값이나 query string에 민감한 정보를 넣지 마세요.

릴리스와 소스맵

배포마다 data-release에 빌드 릴리스를 지정하고 같은 릴리스 이름으로 소스맵을 업로드합니다. Next.js는 productionBrowserSourceMaps: true로 브라우저 소스맵을 생성할 수 있습니다. 업로드 후에는 공개 빌드 출력에서 반드시 .map 파일을 삭제하세요. 소스맵에 원본 코드가 포함될 수 있습니다.

// next.config.mjs
export default { productionBrowserSourceMaps: true };

npx theseeker-sourcemaps upload --release web-1.2.3 --domain example.com \
  --url-prefix https://example.com/_next/static/ .next/static

소스맵을 업로드하면 원본 위치와 문맥이 오류 프레임에 연결되고 fingerprint가 바뀌어 새 이슈가 한 번 만들어질 수 있습니다. 이후 같은 릴리스의 동일 오류는 해당 이슈에 쌓입니다. API로 목록, 릴리스별 파일 조회와 삭제를 할 수 있습니다. 자세한 multipart 필드, 한도, 응답은 Source Maps API를 참고하세요.

재발과 영향 사용자

해결한 이슈가 이후 릴리스에서 다시 발생하면 재발 상태와 재발 횟수가 기록됩니다. 오류 화면에는 최근 30일의 영향을 받은 사용자 수가 표시됩니다. 사용자 ID가 없는 이벤트는 사용자 수에 포함되지 않습니다.

이슈 상세의 영향 사용자에는 최근 30일 동안 영향을 받은 UID, IP 또는 세션별 사용자가 표시됩니다. 각 항목에서 오류 발생 횟수와 마지막 확인 시각을 볼 수 있습니다. 연결된 리플레이가 있으면 리플레이 버튼으로 바로 재생하거나 해당 사용자의 리플레이 목록으로 이동할 수 있습니다. UID, IP와 리플레이 정보는 조직 멤버에게만 표시됩니다.

청크·리소스 로드 실패와 캐시 진단

브라우저 tracker는 data-capture-errors가 설정된 경우 JavaScript 청크 오류와 같은 출처의 <script> 및 스타일시트 로드 실패를 수집합니다. 추가 CDN 출처를 허용하려면 쉼표로 구분한 origin을 data-asset-origins에 지정하세요. 제3자 스크립트와 tracker 또는 replay 스크립트 자체의 실패는 수집하지 않습니다.

빌드 에셋 실패는 ChunkLoadError, 그 밖의 허용된 스크립트·스타일시트 실패는 ResourceLoadError로 분류합니다. tracker는 브라우저 캐시를 사용하지 않는 요청으로 실패한 URL을 확인하고, 응답 상태와 읽을 수 있는 캐시 헤더 및 리소스 타이밍 정보를 오류에 기록합니다. 동일 URL은 한 페이지에서 한 번만 확인하며, 페이지당 최대 3개 URL을 확인하고 요청은 5초 안에 끝냅니다.

교차 출처 에셋은 data-asset-origins에 출처를 명시해야 확인 대상이 됩니다. 오류 상세에서 각 진단과 에셋 URL을 살펴보고 배포 상태, 캐시 및 원본 응답을 구분하세요.

사용자 식별(identify)·IP 수집

data-capture-errors를 설정한 tracker는 window.theseeker API를 제공합니다. tracker가 로드되기 전에 window.theseekerQueue 배열에 명령을 쌓아 둘 수 있으며, 로드 후에는 대기 명령이 순서대로 실행됩니다. 지원 명령은 identify, setTag, captureException, captureMessage입니다.

window.theseekerQueue = window.theseekerQueue || [];
window.theseekerQueue.push(["identify", "member-123"]);

// tracker 로드 후에는 바로 호출할 수 있습니다.
window.theseeker?.identify("member-123", { plan: "pro" });
window.theseeker?.setTag("area", "checkout");

identify(uid)는 앞뒤 공백을 제거한 1~128자 UID를 탭의 sessionStorage에 저장하고 오류에 연결합니다. identify(null)은 저장된 UID를 지웁니다. 선택적 traits는 문자열, 숫자, 불리언으로 이루어진 최대 5개 항목만 오류 속성 user.<키>로 전달합니다. setTag는 최대 20개 태그를 오류 속성 tag.<키>로 전달합니다. 오류 속성은 평면 값만 허용합니다.

IP 주소는 프로퍼티 설정의 IP 주소 수집을 켠 경우에만 저장합니다. 수집된 IP와 앱 사용자 ID는 조직 멤버에게만 표시됩니다. 국가 코드는 오류에 포함될 수 있지만 IP 수집 설정과 별도로 처리됩니다.

React 오류 경계 보고(captureException)

자동 오류 수집은 전역 오류와 처리되지 않은 Promise 거부를 보고합니다. React 오류 경계 등에서 직접 보고하려면 captureException(error, context)를 호출하세요. context.tags와 context.extra는 오류 속성으로 전달됩니다. 청크 오류로 판별되면 오류 경계 태그보다 chunk_load 분류가 우선합니다. 수동 보고는 브라우저 확장이나 삽입 코드만 포함된 스택을 제거한 뒤에도 오류를 전송합니다.

문자 메시지만 기록할 때는 captureMessage(message, level)을 사용합니다. level은 info, warning, error 중 하나이며 생략하면 info입니다.

window.theseeker?.captureException(error, {
  tags: { boundary: "checkout" },
  extra: { operation: "submit-order" },
});
window.theseeker?.captureMessage("결제 확인이 지연됨", "warning");

재로드 대기열(__theseeker_pending) 형식

청크 실패로 자동 새로고침을 수행하는 호스트는 새로고침 직전에 실패 정보를 sessionStorage의 __theseeker_pending 키에 기록할 수 있습니다. 값은 최신 항목 최대 10개를 담은 JSON 배열입니다. tracker는 오류 수집이 켜져 있으면 시작 시 이를 읽고 키를 지운 뒤, 유효한 항목을 recovered=true와 원래 시각 occurredAt을 붙여 보고합니다.

각 항목은 다음 형식을 사용합니다.

{
  "v": 1,
  "message": "Failed to load script /_next/static/chunks/app-abcdef123456.js",
  "type": "ChunkLoadError",
  "stack": "선택 항목",
  "url": "https://example.com/checkout",
  "ts": 1792100000000,
  "props": {
    "category": "chunk_load",
    "resourceUrl": "https://example.com/_next/static/chunks/app-abcdef123456.js",
    "tag": "script",
    "autoReload": true
  }
}

message는 최대 2,000자, type은 최대 200자이며 stack은 선택 항목입니다. ts는 밀리초 단위 시각입니다. 저장 값은 평면 속성만 전달됩니다. 같은 에셋 실패가 재로드 전후 5초 안에 중복 감지되면 tracker는 새 오류 대신 대기열에서 복구한 오류를 사용합니다.

에셋 로드 실패 알림

에셋 로드 실패 급증 알림은 프로퍼티별로 설정합니다. 기본 임계값은 5건, 집계 구간은 10분이며 임계값은 1~10,000건, 구간은 5, 10, 15, 30, 60분 중에서 선택할 수 있습니다. 설정을 끄면 해당 프로퍼티의 에셋 실패 알림을 만들지 않습니다.

지정한 구간에서 chunk_load 또는 resource 오류가 임계값에 도달하면 알림이 생성됩니다. 알림에는 오류 건수, 세션 수, 배포 불일치·캐시 또는 일시 오류·네트워크 오류 수와 상위 에셋 URL이 포함됩니다. 실제 알림 발송에는 조직의 활성 private Telegram 구독이 필요하며, 에러 알림을 켜야 합니다.

릴리스 상태

오류 화면의 릴리스 상태는 최근 24시간 동안 세션과 오류 이벤트에 기록된 릴리스를 비교합니다. 가장 최근 세션이 속한 릴리스를 최신으로 표시합니다. 최신 릴리스가 아니면서 최근 30분 안에 활성 세션이 있는 릴리스는 오래된 상태로 표시됩니다. 릴리스별 세션 수, 활성 세션 수, 오류 수와 청크·리소스 실패 수를 함께 확인할 수 있습니다.

중요도 분류

오류 화면은 각 이슈를 제목(<타입>: <메시지>)과 수집 플랫폼으로 높음 · 중간 · 낮음 중 하나로 자동 분류합니다. 분류는 조회할 때 계산하므로 규칙이 바뀌면 과거 이슈에도 바로 적용되고, 이슈 묶음(fingerprint)과 알림은 바뀌지 않습니다.

목록은 기본으로 높은 중요도 이슈만 보여 줍니다. 툴바의 중요도 선택에서 중간·낮은 중요도나 전체 중요도를 고를 수 있고, 선택은 URL의 importance 파라미터(medium, low, all)로 공유됩니다. 이슈 행과 상세의 중요도 배지에서 분류 사유(예: 낮음 · 청크 로드 실패)를 확인할 수 있습니다.

알림

프로퍼티별로 새 이슈, 재발, 오류 급증 알림을 각각 켜거나 끌 수 있습니다. 급증 기준은 10~100,000건이며 집계 구간은 5, 15, 30, 60, 180, 360 또는 1,440분 중 고릅니다. 기본값은 기준 100건, 60분입니다.

알림은 조직에 활성 private Telegram 구독이 있어야 발송됩니다. 구독자의 Telegram 설정에서 에러 알림을 켜세요. CRM 알림 센터에도 새 이슈·재발·급증 알림이 표시됩니다.

서버 오류 수집

Node SDK와 Python SDK 모두 프로젝트 키의 errors:write scope가 필요합니다. domain 또는 프로퍼티 ID 중 하나를 지정합니다. 서버 오류 API는 /api/error/server이며 HMAC 서명 요청을 사용합니다.

import { createErrorClient } from "@the-seeker/status-sdk";

const errors = createErrorClient({
  keyId: process.env.CRM_KEY_ID!,
  secret: process.env.CRM_KEY_SECRET!,
  domain: "example.com",
  release: "api-1.2.3",
  environment: "production",
});

errors.setUser({ id: "user-123" });
errors.addBreadcrumb({ category: "log", message: "request started" });
await errors.captureException(new Error("request failed"));

Node의 installGlobalHandlers()는 uncaught exception과 unhandled rejection을 fatal로 수집하고 기본적으로 flush한 뒤 프로세스를 종료합니다. 옵션으로 각 핸들러의 "continue" 동작을 선택할 수 있습니다. Python의 install_excepthook()은 기존 sys 및 thread 예외 hook을 이어 호출합니다.

errors:write는 새 프로젝트 키에 추가되는 scope입니다. 기존 키에는 소급 적용되지 않으므로 새 프로젝트 키를 발급하세요. scope 편집이 활성화된 계정은 기존 키를 편집해 추가할 수 있습니다. API 키 문서에서 scope를 확인하세요.

원시 오류 이벤트는 30일 보관합니다. SDK 설치와 전체 CLI 옵션은 Status SDK, 업로드 endpoint는 Source Maps API를 참고하세요.