에러 추적

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

에러 추적은 개발자가 응용 프로그램에서 생성된 오류를 발견하고 볼 수 있도록 합니다. 오류 정보가 코드를 개발하는 위치에 표시되기 때문에 효율성과 인식이 증가합니다. 사용자는 GitLab 통합 오류 추적 및 Sentry 기반 백엔드 중에서 선택할 수 있습니다.

에러 추적 버그 또는 기능에 대한 피드백을 남기려면 피드백 이슈에 댓글을 남기거나 새 이슈를 열어주세요.

에러 추적 작동 방식

에러 추적을 작동시키려면 다음이 필요합니다:

  • Sentry SDK로 구성된 응용 프로그램: 오류가 발생하면 Sentry SDK가 관련 정보를 캡처하고 네트워크를 통해 백엔드로 보냅니다. 백엔드는 모든 오류에 관한 정보를 저장합니다.

  • 오류 추적 백엔드: 백엔드는 GitLab 자체이거나 Sentry일 수 있습니다. GitLab인 경우에는 별도의 백엔드를 설정할 필요가 없기 때문에 _통합 오류 추적_으로 지칭합니다. 제품의 일부로 이미 구현되어 있습니다.

    선택한 백엔드에 관계없이 오류 추적 UI는 동일합니다.

통합 오류 추적

Tier: Free, Premium, Ultimate Offering: GitLab.com

본 안내서는 다양한 언어의 예제를 사용하여 프로젝트에 대한 오류 추적을 설정하는 기본 기능을 제공합니다.

GitLab Observability에서 제공하는 오류 추적은 Sentry SDK를 기반으로 합니다. 응용 프로그램에서 Sentry SDK를 어떻게 사용할 수 있는지에 대한 보다 자세한 예제는 Sentry SDK 문서를 확인하세요.

Sentry 데이터 모델에 따르면 항목 유형은 다음과 같습니다:

프로젝트에 대한 오류 추적 활성화

사용하는 프로그래밍 언어에 관계없이 GitLab 프로젝트에 대한 오류 추적을 먼저 활성화해야 합니다.

본 가이드에서는 GitLab.com 인스턴스를 사용합니다.

전제 조건:

  • 오류 추적을 활성화하려는 프로젝트가 있어야 합니다. 새 프로젝트를 만드는 방법은 프로젝트 만들기를 참조하세요.

GitLab을 백엔드로 사용하여 오류 추적을 활성화하려면:

  1. 프로젝트에서 설정 > 모니터링으로 이동합니다.
  2. 오류 추적을 확장합니다.
  3. 오류 추적 활성화 아래 활성 확인란을 선택합니다.
  4. 오류 추적 백엔드에서 GitLab을 선택합니다.

  5. 변경 사항 저장을 선택합니다.

  6. 데이터 소스 이름(DSN) 문자열을 복사합니다. 이것은 SDK 구현을 구성하는 데 필요합니다.

에러 추적 디렉터리

응용 프로그램이 Sentry SDK를 통해 오류를 에미트한 후, 해당 오류는 모니터 > 오류 추적 탭/섹션에서 확인할 수 있어야 합니다.

MonitorListErrors

에러 추적 세부 정보

에러 세부 정보 보기에서는 예외의 자세한 정보와 발생 횟수, 영향을 받는 사용자, 처음으로 본 날짜, 최근에 본 날짜 등을 볼 수 있습니다.

또한 스택 추적을 검토할 수 있습니다.

MonitorDetailErrors

오류 발생

지원되는 언어 SDK 및 Sentry 유형

다음 표는 Sentry SDK를 통해 사용할 수 있는 모든 이벤트 유형 및 GitLab 에러 추적에서 지원되는지 여부를 보여줍니다.

언어 테스트된 SDK 클라이언트 및 버전 엔드포인트 지원되는 항목 유형
Go sentry-go/0.20.0 store exception, message
Java sentry.java:6.18.1 envelope exception, message
NodeJS sentry.javascript.node:7.38.0 envelope exception, message
PHP sentry.php/3.18.0 store exception, message
Python sentry.python/1.21.0 envelope exception, message, session
Ruby sentry.ruby:5.9.0 envelope exception, message
Rust sentry.rust/0.31.0 envelope exception, message, session

이 표의 자세한 버전은 이 이슈를 참조하세요.

사용 예제

모든 지원되는 언어 SDK에 대한 작동 예제를 찾을 수 있습니다. 나열된 프로그램 각각은 해당 SDK를 사용하여 예외, 이벤트 또는 메시지를 캡처하는 기본 예제를 보여줍니다.

더 자세한 문서는 사용한 언어에 따라 Sentry SDK 문서를 참조하세요.

생성된 DSN 회전

Sentry 데이터 소스 이름 또는 DSN(클라이언트 키)은 비밀이어야 하며 공개되어서는 안 됩니다. 유출이 발생한 경우 다음 단계를 따라 Sentry DSN을 회전하세요:

  1. GitLab.com에서 프로필 사진을 선택한 후 Personaal Access Token 만들기를 선택하여 액세스 토큰을 생성합니다. API 스코프를 추가하는지 확인하세요.

  2. 오류 추적 API를 사용하여 새 Sentry DSN을 생성하세요: 

    curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"
