Gitaly를 모니터링하려면 사용 가능한 로그와 Prometheus 메트릭을 활용합니다.

메트릭 정의는 다음 방법으로 확인할 수 있습니다.

• Gitaly에 구성된 Prometheus /metrics 엔드포인트에서 직접 확인합니다.
• Prometheus를 연결한 Grafana 인스턴스에서 Grafana Explore를 사용합니다.

Gitaly는 요청 동시성(적응형 또는 비적응형)을 기준으로 요청을 제한하도록 구성할 수 있습니다.

Gitaly 동시성 제한 모니터링#

Gitaly 로그와 Prometheus로 동시성 큐에 대기 중인 요청의 구체적인 동작을 관찰할 수 있습니다.

Gitaly 로그에서는 다음과 같은 항목으로 pack-objects 동시성 제한과 관련된 로그를 확인할 수 있습니다.

예를 들면 다음과 같습니다.

{
  "limit.concurrency_queue_length": 1,
  "limit.concurrency_queue_ms": 0,
  "limit.limiting_key": "@hashed/79/02/7902699be42c8a8e46fbbb450172651786b22c56a189f7625a6da49081b2451.git",
  "limit.limiting_type": "per-rpc"
}

Prometheus에서는 다음 메트릭을 확인합니다.

• gitaly_concurrency_limiting_in_progress는 현재 처리 중인 동시 요청 수를 나타냅니다.
• gitaly_concurrency_limiting_queued는 동시성 제한에 도달해 특정 리포지터리의 RPC 요청이 대기 중인 수를 나타냅니다.
• gitaly_concurrency_limiting_acquiring_seconds는 동시성 제한 때문에 요청이 처리 전에 대기해야 하는 시간을 나타냅니다.
• gitaly_requests_dropped_total은 요청 제한으로 삭제된 요청의 총 개수를 제공합니다. reason 레이블은 요청이 삭제된 이유를 나타냅니다.
  • max_size는 동시성 큐 크기에 도달한 경우입니다.
  • max_time은 요청이 Gitaly에 구성된 최대 큐 대기 시간을 초과한 경우입니다.

Gitaly pack-objects 동시성 제한 모니터링#

Gitaly 로그와 Prometheus로 pack-objects 제한의 구체적인 동작을 관찰할 수 있습니다.

Gitaly 로그에서는 다음과 같은 항목으로 pack-objects 동시성 제한과 관련된 로그를 확인할 수 있습니다.

구성 예시는 다음과 같습니다.

{
  "limit.concurrency_queue_length": 1,
  "limit.concurrency_queue_ms": 0,
  "limit.limiting_key": "1.2.3.4",
  "limit.limiting_type": "pack-objects"
}

Prometheus에서는 다음 메트릭을 확인합니다.

• gitaly_pack_objects_in_progress는 동시에 처리 중인 pack-objects 프로세스 수를 나타냅니다.
• gitaly_pack_objects_queued는 동시성 제한에 도달해 대기 중인 pack-objects 프로세스 요청 수를 나타냅니다.
• gitaly_pack_objects_acquiring_seconds는 동시성 제한 때문에 pack-object 프로세스 요청이 처리 전에 대기해야 하는 시간을 나타냅니다.

Gitaly 적응형 동시성 제한 모니터링#

Gitaly 로그와 Prometheus로 적응형 동시성 제한의 구체적인 동작을 관찰할 수 있습니다.

적응형 동시성 제한은 정적 동시성 제한을 확장한 것이므로, 정적 동시성 제한에 적용되는 모든 메트릭과 로그는 적응형 제한을 모니터링할 때도 유효합니다. 여기에 더해 적응형 제한은 제한값의 동적 조정을 모니터링하는 데 도움이 되는 몇 가지 전용 메트릭을 제공합니다.

적응형 제한 로그#

