Sentry CLI 21.8.x 버전 기준 설치 및 활용 가이드

설치 방법

Sentry CLI는 다양한 운영 체제와 환경에서 사용할 수 있도록 여러 설치 옵션을 제공합니다.

수동 다운로드

GitHub 릴리스 페이지에서 각 플랫폼(Linux, macOS, Windows)에 맞는 실행 파일을 직접 다운로드할 수 있습니다. 받은 파일을 sentry-cli 또는 sentry-cli.exe로 이름을 변경하여 사용하면 됩니다.

자동 설치 스크립트 (macOS/Linux)

cURL 명령어를 통해 최신 버전을 자동으로 설치할 수 있습니다:

curl -sL https://sentry.io/get-cli/ | bash

설치 후 관리자 권한이 필요할 경우 sudo 비밀번호 입력을 요청할 수 있습니다. 정상 설치 여부는 다음 명령어로 확인 가능합니다:

sentry-cli --help

NPM을 통한 설치

빌드 서버나 CI 환경에서는 npm 패키지를 활용하는 것이 편리합니다:

npm install @sentry/cli

설치 후 프로젝트 내에서 다음과 같이 실행할 수 있습니다:

./node_modules/.bin/sentry-cli --help

전역 설치 시에는 --unsafe-perm 플래그가 필요할 수 있으나, 일반적으로 추천하지 않습니다:

sudo npm install -g @sentry/cli --unsafe-perm

커스텀 CDN 설정

기본적으로 Fastly 기반 CDN에서 바이너리를 다운로드하지만, 내부 미러를 사용하려면 다음 중 하나의 방법으로 설정할 수 있습니다:

  • NPM config 지정: 
    npm install @sentry/cli --sentrycli_cdnurl=https://my-mirror.local/path
  • .npmrc 파일에 추가: 
    sentrycli_cdnurl=https://my-mirror.local/path
  • 환경 변수 사용: 
    SENTRYCLI_CDNURL=https://my-mirror.local/path npm install @sentry/cli

패키지 매니저 사용

macOS 사용자는 Homebrew로 간편하게 설치할 수 있습니다:

brew install getsentry/tools/sentry-cli

Windows 사용자는 Scoop을 이용할 수 있습니다:

scoop install sentry-cli

Docker 이미지 활용

특정 환경이나 CI 파이프라인에서는 Docker 이미지를 사용하는 것이 유용합니다:

docker pull getsentry/sentry-cli
docker run --rm -v $(pwd):/work getsentry/sentry-cli --help

현재 디렉터리를 /work에 마운트하여 로컬 파일 접근이 가능하도록 구성됩니다.

인증 및 환경 설정

대부분의 CLI 기능은 Sentry 인스턴스와의 인증이 필요합니다. 다음 범위(scope)를 포함하는 토큰이 요구됩니다:

  • project:read
  • project:releases
  • org:read

로그인 절차

간편한 인터랙티브 로그인:

sentry-cli login

자체 호스팅 환경일 경우 URL을 명시해야 합니다:

sentry-cli --url https://my-sentry-server.com/ login

수동 토큰 설정

다음 중 한 가지 방법으로 인증 정보를 제공할 수 있습니다:

  • 환경 변수: 
    export SENTRY_AUTH_TOKEN=your_token_here
  • 명령어 인자: 
    sentry-cli --auth-token your_token_here [command]
  • 설정 파일(~/.sentryclirc): 
    [auth]
token = your_token_here

기타 구성 항목

다음과 같은 주요 설정값을 환경 변수 또는 설정 파일로 지정할 수 있습니다:

