Sentry(v20.12.1) K8S 환경에서의 클라우드 네이티브 아키텍처 탐구, 자바스크립트 SDK 설정 심층 분석

기본 구성 옵션

Sentry JavaScript SDK는 초기화 시점에 전달되는 객체를 통해 다양한 설정을 지원합니다. 이 옵션들은 대부분 공통적이지만 플랫폼 특성에 따라 일부 차이가 있습니다.

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  maxBreadcrumbs: 50,
  debug: true,
});

공통 옵션

dsn: 이 값은 이벤트 전송 대상 서버를 지정합니다. 누락 시 SENTRY_DSN 환경 변수에서 자동 읽기 시도. 브라우저와 같은 프로세스 환경이 없는 경우 기본값 적용 안 됨.
debug: 디버그 모드 활성화 여부. 오류 발생 시 유용한 로그 출력. 생산 환경에서는 권장하지 않음.
release: 배포 버전 정보. 자동 감지 가능하지만 수동 설정 권장. SENTRY_RELEASE 환경 변수 또는 window.SENTRY_RELEASE에서 가져옴.
environment: 환경 이름(예: production, staging). 대소문자 구분하며, SENTRY_ENVIRONMENT에서 자동 읽기.
sampleRate: 에러 이벤트의 샘플링 비율 (0.0 ~ 1.0). 기본값 1.0은 모든 에러 전송, 0.1은 10%만 전송.
maxBreadcrumbs: 수집 가능한 부드럽게 추적 기록 최대 개수. 기본값 100.
attachStacktrace: 메시지에 스택 트레이스 자동 첨부 여부. 기본값은 비활성.
sendDefaultPii: 개인 정보(PII) 자동 포함 여부. 기본값 비활성. 필요 시 수동으로 제어.
denyUrls: Sentry로 전송하지 않을 URL 패턴 목록. 전체 경로 포함 매칭.
allowUrls: 전송할 특정 URL 패턴 목록. denyUrls와 반대 개념.
autoSessionTracking: 브라우저 세션 자동 추적 여부. 페이지 로딩 시 세션 이벤트 전송.
normalizeDepth: 컨텍스트 데이터 정규화 깊이. 기본값 3단계.

통합 구성

SDK 통합은 초기화 시점에 integrations 옵션으로 구성되며, 일부 플랫폼에서는 별도의 방식 제공.

integrations: 사용 가능한 통합 모듈 리스트.
defaultIntegrations: 기본 통합 비활성화 여부. false로 설정 시 기본 통합 미적용.

훅 함수

이벤트 처리 흐름을 조작하기 위한 콜백 함수.

beforeSend: 이벤트 전송 전에 호출. 수정된 이벤트 반환 또는 null 반환 시 전송 취소.
beforeBreadcrumb: 부드럽게 추적 기록 생성 전에 호출. 리턴 없으면 기록 제거.

전송 설정

transport: 이벤트 전송 방식 변경. 테스트 또는 프록시 환경에 적합.

트레이싱 옵션

tracesSampleRate: 트랜잭션 전송 확률 (0~1). tracesSampler와 함께 사용 불가.
tracesSampler: 트랜잭션별 전송 확률 계산 함수. 0은 전송 안 함, 1은 항상 전송.

릴리스 및 건강 관리

릴리스는 배포된 코드 버전을 의미하며, 이를 통해 문제 발생 원인 파악, 회귀 검출, 소스맵 적용 등이 가능합니다.

Sentry.init({
  release: "my-project-name@2.3.12"
});

Node.js 환경에서는 process.env.npm_package_version 활용 가능:

Sentry.init({
  release: "my-project-name@" + process.env.npm_package_version
});

환경 설정

환경 이름은 대소문자 구분, 공백, 슬래시 포함 불가. 최대 64자.

Sentry.init({
  environment: "production"
});

이벤트 필터링 및 샘플링

과도한 이벤트를 방지하고 의미 있는 데이터 수집을 위해 필터링 및 샘플링 설정 필요.

에러 이벤트 필터링

beforeSend를 통해 특정 에러 무시 가능.

Sentry.init({
  beforeSend(event, hint) {
    const error = hint.originalException;
    if (error?.message?.match(/database unavailable/i)) {
      event.fingerprint = ["database-unavailable"];
    }
    return event;
  }
});

트랜잭션 이벤트 필터링

tracesSampler 함수를 통해 특정 트랜잭션 제외 가능.

Sentry.init({
  tracesSampler: context => {
    if (context.transactionName.includes("admin")) return 0.5;
    if (context.transactionName.includes("api")) return 0.01;
    return 0; // 무시
  }
});

종료 및 이벤트 처리

애플리케이션 종료 시 미전송 이벤트 처리.

Sentry.close(2000).then(() => {
  // 종료 후 작업
});

기본 통합 항목

InboundFilters: 특정 에러 메시지나 URL 무시.
FunctionToString: 원본 함수 이름 유지.
TryCatch: 비동기 예외 처리.
Breadcrumbs: 사용자 행동 추적 (클릭, 입력 등).
GlobalHandlers: 전역 예외 및 거부된 프로미스 처리.
LinkedErrors: 연결된 에러 재귀 처리.
UserAgent: 브라우저 및 운영체제 정보 추가.

사용자 정의 통합

커스텀 통합 클래스를 생성하여 사용 가능.

Sentry.init({
  integrations: [new MyCustomIntegration()]
});

세션 재생 (rrweb)

사용자 세션 녹화 및 재생 기능. 주로 복잡한 사용자 행동 진단에 활용.

import * as Sentry from "@sentry/browser";
import { SentryRRWeb } from "@sentry/rrweb";

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  integrations: [new SentryRRWeb({})]
});

테스트 도구: Sentry Testkit

실제 서버 전송 없이 이벤트 수집 확인 가능.

npm install sentry-testkit --save-dev

const { testkit, sentryTransport } = require("sentry-testkit")();
Sentry.init({ transport: sentryTransport });

// 테스트 실행 후
expect(testkit.reports()).toHaveLength(1);

태그: Sentry JavaScript SDK kubernetes cloud-native

7월 15일 03:18에 게시됨

괴물 클럽