분산 추적 개발 지침
GitLab은 분산 추적을 위해 계측되어 있습니다. 현재 GitLab의 분산 추적은 실험적으로 간주되며, 아직 GitLab.com에서 대규모로 테스트되지 않았습니다.
Open Tracing에 따르면:
분산 추적 또는 분산 요청 추적은 특히 마이크로서비스 아키텍처를 사용하여 구축된 응용 프로그램을 프로필링하고 모니터링하는 데 사용되는 방법입니다. 분산 추적은 실패가 발생하는 지점을 정확히 파악하고 불성능의 원인을 파악하는 데 도움이 됩니다.
분산 추적은 GitLab 응용 프로그램의 다른 컴포넌트를 통해 요청의 라이프사이클을 이해하는 데 특히 도움이 됩니다. 현재 Workhorse, Rails, Sidekiq 및 Gitaly는 추적 계측을 지원합니다.
분산 추적은 비활성화된 경우에는 최소한의 오버헤드를 추가하지만, 활성화된 경우에는 소규모의 오버헤드만 부과하여 제품 환경을 포함한 모든 환경에서 사용할 수 있습니다. 그 이유로 인해 특히 성능 문제를 진단하는 데 유용할 수 있습니다.
서비스에는 분산 추적을 지원하는 다양한 수준이 있습니다. 가장 일반적인 라이브러리에 대한 미리 구축된 계측 외에 응용 프로그램 계층에 사용자 정의 계측 코드를 추가해야 합니다.
서비스별 정보는 다음을 참조하십시오:
분산 요청 조사를 위한 상관 ID 사용
GitLab 응용 프로그램은 요청에서 다양한 컴포넌트 사이에 상관 ID를 전달합니다. 상관 ID는 요청 당 하나의 고유한 토큰으로, 요청이 시스템의 다른 GitLab 부분(예: Rails, Workhorse) 간에 연결되는 데 사용됩니다. 로그 출력에 상관 ID가 포함되어 있기 때문에 엔지니어들은 상관 ID를 사용하여 다른 부분의 로그를 연관시키고 시스템을 통해 요청의 최종 경로를 더 잘 이해할 수 있습니다. 요청이 프로세스 경계를 통과할 때 상관 ID가 대상 요청에 주입됩니다. 이를 통해 상관 ID가 각 하류 부속 시스템으로 전파됩니다.
일부 사용자가 특정 웹 요청에 대해 상관 ID를 생성하므로, 상관 ID를 생성하는 Rails 응용 프로그램에 일반적으로 생성됩니다. 일부 사용자 지향 시스템은 사용자 요청에 대해 상관 ID를 생성하지 않습니다(예: SSH를 통한 Git 푸시).
상관 ID 작업 개발 지침
새 시스템에 추적을 통합할 때, 개발자는 상관 ID에 대해 특정 가정을 하지 않아야 합니다. 다음 가이드라인은 GitLab의 모든 부속 시스템에 적용됩니다:
- 상관 ID는 항상 선택 사항입니다.
- 추적 기능 외에도 상관 ID의 존재에 의존하는 것을 절대로 하면 안 됩니다.
- 상관 ID는 항상 자유 텍스트입니다.
- 상관 ID는 컨텍스트를 전달하기 위해 사용해서는 안 됩니다(예: 사용자 이름 또는 IP 주소).
- 상관 ID는 절대로 _구문 분석되지 않아_야 하며 다른 방식으로 조작해서도 안 됩니다(예: 분할).
LabKit 라이브러리는 Go 프로그래밍 언어에서 GitLab 상관 ID를 처리하는 표준화된 인터페이스를 제공합니다. LabKit은 상관 ID에서 추적 및 상관 ID를 사용하는 개발자들을위한 참조 구현으로 사용할 수 있습니다.
분산 추적 활성화
GitLab은 분산 추적을 구성하기 위해 GITLAB_TRACING
환경 변수를 사용합니다. 이 구성은 모든 컴포넌트(예: Workhorse, Rails 등)에 대해 동일하게 사용됩니다.
GITLAB_TRACING
가 설정되지 않은 경우, 응용 프로그램이 계측되지 않으므로 전혀 오버헤드가 없습니다.
GITLAB_TRACING
를 활성화하려면 URL과 유사한 형식의 유효한 “구성 문자열” 값을 설정해야 합니다:
GITLAB_TRACING=opentracing://<driver>?<param_name>=<param_value>&<param_name_2>=<param_value_2>
이 예에서는 다음의 가상값이 있습니다:
-
driver
: Jaeger와 같은 드라이버. -
param_name
,param_value
: 이들은 드라이버별 구성 값입니다. Jaeger의 구성 매개변수는 이 문서의 나중에 자세히 설명됩니다. URL 인코딩되어야 합니다. 여러 값은 URL과 같이&
문자로 구분되어야 합니다.
GitLab Rails은 요청의 자세한 보기를 제공하는 일반적 유형의 작업을 위해 사전에 구현된 계측을 제공합니다. 그러나 자세한 정보는 비용이 발생합니다. 결과 트레이스는 길고 큰 근간 문제를 식별하기 어렵게 만들 수 있습니다. 이러한 우려사항에 대응하기 위해 일부 계측은 기본적으로 비활성화되어 있습니다. 비활성화된 계측을 활성화하려면 다음 환경 변수를 설정하십시오:
-
GITLAB_TRACING_TRACK_CACHES
: 캐시 읽기, 쓰기 또는 삭제와 같은 캐시 작업 추적 활성화. -
GITLAB_TRACING_TRACK_REDIS
: Redis 작업 추적 활성화. 대부분의 Redis 작업은 캐싱을 위한 것입니다.
GitLab 개발 키트에서 Jaeger 사용
GitLab에서 지원하는 첫 번째 추적 구현은 Jaeger이며, GitLab 개발 키트는 Jaeger를 지원하여 분산 추적을 즉시 사용할 수 있게 합니다. GDK는 서비스에 GITLAB_TRACING
환경 변수를 자동으로 추가합니다.
gdk.yml
파일을 편집하여 GDK를 Jaeger에 구성하십시오:
tracer:
build_tags: tracer_static tracer_static_jaeger
jaeger:
enabled: true
listen_address: 127.0.0.1
version: 1.43.0
gdk.yml
파일을 수정한 후 gdk reconfigure
명령을 실행하여 GDK를 다시 구성하십시오. 이렇게 하면 GDK가 올바르게 구성되어 사용할 수 있습니다.
위 구성은 Go로 작성된 서비스를 처음으로 다시 빌드할 때 tracer_static
와 tracer_static_jaeger
빌드 태그를 설정합니다. 이후에 수행한 변경 사항은 해당 빌드 태그로 다시 빌드해야 합니다. 다음과 같이 수행할 수 있습니다:
- 기본 빌드 태그 집합에 이러한 빌드 태그를 추가합니다.
- 빌드 명령에 매뉴얼으로 첨부합니다. 예: Gitaly는 기본적으로 빌드 태그를 추가할 수 있습니다.
make all WITH_BUNDLED_GIT=YesPlease BUILD_TAGS="tracer_static tracer_static_jaeger"
를 실행할 수 있습니다.
구성을 다시 한 후, Jaeger 대시보드는 http://localhost:16686
에서 사용할 수 있습니다. GDK 환경에서 추적을 사용하는 다른 방법은 성능 표시줄을 통해 추적에 액세스하는 것입니다. 이는 브라우저 창에 p
b
를 입력하여 표시할 수 있습니다.
성능 표시줄을 활성화한 후 Trace를 선택하여 Jaeger UI로 이동할 수 있습니다.
Jaeger 검색 UI는 현재 요청의 Correlation-ID
에 대한 쿼리를 반환합니다. 이 검색은 단일 추적 결과를 반환해야 합니다. 이 결과를 선택하면 계층 구분된 시간선에서 추적의 세부 정보가 표시됩니다.
GitLab Developer Kit 없이 Jaeger 사용
분산 추적은 디버깅을 위해 개발 환경뿐만 아니라 프로덕션 또는 스테이징 환경에서도 활성화할 수 있습니다. 현재 이 기능은 실험적으로 제공되며 현재 프로덕션 환경에서는 지원되지 않습니다. 이 최초 릴리스에서는 개발 환경에서의 디버깅에 사용되도록 의도되었습니다.
Jaeger 추적을 사용하려면 3단계 프로세스를 통해 활성화할 수 있습니다:
1. Jaeger 시작
Jaeger에는 많은 구성 옵션이 있지만 메모리를 사용하는 “모든인원(all-in-one)” 모드로 시작하는 것이 쉬움이 큰 장점입니다. “모든인원” 모드의 주요 이점은 사용 편의성입니다.
자세한 구성 옵션에 대해서는 Jaeger 문서를 참조하십시오.
Docker 사용
Docker를 사용할 수 있는 경우, Jaeger all-in-one을 실행하는 더 쉬운 접근 방법은 다음 명령을 사용하여 Docker를 통해 실행하는 것입니다.
$ docker run \
--rm \
-e COLLECTOR_ZIPKIN_HTTP_PORT=9411 \
-p 5775:5775/udp \
-p 6831:6831/udp \
-p 6832:6832/udp \
-p 5778:5778 \
-p 16686:16686 \
-p 14268:14268 \
-p 9411:9411 \
jaegertracing/all-in-one:latest
Jaeger 프로세스 사용
Docker를 사용하지 않을 경우, all-in-one 프로세스를 설정하는 것은 여전히 쉽습니다.
- 플랫폼에 맞는 최신 Jaeger 릴리스를 다운로드하세요.
- 아카이브를 해제하고
bin/all-in-one
프로세스를 실행하세요.
이렇게 하면 기본 수신 포트로 프로세스가 시작됩니다.
2. GITLAB_TRACING
환경 변수 구성
Jaeger를 실행한 후, 적절한 구성 문자열로 GITLAB_TRACING
변수를 구성하세요.
모든 것을 동일한 호스트에서 실행 중인 경우, 다음 값을 사용하세요.
export GITLAB_TRACING="opentracing://jaeger?http_endpoint=http%3A%2F%2Flocalhost%3A14268%2Fapi%2Ftraces&sampler=const&sampler_param=1"
이 구성 문자열은 Jaeger 드라이버 opentracing://jaeger
를 사용하며 다음 옵션을 포함합니다.
이름 | 값 | 설명 |
---|---|---|
http_endpoint
| http://localhost:14268/api/traces
| Jaeger를 구성하여 http://localhost:14268/ 에서 실행 중인 HTTP 엔드포인트로 추적 정보를 전송합니다. 대안으로 upd_endpoint 를 사용할 수도 있습니다.
|
sampler
| const
| Jaeger를 상수 샘플러(켜거나 끔)를 사용하도록 구성합니다. |
sampler_param
| 1
|
const 샘플러를 사용하여 모든 추적을 샘플링하도록 구성합니다. 0 을 사용하면 모든 추적을 샘플링하지 않습니다.
|
다른 매개변수 값도 가능합니다:
이름 | 예제 | 설명 |
---|---|---|
udp_endpoint
| localhost:6831
| 이것이 기본값입니다. Jaeger를 compact thrift 프로토콜을 사용하여 포트 6831 에서 실행 중인 UDP 수신기로 추적 정보를 전송하도록 구성합니다. 이 프로토콜을 사용할 때 Jaeger Client for Ruby를 사용할 때 일부 문제가 발생했습니다.
|
sampler
| probabilistic
| 확률적 랜덤 샘플러를 사용하도록 Jaeger를 구성합니다. 샘플의 비율은 sampler_param 값으로 구성됩니다.
|
sampler_param
| 0.01
|
probabilistic 샘플러를 사용하여 추적의 _1%_를 무작위로 샘플링하도록 0.01 비율을 사용합니다.
|
service_name
| api
| Jaeger 백엔드에서 사용하는 서비스 이름을 재정의합니다. 이 매개변수는 응용프로그램 제공 값보다 우선합니다. |
GITLAB_TRACING
값을 구성해야 합니다.3. GitLab 애플리케이션 시작
GITLAB_TRACING
환경 변수가 모든 GitLab 서비스에 내보내졌으면, 애플리케이션을 시작하세요.
GITLAB_TRACING
을 올바르게 구성한 경우, 애플리케이션은 시작할 때 이 로그를 기록합니다:
13:41:53 gitlab-workhorse.1 | 2019/02/12 13:41:53 Tracing enabled
...
13:41:54 gitaly.1 | 2019/02/12 13:41:54 Tracing enabled
...
GITLAB_TRACING
이 올바르게 구성되지 않은 경우, 이 문제가 로그됩니다:
13:43:45 gitaly.1 | 2019/02/12 13:43:45 skipping tracing configuration step: tracer: unable to load driver mytracer
기본적으로 GitLab에는 Jaeger 추적기가 함께 제공되지만, 컴파일 시 다른 추적기를 포함할 수 있습니다. 이를 수행하는 방법에 대한 자세한 내용은 LabKit 추적 설명서에 포함되어 있습니다.
추적에 대한 로그 메시지가 없으면, GITLAB_TRACING
환경 변수가 설정되지 않은 것으로 보입니다.
4. Jaeger 검색 UI 열기
기본적으로, Jaeger 검색 UI는 http://localhost:16686/search에서 사용할 수 있습니다.