Hyunwoo' Blog

배경

실제로 어떤 서비스를 운영하다 보면 런타임 에러가 발생할 수 있다. 이런 에러를 트래킹하고 모니터링하는 것은 서비스의 안정성을 보장하기 위해 필수적이다. 에러 트래킹 도구로 많이 사용하고 있는 Sentry에 대해 자세히 알아보고 싶어 정리하는 시간을 가졌다.

설치법

https://docs.sentry.io/platforms/javascript/guides/nextjs/ 를 보면 알 수 있다. (nextjs 사용한다고 가정)

npx @sentry/wizard@latest -i nextjs 를 통해 깔기전에 아래와 같인 전제조건이 필요하다

A Next.js application (nextjs 어플리케이션)
A Sentry account and project (계정과 프로젝트 세팅)

FEATURES

Sentry에서 제공하는 여러가지 기능에 대해 알아보았다.

1.Capturing Errors - 오류포착

Sentry SDK를 설치하고 나면 우리 에플리케이션의 런타임 시 발생하는 에러는 자동으로 캡쳐되어 보고된다.
즉, 에러를 캡쳐하는 별도의 코드가 필요없다는 이야기이다. 보고된 에러들은 우리 대시보드에서 확인 할 수 있다.

Capturing Errors

SDK를 어플리케이션에 설치해도 우리는 직접적으로 에러를 아래 코드처럼 직접 캡쳐하여 보고 할 수 있다.
그리고 우리는 Error 객체 말고도 non-Error 객체나 string을 전달 할 수도 있다. 대신 당연한 이야기이지만 에러가 아닌 객체나 string을 전달하면 stack trace 정보는 누락될 수 있다.

import * as Sentry from '@sentry/nextjs'
try {
  aFunctionThatMightFail()
} catch (err) {
  Sentry.captureException(err)
}

Capturing Errors in `error.js` Files

Next.js에는 error.js 라는 특별한 기능을 하는 파일이 있다. 이 파일은 프로젝트 내에서 예외가 발생하면 자동으로 호출되면서 fallback UI역할을 한다.
이 파일은 에러 핸들링을 위해서 존재하며 Sentry가 하는 error 핸들링보다 더 우선순위를 갖는다.
즉, error.js 에 의해 핸들링되는 error는 error.js 파일 내부에서 수동으로 에러를 capture해서 리포팅 해야한다.
( 이 부분은 프로젝트 활용 시 주의해야 할 것 같다.)

"use client";
import { useEffect } from "react";
import * as Sentry from "@sentry/nextjs";
export default function ErrorPage({
  error,
}: {
  error: Error & { digest?: string };
}) {
  useEffect(() => {
    // Log the error to Sentry
    Sentry.captureException(error);
  }, [error]);
  return (
    <div>
      <h2>Something went wrong!</h2>
    </div>
  );
}

Capturing Messages

Sentry.captureMessage('Something went wrong')
// optionally specify the severity level:
// "fatal" | "error" | "warning" | "log" | "debug" | "info" (default)
Sentry.captureMessage('Something went wrong', 'warning')

2.Source Maps - 소스 맵

런타임시 발생하는 에러가 리포팅 되면 우리는 스택트레이스를 통해 에러가 발생된 코드를 확인할 수 있다.
그런데 소스맵이 없다면 그 에러가 발생한 코드를 봐도 minified 되어 있기에 읽기가 불편하다.
참고로 소스맵에는 번들 파일의 특정 줄/컬럼 <-> 원본 파일 몇 번째 줄, 파일 경로, 변수/함수명 같은 정보들이 있기에 번들링 되기 전 소스를 파악할 수 있다.

@sentry/nextjs SDK를 설치하면 이런 소스맵은 자동으로 생성되기에 이런 불편함을 해소 할 수 있다. 참고로 소스 맵은 프로덕션 빌드 중에만 생성된다, 즉 next build에서만 생성되고, 개발빌드 (next dev) 에서는 업로드용 소스 맵이 생성되지 않는다고 한다.
필자는 처음에 그런줄도 모르고 왜 Stack trace 정보가 minified 되어있어서 꽤 해메었다.