Gitaly 로그에서는 현재 제한값이 조정될 때 적응형 동시성 제한과 관련된 로그를 확인할 수 있습니다. 로그 내용(msg)에서 "Multiplicative decrease" 와 "Additive increase" 메시지를 필터링할 수 있습니다.

이 디버그 로그는 디버그 심각도 수준에서만 제공되고 양이 많을 수 있지만, 적응형 제한 조정에 대한 상세한 정보를 제공합니다.

로그 예시는 다음과 같습니다.

{
  "msg": "Multiplicative decrease",
  "limit": "pack-objects",
  "new_limit": 14,
  "previous_limit": 29,
  "reason": "cgroup CPU throttled too much",
  "watcher": "CgroupCpu",
  "stats.time_diff": 15.0,
  "stats.throttled_duration": 13.0,
  "stat.sthrottled_threshold": 0.5
}

적응형 제한 메트릭#

Prometheus에서는 다음 메트릭을 확인합니다.

정적 제한과 적응형 제한 모두에 적용되는 일반 동시성 제한 메트릭입니다.

• gitaly_concurrency_limiting_in_progress - 처리 중인 요청 수입니다.
• gitaly_concurrency_limiting_queued - 동시성 제한 때문에 큐에서 대기 중인 요청 수입니다.
• gitaly_concurrency_limiting_acquiring_seconds - 처리가 시작되기 전에 동시성 제한으로 요청이 대기한 시간입니다.

적응형 동시성 제한 전용 메트릭입니다.

• gitaly_concurrency_limiting_current_limit - RPC 유형별 적응형 동시성 제한의 현재 값을 보여주는 게이지입니다. 이 메트릭에는 적응형 제한만 포함됩니다.
• gitaly_concurrency_limiting_backoff_events_total - 백오프 이벤트의 총 횟수를 나타내는 카운터로, 리소스 부하로 제한값이 언제 왜 낮아졌는지를 보여줍니다.
• gitaly_concurrency_limiting_watcher_errors_total - Gitaly가 리소스 데이터를 가져오지 못했을 때 발생하는 오류를 추적하는 카운터입니다. 이 오류는 Gitaly가 현재 리소스 상황을 판단하는 능력에 영향을 줄 수 있습니다.

적응형 제한 관련 문제를 조사할 때는 이 메트릭을 일반 동시성 제한 메트릭·로그와 함께 대조해 시스템 동작 전반을 파악합니다.

Gitaly cgroups 모니터링#

Prometheus로 컨트롤 그룹(cgroups)의 상태를 관찰할 수 있습니다.

• gitaly_cgroups_reclaim_attempts_total은 메모리 회수를 시도한 총 횟수를 나타내는 게이지입니다. 이 값은 서버를 재시작할 때마다 초기화됩니다.
• gitaly_cgroups_cpu_usage는 cgroup별 CPU 사용량을 측정하는 게이지입니다.
• gitaly_cgroup_procs_total은 Gitaly가 cgroups의 통제 아래 생성한 프로세스의 총 개수를 측정하는 게이지입니다.
• gitaly_cgroup_cpu_cfs_periods_total은 nr_periods 값을 나타내는 카운터입니다.
• gitaly_cgroup_cpu_cfs_throttled_periods_total은 nr_throttled 값을 나타내는 카운터입니다.
• gitaly_cgroup_cpu_cfs_throttled_seconds_total은 throttled_time 값을 초 단위로 나타내는 카운터입니다.

pack-objects 캐시#

다음 pack-objects 캐시 메트릭을 사용할 수 있습니다.