--header "Content-Type: application/json" \
   "https://gitlab.example.com/api/v4/projects/<your_project_number>/error_tracking/client_keys"

  3. 사용 가능한 클라이언트 키(Sentry DSN)를 가져옵니다. 새로 생성된 Sentry DSN이 제대로 들어 있는지 확인하세요. 그런 다음 이전 클라이언트 키의 키 ID를 메모해두세요: 

    curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/<your_project_number>/error_tracking/client_keys"

  4. 이전 클라이언트 키를 삭제하세요. 

    curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/<your_project_number>/error_tracking/client_keys/<key_id>"

SDK 이슈 디버그

Sentry에서 지원하는 대부분의 언어는 초기화의 일환으로 debug 옵션을 노출합니다. 이것은 오류를 전송하는 문제를 디버깅하는 데 도움이 될 수 있습니다. 그렇지 않으면, API로 전송하기 전에 JSON을 출력할 수 있는 옵션이 있습니다.

Sentry 오류 추적

Sentry는 오픈 소스 오류 추적 시스템입니다. GitLab은 관리자가 Sentry를 GitLab에 연결하여 사용자가 GitLab에서 Sentry 오류 디렉터리을 볼 수 있도록 허용합니다.

Sentry 배포

클라우드 호스팅 Sentry에 가입하거나 자체 온프레미스 인스턴스를 배포할 수 있습니다.

프로젝트에 대한 Sentry 통합 활성화

GitLab은 Sentry를 프로젝트에 연결할 수 있는 방법을 제공합니다.

필수 사항:

  • 프로젝트에 대한 최소한 Maintainer 역할이 있어야 합니다.

Sentry 통합을 활성화하려면:

  1. Sentry.io에 가입하거나 자체 배포를 진행합니다.
  2. 새 Sentry 프로젝트 생성. 통합하려는 각 GitLab 프로젝트에 대해 새 Sentry 프로젝트를 만들어야 합니다.
  3. Sentry auth 토큰 찾기 또는 생성. Sentry의 SaaS 버전의 경우, https://sentry.io/api/에서 auth 토큰을 찾거나 생성할 수 있습니다. 해당 토큰에는 적어도 다음 범위를 제공해야 합니다: project:read, event:read, 그리고 event:write (이벤트 해결용).
  4. GitLab에서 오류 추적을 활성화하고 구성하십시오:
    1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
    2. Settings > Monitor > Error Tracking을 선택합니다.
    3. 오류 추적 활성화 아래 활성 확인란을 선택합니다.
    4. 오류 추적 백엔드에서 Sentry를 선택합니다.
    5. Sentry API URL에 Sentry 호스트명을 입력합니다. 예를 들어, https://sentry.example.com을 입력합니다. Sentry의 SaaS 버전의 경우 호스트명은 https://sentry.io입니다.
    6. Auth Token에 이전에 생성한 토큰을 입력합니다.
    7. Sentry와의 연결을 테스트하고 프로젝트 드롭다운 디렉터리을 채우려면 연결을 선택합니다.
    8. 프로젝트 디렉터리에서 GitLab 프로젝트에 연결할 Sentry 프로젝트를 선택합니다.
    9. 변경 사항 저장을 선택합니다.

이제 프로젝트의 사이드바에서 Monitor > Error Tracking을 방문하여 Sentry 오류 디렉터리을 볼 수 있습니다.

Sentry의 GitLab 통합

Sentry의 GitLab 통합을 활성화하려면 Sentry 문서의 단계를 따를 수도 있습니다.

GitLab Runner 활성화

Sentry와 GitLab Runner를 구성하기 위해, config.toml 구성 파일에 sentry_dsn 값을 추가해야 합니다. 이 값은 고급 구성에서 참조됩니다.

Sentry 설정 중 프로젝트 유형을 설정하라는 요청이 오면 Go를 선택하세요.

다음 오류를 해결하려면, Sentry.io > Project Settings > Client Keys (DSN) > Show deprecated DSN에서 사용되지 않는 DSN을 지정하세요. 

ERROR: Sentry failure builds=0 error=raven: dsn missing private key

데이터 유지 기간

GitLab은 모든 오류에 대해 90일의 유지 제한을 가지고 있습니다.

문제 해결

오류 추적 작업 중에 다음과 같은 문제가 발생할 수 있습니다.

오류 연결 실패. 인증 토큰을 확인하고 다시 시도하십시오

프로젝트 설정에서 Monitor 기능이 비활성화된 경우, 프로젝트에 대한 Sentry 통합을 활성화하려고 하면 오류가 발생할 수 있습니다. 결과적으로 /project/path/-/error_tracking/projects.json?api_host=https:%2F%2Fsentry.example.com%2F&token=<token>로 요청하면 404 상태가 반환될 수 있습니다.

이 문제를 해결하려면 프로젝트의 Monitor 기능을 활성화하십시오.