필자가 직접 테스트해본 결과 소스맵 생성에 있어서 auth token 설정이 필요해 보인다. 처음 sentry 설치시 npx @sentry/wizard@latest -i nextjs 를 통해 설치하면 자동으로 소스맵 생성을 위한 auth token 설정이 된다.(sentry 계정이 존재한다는 가정하에)

만약 auth token 을 발급받지 못했다면 센트리에 접속하여 로그인 하고 좌측패널 Settings -> Developer Settings -> Organization Tokens 에 접속해서 Create New Token 버튼을 클릭하여 생성할 수 있다.
이렇게 생성된 생성된 auth token 을 환경변수에 넣어두고 아래와 같이 next.config.js 에 설정해주면 된다.

// next.config.js
const { withSentryConfig } = require("@sentry/nextjs");
module.exports = withSentryConfig(
  {
    // your existing Next.js config
  },
  {
    ...
    authToken: process.env.SENTRY_AUTH_TOKEN,
 
  },
);

3.Logs (!New) - 로그

런타임시 발생하는 이슈들을 리포팅하는 것 외에도 텍스트 기반 로그 정보를 의도적으로 전송할 수 있다.
그리고 그런 텍스트 기반 로그들을 텍스트 문자열로 검색하거나 개별 속성을 사용하여 검색 할 수 있다.

이 기능은 9.41.0 Sentry SDK 버전 이상부터 사용할 수 있고 이를 사용하기 위해서는 enableLogs 옵션을 true로 설정해야 한다.

사용법

아래와 같이 다른 레벨의 로그를 전송할 수 있다. 6가지가 있다고 한다. ( trace, debug, info, warn, error, 및 fatal)

Sentry.logger.error(Sentry.logger.fmt`Uh oh, something broke, here's the error: '${error}'`)
Sentry.logger.info(Sentry.logger.fmt`'${user.username}' added '${product.name}' to cart.`)

여기서 보면 fmt를 이용하여 로그를 남기면 속성을 삽입하는 형태로 보고 대시보드 로그 UI에서 검색할 수 있고 별도의 열이 추가된다고 한다. 즉, 저 fmt를 이용하지 않고 그냥 literal형태로 남기면 말한 기능들은 안되는 것 같다.

Sentry.logger.trace('Starting database connection', { database: 'users' })
Sentry.logger.debug('Cache miss for user', { userId: 123 })
Sentry.logger.info('Updated profile', { profileId: 345 })
Sentry.logger.warn('Rate limit reached for endpoint', {
  endpoint: '/api/results/',
  isEnterprise: false,
})
Sentry.logger.error('Failed to process payment', {
  orderId: 'order_123',
  amount: 99.99,
})
Sentry.logger.fatal('Database connection pool exhausted', {
  database: 'users',
  activeConnections: 100,
})

그런데 굳이 fmt를 안써도 이렇게 파라미터로 넘겨주면 fmt를 이용하여 로그를 남긴것과 같은 효과를 줄 수 있다고 한다. 결국 선택인 것 같다. 위와 같은 형태는 error message내에 속성들이 포함되진 않는다.

Sentry.getGlobalScope().setAttributes({
  is_admin: true,
  auth_provider: 'sentry',
})
Sentry.withScope((scope) => {
  scope.setAttribute('step', 'authentication')
  // scope attributes `is_admin`, `auth_provider` and `step` are added
  Sentry.logger.info(`user ${user.id} logged in`, { activeSince: 100 })
  Sentry.logger.info(`updated ${user.id} last activity`)
})
// scope attributes `is_admin` and `auth_provider` are added
Sentry.logger.warn('stale website version, reloading page')

10.32.0 이상 부터는 위와 같이 스코프 API를 이용하여 특정 스코프내에서 전역적으로 모든 로그에 특정 속성을 설정할 수 있다고 한다.

여기까지 주요 사용법이다. 이 외에도 여러가지 로깅관련 추가 기능들이 있는데 필요할때 https://docs.sentry.io/platforms/javascript/guides/nextjs/logs/ 를 참고하면 될 것 같다.

4.Session Replay - 세션 다시보기