• gitaly_pack_objects_cache_enabled는 캐시가 활성화되면 1로 설정되는 게이지입니다. 사용 가능한 레이블은 dir과 max_age 입니다.
• gitaly_pack_objects_cache_lookups_total은 캐시 조회 횟수를 나타내는 카운터입니다. 사용 가능한 레이블은 result 입니다.
• gitaly_pack_objects_generated_bytes_total은 캐시에 기록된 바이트 수를 나타내는 카운터입니다.
• gitaly_pack_objects_served_bytes_total은 캐시에서 읽은 바이트 수를 나타내는 카운터입니다.
• gitaly_streamcache_filestore_disk_usage_bytes는 캐시 파일의 전체 크기를 나타내는 게이지입니다. 사용 가능한 레이블은 dir 입니다.
• gitaly_streamcache_index_entries는 캐시에 있는 항목 수를 나타내는 게이지입니다. 사용 가능한 레이블은 dir 입니다.

이 가운데 일부 메트릭 이름이 gitaly_streamcache로 시작하는 이유는 Gitaly의 내부 라이브러리 패키지인 streamcache가 생성하기 때문입니다.

예시:

gitaly_pack_objects_cache_enabled{dir="/var/opt/gitlab/git-data/repositories/+gitaly/PackObjectsCache",max_age="300"} 1
gitaly_pack_objects_cache_lookups_total{result="hit"} 2
gitaly_pack_objects_cache_lookups_total{result="miss"} 1
gitaly_pack_objects_generated_bytes_total 2.618649e+07
gitaly_pack_objects_served_bytes_total 7.855947e+07
gitaly_streamcache_filestore_disk_usage_bytes{dir="/var/opt/gitlab/git-data/repositories/+gitaly/PackObjectsCache"} 2.6200152e+07
gitaly_streamcache_filestore_removed_total{dir="/var/opt/gitlab/git-data/repositories/+gitaly/PackObjectsCache"} 1
gitaly_streamcache_index_entries{dir="/var/opt/gitlab/git-data/repositories/+gitaly/PackObjectsCache"} 1

Gitaly 서버 측 백업 모니터링#

서버 측 리포지터리 백업은 다음 메트릭으로 모니터링합니다.

• gitaly_backup_latency_seconds는 서버 측 백업의 각 단계에 걸린 시간을 초 단위로 측정하는 히스토그램입니다. 단계는 refs, bundle, custom_hooks 이며 각 단계에서 처리하는 데이터 유형을 나타냅니다.
• gitaly_backup_bundle_bytes는 Gitaly 백업 서비스가 오브젝트 스토리지로 푸시하는 Git 번들의 업로드 데이터 전송률을 측정하는 히스토그램입니다.

GitLab 인스턴스에 대용량 리포지터리가 있다면 이 메트릭을 특히 눈여겨봅니다.

쿼리#

다음은 Gitaly를 모니터링할 때 사용할 수 있는 쿼리입니다.

• 프로덕션 환경에서 Gitaly가 처리하는 연결 유형을 관찰하려면 다음 Prometheus 쿼리를 사용합니다.

  sum(rate(gitaly_connections_total[5m])) by (type)
  

• GitLab 설치의 인증 동작을 모니터링하려면 다음 Prometheus 쿼리를 사용합니다.

  sum(rate(gitaly_authentications_total[5m])) by (enforced, status)
  

  인증이 올바르게 구성되어 있고 실제 트래픽이 있는 시스템에서는 다음과 같은 결과를 볼 수 있습니다.

  {enforced="true",status="ok"}  4424.985419441742
  

  비율이 0인 다른 숫자가 함께 나올 수 있지만, 0이 아닌 숫자만 확인하면 됩니다.

  0이 아닌 숫자는 enforced="true",status="ok" 하나뿐이어야 합니다. 0이 아닌 다른 숫자가 있다면 구성에 문제가 있는 것입니다.

  status="ok" 숫자는 현재 요청 비율을 나타냅니다. 앞의 예시에서 Gitaly는 초당 약 4000건의 요청을 처리하고 있습니다.

• 프로덕션 환경에서 사용 중인 Git 프로토콜 버전을 관찰하려면 다음 Prometheus 쿼리를 사용합니다.

  sum(rate(gitaly_git_protocol_requests_total[1m])) by (grpc_method,git_protocol,grpc_service)