분산 추적 개발 가이드라인

GitLab 애플리케이션에서 분산 추적을 설정하고 사용하는 방법과 Jaeger를 이용한 요청 추적 방법을 설명합니다.

GitLab은 분산 추적(distributed tracing)을 위해 계측(instrumentation)되어 있습니다. GitLab의 분산 추적은 GitLab.com에서 대규모로 아직 테스트되지 않았기 때문에 현재 실험적 인 것으로 간주됩니다. Open Tracing 에 따르면: 분산 요청 추적(distributed request tracing)이라고도 불리는 분산 추적은 애플리케이션, 특히 마이크로서비스 아키텍처로 구축된 애플리케이션을 프로파일링하고 모니터링하는 데 사용되는 방법입니다. 분산 추적은 장애가 발생하는 위치와 성능 저하의 원인을 정확히 파악하는 데 도움을 줍니다. 분산 추적은 특히 요청이 GitLab 애플리케이션의 다양한 구성 요소를 통과하는 생명 주기를 이해하는 데 유용합니다. 현재 Workhorse, Rails, Sidekiq, Gitaly가 추적 계측을 지원합니다. 분산 추적은 비활성화된 경우 오버헤드가 최소화되며, 활성화된 경우에도 오버헤드가 매우 작기 때문에 프로덕션 환경을 포함한 모든 환경에서 사용 가능합니다. 이러한 이유로 프로덕션 문제, 특히 성능 문제를 진단하는 데 유용하게 활용할 수 있습니다. 서비스별로 분산 추적 지원 수준이 다릅니다. 가장 일반적인 라이브러리를 위한 기본 제공(pre-built) 계측 외에도 애플리케이션 레이어에 커스텀 계측 코드를 추가해야 합니다. 서비스별 정보는 다음을 참조하세요: Gitaly 로컬 개발을 위한 Jaeger 사용 상관 관계 ID를 사용한 분산 요청 조사 # GitLab 애플리케이션은 요청의 다양한 구성 요소 간에 상관 관계 ID(correlation ID)를 전달합니다. 상관 관계 ID는 단일 요청에 고유한 토큰으로, 서로 다른 GitLab 하위 시스템(예: Rails, Workhorse) 간의 단일 요청을 연관 짓는 데 사용됩니다. 상관 관계 ID는 로그 출력에 포함되기 때문에 엔지니어는 상관 관계 ID를 이용해 서로 다른 하위 시스템의 로그를 연관 짓고 시스템을 통한 요청의 엔드투엔드 경로를 더 잘 이해할 수 있습니다. 요청이 프로세스 경계를 넘을 때 상관 관계 ID가 나가는 요청에 주입됩니다. 이를 통해 각 다운스트림 하위 시스템으로 상관 관계 ID가 전파됩니다. 상관 관계 ID는 일반적으로 특정 웹 요청에 대한 응답으로 Rails 애플리케이션에서 생성됩니다. 일부 사용자 대면 시스템은 사용자 요청(예: SSH를 통한 Git push)에 대한 응답으로 상관 관계 ID를 생성하지 않습니다. 상관 관계 ID 작업을 위한 개발자 가이드라인 # 새로운 시스템에 추적을 통합할 때 개발자는 상관 관계 ID에 대한 특정 가정을 피해야 합니다. 다음 가이드라인은 GitLab의 모든 하위 시스템에 적용됩니다: 상관 관계 ID는 항상 선택 사항(optional)입니다. 추적이 아닌 기능이 업스트림 시스템의 상관 관계 ID 존재에 의존하게 해서는 안 됩니다. 상관 관계 ID는 항상 자유 텍스트(free text)입니다. 상관 관계 ID는 컨텍스트(예: 사용자 이름 또는 IP 주소)