오류 추적

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 Data Source Name 또는 DSN(클라이언트 키)은 비밀이며 공개되어서는 안 됩니다. 누설이 발생한 경우, 다음 단계를 따라 Sentry DSN을 회전하세요:

  1. 개인 엑세스 토큰을 생성하십시오. GitLab.com에서 프로필 사진을 선택한 다음, 환결설정을 선택한 다음 엑세스 토큰을 선택하십시오. 반드시 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에 가입하거나 자체 배포한 Sentry 인스턴스에 가입하십시오.
  2. 새 Sentry 프로젝트를 생성하십시오. 통합하려는 각 GitLab 프로젝트에 대해 새 Sentry 프로젝트를 생성해야 합니다.
  3. Sentry 인증 토큰을 찾거나 생성하십시오. Sentry의 SaaS 버전인 경우, https://sentry.io/api/에서 인증 토큰을 찾거나 생성할 수 있습니다. 토큰에 적어도 다음 스코프를 부여해야 합니다: project:read, event:read, 그리고 event:write (이벤트 해결을 위해).
  4. GitLab에서 오류 추적을 활성화하고 구성하십시오:
    1. 왼쪽 사이드바에서 검색 또는 이동을 선택하여 프로젝트를 찾으십시오.
    2. 설정 > 모니터 > 오류 추적을 선택하십시오.
    3. 오류 추적 활성화 아래에서 활성 확인란을 선택하십시오.
    4. 오류 추적 백엔드 아래에서 Sentry를 선택하십시오.
    5. Sentry API URL 아래에 Sentry 호스트명을 입력하십시오. 예를 들어, https://sentry.example.com을 입력하십시오. Sentry의 SaaS 버전인 경우, 호스트명은 https://sentry.io입니다.
    6. 인증 토큰 아래에 이전에 생성한 토큰을 입력하십시오.
    7. Sentry와의 연결을 테스트하고 프로젝트 드롭다운 목록을 채우려면 연결을 선택하십시오.
    8. 프로젝트 목록에서 GitLab 프로젝트에 연결할 Sentry 프로젝트를 선택하십시오.
    9. 변경 사항 저장을 선택하십시오.

이제 프로젝트 사이드바의 모니터 > 오류 추적을 방문하여 Sentry 오류의 목록을 보기 할 수 있습니다.

Sentry의 GitLab 통합

Sentry 설명서의 단계에 따라 Sentry의 GitLab 통합을 활성화하려고 할 수도 있습니다.

GitLab Runner 활성화

GitLab Runner를 Sentry와 구성하려면 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일의 유지 기간 제한을 가지고 있습니다.

문제 해결

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

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

프로젝트 설정에서 모니터 기능이 비활성화되어 있으면 프로젝트의 Sentry 통합을 활성화하려고 시도할 때 오류가 발생할 수 있습니다. 결과적으로 /project/path/-/error_tracking/projects.json?api_host=https:%2F%2Fsentry.example.com%2F&token=<token>로 보내는 요청은 404 상태를 반환합니다.

이 문제를 해결하려면 프로젝트의 모니터 기능을 활성화하세요.