GitLab에는 분산 추적이 계측되어 있습니다. GitLab의 분산 추적은 아직 GitLab.com에서 대규모로 검증되지 않았으므로 현재 실험 기능으로 분류합니다.

Open Tracing의 설명은 다음과 같습니다.

분산 요청 추적이라고도 하는 분산 추적은 애플리케이션, 특히 마이크로서비스 아키텍처로 구축한 애플리케이션을 프로파일링하고 모니터링하는 데 사용하는 방법입니다. 분산 추적은 장애가 어디에서 발생하는지, 무엇이 성능 저하를 일으키는지 짚어내는 데 도움이 됩니다.

분산 추적은 요청이 GitLab 애플리케이션의 여러 구성 요소를 거치는 동안의 수명 주기를 이해하는 데 특히 유용합니다. 현재 Workhorse, Rails, Sidekiq, Gitaly가 추적 계측을 지원합니다.

분산 추적은 비활성화 상태에서는 오버헤드가 거의 없고, 활성화하더라도 오버헤드가 작기 때문에 프로덕션을 포함한 어떤 환경에서도 사용할 수 있습니다. 그래서 프로덕션 문제, 특히 성능 문제를 진단할 때 유용합니다.

서비스마다 분산 추적 지원 수준이 다릅니다. 가장 널리 쓰이는 라이브러리에 대한 사전 구현 계측 외에, 애플리케이션 계층에 사용자 지정 계측 코드를 추가해야 합니다.

서비스별 정보는 다음을 참고합니다.

• Gitaly 로컬 개발에서 Jaeger 사용

상관 관계 ID를 사용한 분산 요청 조사#

GitLab 애플리케이션은 요청에 참여하는 여러 구성 요소 사이에 상관 관계 ID를 전달합니다. 상관 관계 ID는 단일 요청마다 고유한 토큰으로, 서로 다른 GitLab 하위 시스템(예: Rails, Workhorse) 사이에서 하나의 요청을 연결하는 데 사용합니다. 상관 관계 ID는 로그 출력에 포함되므로, 엔지니어는 이 ID로 여러 하위 시스템의 로그를 연결해 요청이 시스템을 통과하는 전 구간 경로를 더 잘 이해할 수 있습니다. 요청이 프로세스 경계를 넘어갈 때는 상관 관계 ID가 나가는 요청에 주입됩니다. 이를 통해 상관 관계 ID가 각 다운스트림 하위 시스템으로 전파됩니다.

상관 관계 ID는 보통 특정 웹 요청에 대응해 Rails 애플리케이션에서 생성됩니다. 일부 사용자 대면 시스템은 사용자 요청에 대응해 상관 관계 ID를 생성하지 않습니다 (예: SSH를 통한 Git 푸시).

상관 관계 ID 작업을 위한 개발자 가이드라인#

새 시스템에 추적을 통합할 때 개발자는 상관 관계 ID에 대해 특정한 가정을 하지 않아야 합니다. 다음 가이드라인은 GitLab의 모든 하위 시스템에 적용됩니다.

• 상관 관계 ID는 항상 선택 사항입니다.
  • 추적과 무관한 기능이 업스트림 시스템에서 온 상관 관계 ID의 존재에 의존하도록 만들지 않습니다.
• 상관 관계 ID는 항상 자유 텍스트입니다.
  • 상관 관계 ID로 컨텍스트(예: 사용자 이름이나 IP 주소)를 전달하지 않습니다.
  • 상관 관계 ID를 파싱하거나 다른 방식으로 조작(예: 분할)하지 않습니다.

LabKit 라이브러리는 Go 프로그래밍 언어에서 GitLab 상관 관계 ID를 다루기 위한 표준 인터페이스를 제공합니다. Go가 아닌 GitLab 하위 시스템에서 추적과 상관 관계 ID를 다루는 개발자는 LabKit을 참조 구현으로 활용할 수 있습니다.

분산 추적 활성화#

GitLab은 GITLAB_TRACING 환경 변수로 분산 추적을 구성합니다. 모든 구성 요소 (예: Workhorse, Rails 등)에 같은 구성을 사용합니다.

GITLAB_TRACING 이 설정되지 않으면 애플리케이션은 계측되지 않으므로 오버헤드가 전혀 없습니다.

GITLAB_TRACING을 활성화하려면 URL과 비슷한 형태의 유효한 "configuration-string" 값을 설정해야 합니다.

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 Development Kit에서 Jaeger 사용#

GitLab 이 지원하는 첫 번째 추적 구현은 Jaeger 이며, GitLab Development Kit은 Jaeger 기반 분산 추적을 기본으로 지원합니다. GDK는 서비스를 추가할 때 GITLAB_TRACING 환경 변수를 자동으로 추가합니다.

Jaeger 용으로 GDK를 구성하려면 gdk.yml 파일을 편집해 다음 설정을 추가합니다.

tracer:
  build_tags: tracer_static tracer_static_jaeger
  jaeger:
    enabled: true
    listen_address: 127.0.0.1
    version: 1.66.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"를 실행할 수 있습니다.

다시 구성한 뒤에는 http://localhost:16686에서 Jaeger 대시보드를 사용할 수 있습니다. GDK 환경에서 추적에 접근하는 또 다른 방법은 성능 표시줄을 사용하는 것입니다. 브라우저 창에서 p b를 입력하면 표시할 수 있습니다.

성능 표시줄을 활성화한 뒤 성능 표시줄에서 Trace를 선택하면 Jaeger UI로 이동합니다.

Jaeger 검색 UI는 현재 요청의 Correlation-ID에 대한 쿼리를 반환합니다. 이 검색은 단일 트레이스 결과를 반환해야 합니다. 이 결과를 선택하면 계층형 타임라인으로 트레이스 상세를 확인할 수 있습니다.

GitLab Developer Kit 없이 Jaeger 사용#

분산 추적은 GDK가 아닌 개발 환경은 물론 프로덕션이나 스테이징 환경에서도 문제 해결을 위해 활성화할 수 있습니다. 현재 이 기능은 실험 기능이며 프로덕션 환경에서는 지원되지 않습니다. 이번 첫 릴리스에서는 개발 환경 디버깅 용도로만 사용하도록 만들어졌습니다.

Jaeger 추적은 다음 세 단계로 활성화할 수 있습니다.

1. Jaeger 시작.
2. GITLAB_TRACING 환경 변수 구성.
3. GitLab 애플리케이션 시작.
4. 브라우저에서 Jaeger 검색 UI 열기.

1. Jaeger 시작#

Jaeger에는 구성 옵션이 많지만, 트레이스 저장에 메모리를 사용하는(따라서 영속되지 않는) "all-in-one" 모드로는 아주 쉽게 시작할 수 있습니다. "all-in-one" 모드의 가장 큰 장점은 사용이 간편하다는 점입니다.

더 자세한 구성 옵션은 Jaeger 문서를 참고합니다.

Docker 사용#

Docker를 사용할 수 있다면 다음 명령으로 Docker에서 Jaeger all-in-one을 실행하는 편이 더 간단합니다.

$ 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 프로세스는 쉽게 설정할 수 있습니다.

1. 사용 중인 플랫폼에 맞는 최신 Jaeger 릴리스를 내려받습니다.
2. 압축을 풀고 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를 다음 옵션과 함께 사용합니다.

다음과 같은 다른 파라미터 값도 사용할 수 있습니다.

3. GitLab 애플리케이션 시작#

모든 GitLab 서비스에 GITLAB_TRACING 환경 변수를 내보낸 뒤 애플리케이션을 시작합니다.

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에서 사용할 수 있습니다.