오류 추적

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 옵저버빌리티에서 제공하는 오류 추적은 Sentry SDK를 기반으로 합니다. 애플리케이션에서 Sentry SDK를 사용하는 방법에 대한 보다 심층적인 예제는 Sentry SDK 문서를 확인하세요.

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

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

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

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

전제 조건:

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

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

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

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

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

사용자 추적 구성

오류로 영향을 받는 사용자 수를 추적하려면:

  • 기기 코드에서 각 사용자가 고유하게 식별되는 것을 확인합니다.

    사용자 식별에는 사용자 ID, 이름, 이메일 주소 또는 IP 주소를 사용할 수 있습니다.

    예를 들어, Python을 사용하면 이메일로 사용자를 식별할 수 있습니다. 

    Sentry.setUser({ email: "john.doe@example.com" });

    사용자 식별에 대한 자세한 정보는 Sentry 문서를 참조하세요.

오류 추적 디렉터리

애플리케이션이 Sentry SDK를 통해 오류를 Error Tracking API에 보내면 해당 오류는 모니터 > 오류 추적 탭/섹션 하에 사용 가능해야 합니다.

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에서 프로필 사진을 선택한 후 환경 설정을 선택한 다음 액세스 토큰을 선택합니다. 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에 가입하거나 본사에 kpremise 인스턴스를 배포할 수 있습니다.

프로젝트에 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 활성화

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

Sentry를 설정하는 동안 프로젝트 유형을 묻는 경우 Go를 선택하세요.

다음 오류를 해결하려면, Sentry.io > 프로젝트 설정 > 클라이언트 키 (DSN) > Deprecated DSN 표시에서 더 이상 사용되지 않는 DSN을 명시하세요. 

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

막대 그래프 데이터 분석

가장 최근 보고된 타임스탬프는 오류 자체에 대한 구체적인 세부 정보를 제공합니다. 상자 위에 마우스를 가져다 대면 오류가 마지막으로 발생한 구체적인 타임스탬프를 볼 수 있습니다. 다음 예제에서는 오류가 CEST 11:41에 발생했습니다.

MonitorDetailErrors

아래 그래프는 시간 간격별로 메트릭되며, 해당 시간 동안의 오류 총 수를 세어놓은 것입니다. 이 예에서는 오전 11시에 239개의 오류가 있었습니다. 마지막으로 본 시간 필드는 11시로 표시되며, 해당 시간이 완전히 지나기 전까지는 업데이트되지 않습니다. 이는 이 호출에 사용하는 라이브러리(import * as timeago from 'timeago.js') 때문입니다.

MonitorDetailErrors

데이터 보유

GitLab은 모든 오류에 대해 90일의 보유 기간을 설정합니다.

문제 해결

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

오류 Connection failed. Check auth token and try again

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

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