에러 트래킹
예외 이벤트를 이슈로 묶어 상태·심각도별로 추적하고, 스택트레이스와 발생 맥락으로 원인을 좁힙니다.
에러 화면은 SDK가 보낸 $exception 이벤트를 같은 원인끼리 이슈로 묶어 보여줍니다.
목록에서는 오류별 발생 빈도와 영향받은 사용자 수를 보고, 이슈 상세에서는 오류가 난 위치와 발생들의 공통점을 확인합니다.
진입 경로
- 이슈 목록:
/dashboard/[orgId]/[projectId]/errors(사이드바의 에러, 단축키G O) - 이슈 상세:
/dashboard/[orgId]/[projectId]/errors/[issueId] - 규칙·릴리즈·소스맵 관리: 프로젝트 설정 (
/dashboard/[orgId]/[projectId]/settings)
수집 켜기
예외 자동 수집은 기본으로 꺼져 있습니다. 브라우저 SDK에서 capture.exceptions를 켜면 잡히지 않은 오류와 처리되지 않은 Promise 거절이 $exception으로 전송됩니다.
import { init } from "@reopt-ai/data-sdk-client";
const client = init({
writeKey: process.env.NEXT_PUBLIC_REOPT_WRITE_KEY!,
baseUrl: process.env.NEXT_PUBLIC_REOPT_API_URL!,
release: "1.4.0", // 빌드 식별자. 모든 이벤트에 $release_id로 붙습니다
capture: { exceptions: true },
});
// 직접 잡은 오류를 보고할 때
try {
await submitOrder();
} catch (error) {
client.captureException(error, { level: "warning", properties: { step: "checkout" } });
}- 자동 수집은 같은 타입의 예외가 몰릴 때 전송량을 제한합니다. 기본은 예외 타입별로 10건까지 보내고 10초마다 1건씩 다시 허용합니다.
captureException()으로 직접 보낸 오류는 조절하지 않습니다. - 브라우저 확장 프로그램 코드만으로 이루어진 스택은 자동 수집에서 제외합니다.
- Next.js 서버 오류는 서버 SDK의
createOnRequestError를instrumentation.ts에서onRequestError로 내보내면 같은 방식으로 이슈가 됩니다. release는 선택이지만 넣어 두세요. 이슈가 처음·마지막으로 발생한 빌드가 기록되고, 아래 회귀 판정에 쓰입니다.- minify된 스택을 원본 파일·줄·함수명으로 보려면 빌드 뒤에 소스맵을 올리세요. 명령은 CLI의 "소스맵을 CI에서 업로드하기"에 있습니다.
이슈 목록
| 열 | 뜻 |
|---|---|
| 심각도 | 낮음·보통·높음·심각 |
| 이슈 | 이름(기본값은 예외 타입)과 메시지. 누르면 상세로 이동합니다 |
| 추이 | 조회 기간의 발생량. 기간이 2일 이하면 시간별, 그보다 길면 일별 막대입니다 |
| 발생 · 사용자 · 세션 | 조회 기간 안의 발생 수와, 그 오류를 겪은 사용자·세션 수 |
| 최근 발생 | 마지막으로 발생한 시점 |
| 상태 | 행에서 바로 바꿉니다 |
| 담당자 | 없으면 미배정 |
- 처음 열면 최근 7일, 상태 활성, 최근 발생순입니다. 정렬은
최초 발생순·발생 횟수순·영향 사용자순으로 바꿉니다. - 검색창은 이슈 이름과 메시지에서 찾습니다. Enter를 누르거나 입력란을 벗어나면 적용됩니다.
상태와심각도필터는 여러 값을 함께 고를 수 있습니다.- 기간·필터·정렬은 전부 URL에 들어갑니다. 좁혀 둔 목록을 링크로 그대로 넘길 수 있습니다.
- 한 번에 50개씩 불러오고
더 보기로 이어집니다. - 행을 선택하면
해결됨으로,보관,병합(2개 이상 선택 시)을 한꺼번에 적용합니다.
조회 기간은 발생 수·사용자 수·추이를 그 구간으로 좁힐 뿐, 이슈를 목록에서 빼지는 않습니다. 그 기간에 발생이 없던 이슈는 0으로 남습니다.
원본 보기상태와 재발
| 상태 | 쓰는 경우 | 다시 발생하면 |
|---|---|---|
활성 | 아직 판단이 필요한 이슈 | 그대로 활성 |
해결됨 | 고쳤다고 표시한 이슈 | 활성으로 돌아옵니다 |
릴리즈 대기 | 고쳤지만 아직 배포되지 않은 이슈 | 수정된 릴리즈와 같은 릴리즈에서 난 발생은 그대로 두고, 그 밖에는 활성으로 돌아옵니다 |
숨김 | 더는 주의를 끌지 않게 할 이슈 | 이벤트는 저장되고 집계되지만 상태는 바뀌지 않고, 이 이슈로는 알림이 가지 않습니다 |
보관됨 | 목록의 보관으로 내려 둔 이슈 | 활성으로 돌아옵니다 |
이슈 상세에서 해결됨을 고르면, 이 프로젝트에서 관측된 릴리즈가 있을 때 수정된 릴리즈를 묻습니다.
릴리즈를 지정하면 이후 다른 릴리즈에서 같은 오류가 나올 때 재발 알림이 회귀(Regression)로 표시해 알려줍니다. 비워 두면 일반 재발로 처리합니다.
이슈 상세
상단에서 이름(눌러서 수정), 상태, 심각도, 담당자를 바꿉니다. 담당자는 조직 구성원 중에서만 고를 수 있습니다.
요약에는 최초 발생·최근 발생·누적 발생·영향 사용자·fingerprint·담당자가 보입니다. 릴리즈를 보내는 프로젝트라면 릴리즈(처음 → 마지막으로 발생한 빌드)가, 릴리즈를 지정해 해결한 이슈라면 수정된 릴리즈가 함께 나옵니다.
누적 발생은 전체 기간의 합이고, 영향 사용자와 아래 막대(최근 30일 발생 추이)는 최근 30일 기준입니다.
| 탭 | 볼 수 있는 것 |
|---|---|
스택트레이스 | 가장 최근 발생의 스택. 앱 코드만 / 전체 프레임 전환, 원인 체인, 처리됨·미처리 배지. 소스맵이 적용된 프레임은 소스맵 해석됨으로 표시되고 펼치면 주변 소스가 보입니다 |
발생 이벤트 | 발생 한 건씩의 시각·경로·환경·국가. 행을 누르면 스택트레이스가 그 발생으로 바뀝니다. 세션 보기, 리플레이, 사용자 보기로 이어집니다 |
분포 | 브라우저, OS, 경로, 국가, 디바이스, 예외 타입, 발생 위치, 처리 여부, 릴리즈 중 하나를 골라 최근 7일의 상위 20개 값을 봅니다 |
리플레이는 그 발생 시점을 담은 녹화를 해당 위치에서 엽니다. 시점이 겹치는 녹화가 없으면 같은 세션에서 그 직전에 시작한 녹화를 열고, 그것도 없으면 직후 녹화를 엽니다. 재생할 녹화가 없으면 없다고 알려줍니다.- SDK가 직전 동작(
$exception_steps)을 보내면직전 동작목록이 탭 위에 나타납니다.capture.exceptionSteps를 켜면 페이지 이동이 자동으로 기록되고,client.addExceptionStep()으로 직접 남길 수도 있습니다(최대 20개). - 프로젝트 설정의
소스 저장소를 채우면 해석된 프레임에소스 열기링크가 붙습니다. 릴리즈가 커밋 SHA 모양이면 그 커밋을, 아니면기본 브랜치(비우면main)를 엽니다. 왜 이렇게 묶였나?를 펼치면 이 발생이 어떤 조각으로 묶였는지 보여줍니다.알림 만들기는 에러 이슈 조건이 미리 채워진 알림 화면으로 이동합니다.
묶음 고치기
- 병합: 같은 원인이 여러 이슈로 갈라졌을 때 씁니다. 발생 이벤트는 그대로 두고 연결만 옮기므로 과거 이벤트를 모두 볼 수 있습니다.
- 나누기: 한 이슈에 다른 원인이 섞였을 때 fingerprint 단위로 새 이슈를 떼어냅니다. fingerprint가 2개 이상일 때만 가능하고, 최소 하나는 원래 이슈에 남아야 합니다.
- 처음부터 직접 묶으려면
captureException(error, { fingerprint: "..." })로 지정하거나 아래의묶기규칙을 쓰세요. 우선순위는 SDK가 보낸 값, 묶기 규칙, 자동 묶음 순입니다.
프로젝트 설정의 에러 항목
| 패널 | 하는 일 |
|---|---|
에러 규칙 | 숨김·배정·묶기·심각도 규칙. 위에서부터 평가하고, 종류별로 처음 맞는 규칙 하나가 적용됩니다 |
규칙 테스트 | 이벤트 properties를 붙여넣어 저장된 규칙을 돌려봅니다. 아무것도 기록하지 않습니다 |
급증 감지 | 현재는 읽기 전용입니다. 기준은 평소의 3배, 최소 5분에 10건입니다 |
릴리즈 | 이벤트의 $release_id로 관측된 빌드 목록. 미리 등록할 필요가 없습니다 |
심볼셋 | 업로드한 소스맵과 마지막 사용 시점. 삭제해도 이미 해석된 프레임은 그대로 남습니다 |
규칙 조건은 예외 타입, 메시지, 발생 위치, 처리 여부, 레벨, 릴리즈, 경로로 겁니다.
숨김·배정·심각도 규칙은 이슈가 처음 만들어질 때만 적용됩니다. 새로 만든 규칙이 사람이 이미 분류한 이슈를 뒤집지 않습니다.
이슈 상세의 업무로 보내기는 리옵트 스튜디오 브랜드에 연결된 프로젝트에서 쓸 수 있습니다. 보낸 뒤에는 스튜디오 업무 링크와 보드의 현재 단계가 보입니다. 이슈 상태를 바꾸면 업무에, 보드에서 단계를 바꾸면 이슈 상태에 반영됩니다. 연결되지 않은 프로젝트에서는 버튼이 비활성으로 보입니다.
다른 화면에서 이어 보기
- 알림에서 조건 종류를
에러 이슈로 고르면신규·재발·급증시점과 최소 심각도로 알림을 받습니다. - 대시보드 상세의
+ 에러 이슈 타일은 최근 7일 발생 횟수 기준 활성 이슈 상위 5개를 타일로 추가합니다. - 세션 타임라인과 사용자 타임라인의 예외 행에는
이슈 보기가 붙습니다. 이벤트 스트림에서는 예외 행의 상세 패널에 있는이슈 상세 열기로 넘어옵니다.
주의할 점
- 예외 이벤트는 수집 1건당 데이터 포인트 1을 씁니다.
숨김규칙에 걸린 예외도 수집은 일어났으므로 똑같이 차감됩니다. 이슈 목록과 상세 조회는 차감하지 않습니다. - 사용자·세션 수는 fingerprint별 합계입니다. 병합으로 fingerprint가 여럿인 이슈에서는 같은 사람이 두 번 세어져 실제보다 크게 보일 수 있습니다.
- 심각도는 SDK가 보낸
level을 먼저 따릅니다(fatal은 심각,warning은 보통,info는 낮음). 그 밖에는 미처리 오류가높음, 처리된 오류가보통으로 시작하고,심각도규칙이나 수동 변경이 이를 덮어씁니다. - 소스맵은 이벤트가 저장될 때 한 번 적용됩니다. 지금 올린 소스맵은 그 이후에 발생한 이벤트부터 해석하고, 이미 저장된 이벤트는 그대로 남습니다.
- 목록은 상태·심각도 조건에 맞는 이슈 중 최근에 발생한 500개까지를 대상으로 정렬하고 검색합니다. 이슈가 많은 프로젝트에서는 필터로 먼저 좁히세요.
- 병합과 규칙 변경은 새 발생에 반영되기까지 최대 1분쯤 걸릴 수 있습니다.
다음 단계
- 소스맵 업로드를 CI에 붙이려면 CLI
- 오류가 난 순간의 화면을 보려면 세션 리플레이
- 신규·재발·급증 알림을 받으려면 실시간, 인사이트, 알림
- 예외 한 건을 원본 이벤트로 확인하려면 이벤트 스트림