환경 변수 설명
SENTRY_URL Sentry 서버 주소 (기본값: https://sentry.io)
SENTRY_ORG 조직 식별자(slug)
SENTRY_PROJECT 프로젝트 식별자(slug)
SENTRY_LOG_LEVEL 로그 출력 수준(info, warn 등)
SENTRY_HTTP_MAX_RETRIES 업로드 재시도 횟수

설정 확인

구성 상태를 점검하려면 다음 명령을 사용하세요:

sentry-cli info

릴리스 관리

Sentry CLI는 애플리케이션 배포와 연계된 릴리스 정보를 관리하는 핵심 도구입니다.

릴리스 생성

새 릴리스를 생성하려면 고유한 버전 식별자가 필요합니다:

sentry-cli releases new "v1.0.0"

릴리스 이름은 특수 문자(/,\,공백 등)를 포함할 수 없으며 최대 200자까지 가능합니다. 모바일 앱의 경우 package@version 형식을 권장합니다.

자동 버전 제안

Git 저장소 기반 프로젝트에서는 커밋 해시를 기반으로 한 버전을 자동 생성할 수 있습니다:

VERSION=$(sentry-cli releases propose-version)

릴리스 완료 처리

생성된 릴리스는 기본적으로 미완료 상태이며, 다음 명령으로 완료 상태로 전환할 수 있습니다:

sentry-cli releases finalize "v1.0.0"

또는 생성 시 바로 완료 처리할 수 있습니다:

sentry-cli releases new "v1.0.0" --finalize

커밋 연동

릴리스에 관련된 커밋을 자동으로 연결할 수 있습니다:

sentry-cli releases set-commits "v1.0.0" --auto

저장소 접근이 불가능한 환경에서는 수동으로 커밋을 지정할 수 있습니다:

sentry-cli releases set-commits "v1.0.0" --commit "repo-name@abc123def"

이전 커밋 기준을 명시하려면 범위를 지정합니다:

sentry-cli releases set-commits "v1.0.0" --commit "repo-name@prev..current"

아티팩트 업로드

특히 JavaScript 프로젝트에서는 소스맵을 업로드하여 오류 추적 정확도를 높일 수 있습니다:

sentry-cli releases files "v1.0.0" upload-sourcemaps ./dist/js

주요 옵션:

  • --url-prefix: 원격 경로 접두사 지정 (예: ~/static/js)
  • --strip-common-prefix: 공통 로컬 경로 제거
  • --ignore-file .sentryignore: 무시할 파일 패턴 지정
  • --validate: 업로드 전 소스맵 유효성 검사

배포(Deploy) 기록

릴리스를 특정 환경에 배포했음을 기록할 수 있습니다:

sentry-cli releases deploys "v1.0.0" new -e production

배포 시간도 함께 기록할 수 있습니다:

start_time=$(date +%s)
# ... 배포 작업 수행 ...
end_time=$(date +%s)
sentry-cli releases deploys "v1.0.0" new -e staging -t $((end_time - start_time))

디버그 심볼 관리

네이티브 앱(iOS, Android 등)의 충돌 분석을 위해 디버그 심볼 파일(dSYM, PDB 등)을 업로드할 수 있습니다.

파일 확인

업로드 가능한 디버그 정보 파일인지 확인:

sentry-cli difutil check MyApp.app.dSYM

디버그 파일 업로드

다음 명령어로 디버그 심볼을 업로드합니다:

sentry-cli upload-dif -o my-org -p my-project /path/to/symbols

서버 처리 완료까지 대기하려면 --wait 플래그를 사용합니다:

sentry-cli upload-dif --wait -o my-org -p my-project /path/to/symbols

소스 번들 생성

스택 트레이스에 소스 코드 컨텍스트를 표시하기 위해 소스 번들을 생성할 수 있습니다:

sentry-cli difutil bundle-sources /path/to/debug/files

업로드 시 즉시 생성하려면:

sentry-cli upload-dif --include-sources /path/to/files

ProGuard 매핑 파일 업로드 (Android)

난독화된 Android 앱의 역추적을 위해 ProGuard 매핑 파일을 업로드합니다:

sentry-cli upload-proguard \
  --write-properties app/build/generated/sentry.properties \
  app/build/outputs/mapping/release/mapping.txt

--write-properties 옵션은 UUID 값을 속성 파일에 자동으로 기록합니다.

이벤트 전송

테스트 목적이나 스크립트 오류 모니터링을 위해 CLI를 통해 직접 이벤트를 전송할 수 있습니다. 먼저 DSN을 설정해야 합니다:

export SENTRY_DSN=https://public-key@o0.ingest.sentry.io/0

기본 메시지 전송

sentry-cli send-event -m "서비스 시작 완료"

파라미터화된 메시지

sentry-cli send-event -m "사용자 %s 생성됨" -a "alice"

로그 파일 및 추가 데이터

로그 파일을 크럼블(빵조각) 형태로 포함할 수 있습니다:

sentry-cli send-event -m "실패 발생" --logfile app.log

태그와 추가 정보도 전달 가능:

sentry-cli send-event -m "오류" -t env:prod -e user_id:123

Bash 오류 훅

스크립트에서 발생하는 오류를 자동으로 전송하려면 다음을 사용합니다:

#!/bin/bash
export SENTRY_DSN=https://public-key@o0.ingest.sentry.io/0
eval "$(sentry-cli bash-hook)"
# 스크립트 본문

이후 스크립트 내에서 처리되지 않은 오류는 자동으로 Sentry로 전송됩니다.

태그: sentry-cli debugging sourcemaps release-management error-tracking

5월 26일 15:10에 게시됨

인기 태그

©2026 괴물 클럽