세션 리플레이 기능은 오류가 발생했을 때의 사용자 행동을 비디오처럼 재현해주는 기능인데 요금을 많이 먹는다. 딱히, 현재하는 프로젝트에서는 사용하지 않을 것 같아 자세히 보지는 않았다. 나중에 필요할때 아래를 참고하면 될 것 같다. https://docs.sentry.io/platforms/javascript/guides/nextjs/session-replay/

5.Tracing - 추적

트레이싱 기능은 에러 트래킹 보단 성능적인 모니터링을 위한 기능으로 보인다.
예를 들어 트랜잭션 단위 실행시간 측정 ( DB 쿼리, 페이지 로드, API호출 등 ) 등을 측정할 수 있을 것으로 보인다. 모든 트랜잭션을 다 측정하기엔 너무 많기에 sample rate를 조정할 수 있다고 한다. 추후 프로젝트를 고도화 할 때 사용해보면 좋을 것 같다. (https://docs.sentry.io/platforms/javascript/guides/nextjs/tracing/)

6.Metrics (Beta) - 메트릭

이 기능 역시 이슈 트래킹 보단 성능 모니터링을 위한 기능으로 보인다. 내용을 확인하면 아래와 같은 기능들로 구성되어 있고 여러 준비된 계측 api를 이용하여 애플리케이션의 성능을 수치적으로 측정할 수 있다. 아직은 베타 버전이라고 한다.

Counter - 버튼이 몇번 눌렀는지와 같은 정보 카운팅

Sentry.metrics.count('button_click', 1)

Gauge - 현재 메모리 사용량과 같은 정보 측정

Sentry.metrics.gauge('queue_depth', 42)

Distribution - 특정 request 단위 성능 측정

Sentry.metrics.distribution('response_time', 187.5)

이 기능 역시 현재 프로젝트에서는 사용되진 않을 것 같고 나중에 필요할때 아래를 참고하면 될 것 같다.
https://docs.sentry.io/platforms/javascript/guides/nextjs/metrics/

7.Profiling - 프로파일링 (브라우저 프로파일링)

우리는 웹 성능을 확인하거나 디버깅할 때 브라우저 개발자 도구를 열고 프로파일링을 할 수 있는데 여기서 말하는 프로파일링도 동일한 의미로 사용된 것이다. 센트리에서 실제 사용자 데이터를 수집하여 사용자환경으로 프로파일링 기능을 제공할수 있다고 한다. 즉, 사용자 환경에서의 성능 모니터링을 할 수 있다는 이야기이다. 참고로 브라우저 프로파일링 API는 현재 크로미움 기반 브라우저에서만 구현되어 있기 크로미움 기반 브라우저 사용자들의 데이터만 수집할 수 있다고 한다. 데이터 수집 샘플링 비율은 설정가능하다고 한다. 나중에 필요할때 아래를 참고하면 될 것 같다. https://docs.sentry.io/platforms/javascript/guides/nextjs/profiling/

목적: 특정 에러가 발생했을 때 이를 추적하고 기록하는 것에 초점
범위: 에러 발생 시점, 스택 트레이스, 사용자 컨텍스트 등 에러 자체에 대한 정보
예시:
- JavaScript 런타임 에러 발생 시 자동으로 캡처
- 에러 발생 빈도 추적
- 에러별 그룹핑 및 중복 제거

모니터링 (Monitoring)

목적: 애플리케이션의 전반적인 상태를 지속적으로 관찰
범위: 성능 메트릭, 리소스 사용량, API 응답 시간등
예시:
- 서버 CPU/메모리 사용률
- API 엔드포인트 응답 시간
- 사용자 세션 추적
- 트랜잭션 성능 분석

관계

에러 트래킹은 모니터링의 한 부분이다. 모니터링이 더 넓은 개념이며, 에러 트래킹은 그 중에서도 에러에 특화된 부분이다.

Sentry는 주로 에러 트래킹 도구로 알려져 있지만, 최근에는 Performance Monitoring 기능도 추가되어 전반적인 모니터링도 가능하다.

Hyunwoo

Sentry

Sentry 기능 정리

목차

배경

설치법