에러 트래킹

브라우저 오류 수집

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

<script defer data-domain="example.com" data-capture-errors
  data-release="web-1.2.3" data-environment="production"
  src="https://crm.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가 없는 이벤트는 사용자 수에 포함되지 않습니다.

중요도 분류

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

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를 참고하세요.