accessibility
Debug Fundamentals

한국어

English
日本語
简体中文

한국어

English
日本語
简体中文

Appearance

에러 로그를 상세히 남기기 ​

에러 로그는 단순히 문제를 빠르게 해결하는 데 필요한 도구일 뿐 아니라, 같은 문제가 다시 발생하지 않도록 예방하는 핵심 자료예요. 로그가 충분히 남아 있으면 개발자는 문제의 원인을 분석하고, 코드 수정이나 시스템 개선으로 이어질 수 있어요.

에러 수집 내용 ​

아래는 에러 로그를 남길 수 있는 정보들이에요. 이 정보들을 기록하면 문제가 발생한 상황을 더 쉽게 이해하고, 빠르게 대응할 수 있어요.

사용자 상태 ​

사용자가 어떤 환경에서 문제를 겪었는지 기록해요. 다양한 기기와 설정에서 발생할 수 있는 문제를 추적할 수 있어요.

소프트웨어 버전: `1.3.5`
디바이스 정보: `iPhone 13 Pro, iOS 17.4.1`
브라우저 버전: `Chrome 123.0.1234.56`, `Safari 17.1`
지역, 시간대: `Asia/Seoul`

확인할 것 ​

  • 소프트웨어 버전
    릴리즈 노트 및 변경 이력을 확인해요. 해당 버전에 도입된 기능, 수정된 버그 등의 내용을 확인해요. 또는, 이전/다음 버전과의 비교 테스트를 해보면 문제의 범위를 좁힐 수 있어요.

  • 디바이스 정보
    해상도나 렌더링 성능에 따라 발생하는 문제인지 확인해요.
    WebKit 버그 리포트

  • 브라우저 버전
    특정 브라우저에서만 발생하는 문제는 polyfill 적용 여부와 브라우저 업데이트 내역을 함께 살펴봐요.
    Chrome 업데이트 내역
    Safari 릴리즈 노트
    Can I use

  • 지역, 시간대(Timezone)
    브라우저에서 사용하는 시간대가 KST인지 확인해요.
    시간대 비교 도구

배포 상태 ​

문제가 발생한 빌드가 어떤 커밋과 연결돼 있는지 확인할 수 있어요. 어떤 기능이나 수정이 포함된 상태였는지를 파악하는 데 도움이 돼요.

앱 버전: `v1.3.5`
커밋 ID: `a1b2c3d4`
빌드 일시: `2025-04-17T08:30:00Z`
릴리즈 노트: https://github.com/org/repo/releases/tag/v1.3.5
환경: `production`

확인할 것 ​

  • 해당 커밋과 릴리즈 노트를 참고해서 어떤 변경사항이 있었는지 확인해요.

런타임 상태 ​

에러가 발생한 순간에 사용자가 어떤 입력을 했는지, 어떤 상태였는지를 기록해요.
문제를 재현하고 원인을 추적하는 데 중요한 단서가 돼요.

옵션 ID: `opt-00123`
옵션 유형: `size`
선택한 개수: `2`

확인할 것 ​

  • 특정 옵션 조합에서만 문제가 발생하는지 확인해요.
  • 서버에서 내려온 데이터와 사용자 선택값이 일치하는지 확인해요.
  • 클릭, 입력 등의 인터랙션이 실제로 처리됐는지 확인해요. 디바운스나 중복 클릭으로 race condition이 발생한 것은 아닌지도 확인해요.

⚠️ 주의사항 ​

에러 로그에는 다음과 같은 개인정보는 절대 포함하지 않아요.

사용자 이름, 이메일, 전화번호
IP 주소 전체
결제 정보 등 민감한 데이터

필요하다면 ID를 마스킹하거나 익명화된 식별자만 저장해요.

에러 로그 수집 방법 ​

Sentry ​

에러를 남길 수 있는 대표적인 방법으로는 Sentry를 활용하는 방법이 있어요. Sentry는 자바스크립트 애플리케이션에서 에러를 자동으로 수집하고, 발생한 맥락을 함께 기록할 수 있는 도구예요. 단순히 스택 트레이스를 수집하는 것을 넘어서, 사용자 행동, 환경 정보, 커스텀 태그 등을 함께 기록할 수 있어 디버깅 효율을 크게 높여줘요.

기본 사용법 ​

tsx
import * as Sentry from "@sentry/react";
Sentry.init({
  dsn: "https://your-dsn.ingest.sentry.io/project-id",
  tracesSampleRate: 1.0 // 퍼포먼스 추적을 원하면 설정할 수 있어요
});

사용자가 어떤 행동을 했는지 타임라인처럼 추적할 수 있게 해주는 기능이에요. 이 breadcrumb는 에러가 발생했을 때 함께 첨부되어, 사용자가 어떤 행동을 했는지를 추적할 수 있게 도와줘요. 로그인을 시도했다거나, 필터를 바꿨다거나, 특정 입력을 했을 때 넣어주면 좋아요.

tsx
Sentry.addBreadcrumb({
  category: "ui.click",
  message: '사용자가 "결제 버튼" 클릭',
  level: "info"
});

tag 사용법 (에러 분류/필터링) ​

수집된 에러를 버전, 지역, 플랫폼, 실험 그룹 등으로 분류해서 필터링할 수 있게 도와줘요. 에러가 new-recommendation 기능 플래그와 관련된 것인지, 특정 버전에서만 발생했는지를 쉽게 추적할 수 있어요.

tsx
Sentry.setTag("feature_flag", "new-recommendation");
Sentry.setTag("app_version", "1.3.5");