GitLab Runner는 Prometheus를 사용하여 모니터링할 수 있습니다.

내장 Prometheus 메트릭#

GitLab Runner에는 네이티브 Prometheus 메트릭이 포함되어 있으며, /metrics 경로의 내장 HTTP 서버를 사용하여 노출할 수 있습니다. 서버가 활성화된 경우 Prometheus 모니터링 시스템에서 스크랩하거나 다른 HTTP 클라이언트로 액세스할 수 있습니다.

노출된 정보는 다음을 포함합니다:

• 러너 비즈니스 로직 메트릭(예: 현재 실행 중인 잡 수)
• Go 특정 프로세스 메트릭(예: 가비지 컬렉션 통계, goroutine, memstats)
• 일반 프로세스 메트릭(메모리 사용량, CPU 사용량, 파일 디스크립터 사용량 등)
• 빌드 버전 정보

메트릭 형식은 Prometheus의 Exposition formats 사양에 문서화되어 있습니다.

이 메트릭은 운영자가 러너를 모니터링하고 통찰력을 얻는 방법으로 사용됩니다. 예를 들어 러너 호스트의 평균 부하 증가가 처리된 잡 증가와 관련이 있는지 알고 싶을 수 있습니다. 또는 머신 클러스터를 실행 중이고 인프라에 변경 사항을 적용할 수 있도록 빌드 트렌드를 추적하고 싶을 수 있습니다.

Prometheus에 대해 더 알아보기#

이 HTTP 엔드포인트를 스크랩하도록 Prometheus 서버를 설정하고 수집된 메트릭을 사용하려면 Prometheus의 시작하기 가이드를 참조하세요. Prometheus를 구성하는 방법에 대한 자세한 내용은 구성 섹션을 참조하세요. 알림 구성에 대한 자세한 내용은 알림 규칙과 Alertmanager를 참조하세요.

사용 가능한 메트릭#

사용 가능한 모든 메트릭의 전체 목록을 찾으려면 메트릭 엔드포인트를 구성하고 활성화한 후 curl로 확인하세요. 예를 들어 수신 포트 9252로 구성된 로컬 러너의 경우:

$ curl -s "http://localhost:9252/metrics" | grep -E "# HELP"

# HELP gitlab_runner_api_request_statuses_total The total number of api requests, partitioned by runner, endpoint and status.
# HELP gitlab_runner_autoscaling_machine_creation_duration_seconds Histogram of machine creation time.
# HELP gitlab_runner_autoscaling_machine_states The current number of machines per state in this provider.
# HELP gitlab_runner_concurrent The current value of concurrent setting
# HELP gitlab_runner_errors_total The number of caught errors.
# HELP gitlab_runner_limit The current value of limit setting
# HELP gitlab_runner_request_concurrency The current number of concurrent requests for a new job
# HELP gitlab_runner_request_concurrency_exceeded_total Count of excess requests above the configured request_concurrency limit
# HELP gitlab_runner_version_info A metric with a constant '1' value labeled by different build stats fields.
...

목록에는 Go 특정 프로세스 메트릭이 포함됩니다. Go 특정 프로세스가 포함되지 않은 사용 가능한 메트릭 목록은 러너 모니터링을 참조하세요.

pprof HTTP 엔드포인트#

메트릭을 통한 GitLab Runner 프로세스의 내부 상태는 유용하지만, 경우에 따라 실행 중인 프로세스를 실시간으로 검사해야 합니다. 그래서 pprof HTTP 엔드포인트를 도입했습니다.

pprof 엔드포인트는 /debug/pprof/ 경로의 내장 HTTP 서버를 통해 사용할 수 있습니다.

pprof 사용에 대한 자세한 내용은 문서를 참조하세요.

메트릭 HTTP 서버 구성#

다음 방법 중 하나를 사용하여 메트릭 HTTP 서버를 구성하세요:

• config.toml 파일에서 listen_address 전역 구성 옵션을 사용합니다.

• run 명령에 --listen-address 명령줄 옵션을 사용합니다.

• Helm 차트를 사용하는 러너의 경우 values.yaml에서:

  1. metrics 옵션을 구성합니다:

     ## Configure integrated Prometheus metrics exporter
     ##
     ## ref: https://docs.gitlab.com/runner/monitoring/#configuration-of-the-metrics-http-server
     ##
     metrics:
       enabled: true
     
       ## Define a name for the metrics port
       ##
       portName: metrics
     
       ## Provide a port number for the integrated Prometheus metrics exporter
       ##
       port: 9252
     
       ## Configure a prometheus-operator serviceMonitor to allow automatic detection of
       ## the scraping target. Requires enabling the service resource below.
       ##
       serviceMonitor:
         enabled: true
     
         ...
     

  2. 구성된 metrics를 검색하도록 service 모니터를 구성합니다:

     ## Configure a service resource to allow scraping metrics by using
     ## prometheus-operator serviceMonitor
     service:
       enabled: true
     
       ## Provide additional labels for the service
       ##
       labels: {}
     
       ## Provide additional annotations for the service
       ##
       annotations: {}
     
       ...
     

config.toml 파일에 주소를 추가하면 메트릭 HTTP 서버를 시작하기 위해 러너 프로세스를 재시작해야 합니다.

두 경우 모두 옵션은 [host]:<port> 형식의 문자열을 허용합니다. 여기서:

• host는 IP 주소 또는 호스트명일 수 있습니다.
• port는 유효한 TCP 포트 또는 심볼릭 서비스 이름(예: http)입니다. Prometheus에서 이미 할당된 포트 9252를 사용해야 합니다.

수신 주소에 포트가 포함되지 않으면 기본값은 9252입니다.

주소 예시:

• :9252는 포트 9252의 모든 인터페이스에서 수신합니다.
• localhost:9252는 포트 9252의 루프백 인터페이스에서 수신합니다.
• [2001:db8::1]:http는 HTTP 포트 80의 IPv6 주소 [2001:db8::1]에서 수신합니다.

적어도 Linux/Unix 시스템에서 1024 미만의 포트에서 수신하려면 루트/관리자 권한이 필요합니다.

HTTP 서버는 선택한 host:port에서 인증 없이 열립니다. 메트릭 서버를 공개 인터페이스에 바인딩하는 경우 방화벽을 사용하여 액세스를 제한하거나 인증 및 접근 제어를 위한 HTTP 프록시를 추가하세요.

Operator 관리 GitLab Runner 모니터링#

GitLab Runner Operator가 관리하는 GitLab Runner는 독립 실행형 GitLab Runner 인스턴스와 동일한 내장 Prometheus 메트릭 서버를 사용합니다. 메트릭 서버는 포트 9252의 모든 IPv6 및 IPv4 인터페이스에서 수신하는 listenAddr이 [::]:9252로 사전 구성되어 있습니다.

메트릭 포트 노출#

GitLab Runner Operator가 관리하는 GitLab Runner의 모니터링 및 메트릭 수집을 활성화하려면 Operator 관리 GitLab Runner 모니터링을 참조하세요.

메트릭 포트 구성#

러너 구성의 podSpec 필드에 다음 패치를 추가합니다:

apiVersion: apps.gitlab.com/v1beta2
kind: Runner
metadata:
  name: gitlab-runner
spec:
  gitlabUrl: https://gitlab.example.com
  token: gitlab-runner-secret
  buildImage: alpine
  podSpec:
    name: "metrics-config"
    patch: |
      {
        "containers": [
          {
            "name": "runner",
            "ports": [
              {
                "name": "metrics",
                "containerPort": 9252,
                "protocol": "TCP"
              }
            ]
          }
        ]
      }
    patchType: "strategic"

이 구성:

• name: 식별을 위해 커스텀 PodSpec에 이름을 할당합니다.
• patch: PodSpec에 적용할 JSON 패치를 정의하고 러너 컨테이너에서 포트 9252를 노출합니다.
• patchType: 패치를 적용하기 위해 strategic 병합 전략(기본값)을 사용합니다.
• port: Kubernetes 서비스에서 쉽게 식별할 수 있도록 metrics로 이름이 지정됩니다.

Prometheus 스크랩 구성#

Prometheus Operator를 사용하는 환경의 경우 러너 파드에서 직접 메트릭을 스크랩하는 PodMonitor 리소스를 생성합니다:

apiVersion: monitoring.coreos.com/v1
kind: PodMonitor
metadata:
  name: gitlab-runner-metrics
  namespace: kube-prometheus-stack
  labels:
    release: kube-prometheus-stack
spec:
  selector:
    matchLabels:
      app.kubernetes.io/component: runner
  namespaceSelector:
    matchNames:
      - gitlab-runner-system
  podMetricsEndpoints:
    - port: metrics
      interval: 10s
      path: /metrics

PodMonitor 구성을 적용합니다:

kubectl apply -f gitlab-runner-podmonitor.yaml

PodMonitor 구성:

• selector: app.kubernetes.io/component: runner 레이블이 있는 파드와 매칭됩니다.
• namespaceSelector: 스크랩을 gitlab-runner-system 네임스페이스로 제한합니다.
• podMetricsEndpoints: 메트릭 포트, 스크랩 간격 및 경로를 정의합니다.

메트릭에 러너 식별 추가#

내보낸 모든 메트릭에 러너 식별을 추가하려면 PodMonitor에 레이블 재지정 구성을 포함합니다:

podMetricsEndpoints:
  - port: metrics
    interval: 10s
    path: /metrics
    relabelings:
      - sourceLabels: [__meta_kubernetes_pod_label_app_kubernetes_io_name]
        targetLabel: runner_name

레이블 재지정 구성:

• 각 러너 파드에서 app.kubernetes.io/name 레이블을 추출합니다(GitLab Runner Operator에 의해 자동으로 설정됨).
• 해당 파드의 모든 메트릭에 runner_name 레이블로 추가합니다.
• 특정 러너 인스턴스별로 메트릭을 필터링하고 집계할 수 있습니다.

다음은 러너 식별이 포함된 메트릭 예시입니다:

gitlab_runner_concurrent{runner_name="my-gitlab-runner"} 10
gitlab_runner_jobs_running_total{runner_name="my-gitlab-runner"} 3

직접 Prometheus 스크랩 구성#

Prometheus Operator를 사용하지 않는 경우 Prometheus 스크랩 구성에 직접 레이블 재지정 구성을 추가할 수 있습니다:

scrape_configs:
  - job_name: 'gitlab-runner-operator'
    kubernetes_sd_configs:
      - role: pod
        namespaces:
          names:
            - gitlab-runner-system
    relabel_configs:
      - source_labels: [__meta_kubernetes_pod_label_app_kubernetes_io_name]
        target_label: runner_name
    metrics_path: /metrics
    scrape_interval: 10s

이 구성:

• Kubernetes 서비스 디스커버리를 사용하여 gitlab-runner-system 네임스페이스의 파드를 찾습니다.
• app.kubernetes.io/name 레이블을 추출하여 메트릭에 runner_name으로 추가합니다.

Kubernetes 이외의 executor를 사용하는 GitLab Runner 모니터링#

Kubernetes 이외의 executor를 사용하는 GitLab Runner 배포의 경우 Prometheus 구성의 외부 레이블을 통해 러너 식별을 추가할 수 있습니다.

외부 레이블을 사용한 정적 구성#

GitLab Runner 인스턴스를 스크랩하고 식별 레이블을 추가하도록 Prometheus를 구성합니다:

scrape_configs:
  - job_name: 'gitlab-runner'
    static_configs:
      - targets: ['runner1.example.com:9252']
        labels:
          runner_name: 'production-runner-1'
      - targets: ['runner2.example.com:9252']
        labels:
          runner_name: 'staging-runner-1'
    metrics_path: /metrics
    scrape_interval: 30s

이 구성은 메트릭에 러너 식별을 추가합니다:

gitlab_runner_concurrent{runner_name="production-runner-1"} 10
gitlab_runner_jobs_running_total{runner_name="staging-runner-1"} 3

이 구성을 통해 다음이 가능합니다:

• 특정 러너 인스턴스별로 메트릭을 필터링합니다.
• 러너별 대시보드 및 알림을 만듭니다.
• 다양한 러너 배포 간의 성능을 추적합니다.

Operator 관리 GitLab Runner에 사용 가능한 메트릭#

GitLab Runner Operator가 관리하는 GitLab Runner는 독립 실행형 GitLab Runner 배포와 동일한 메트릭을 노출합니다. 사용 가능한 모든 메트릭을 보려면 kubectl을 사용하여 메트릭 엔드포인트에 액세스합니다:

kubectl port-forward pod/<gitlab-runner-pod-name> 9252:9252
curl -s "http://localhost:9252/metrics" | grep -E "# HELP"

사용 가능한 메트릭의 전체 목록은 사용 가능한 메트릭을 참조하세요.

Operator 관리 GitLab Runner의 보안 고려 사항#

GitLab Runner Operator가 관리하는 GitLab Runner의 메트릭 수집을 구성할 때:

• Kubernetes NetworkPolicies를 사용하여 승인된 모니터링 시스템에 대한 액세스를 제한합니다.
• 프로덕션 환경에서 메트릭 스크랩에 상호 TLS 암호화 사용을 고려합니다.

Operator 관리 GitLab Runner 모니터링 트러블슈팅#

메트릭 엔드포인트에 액세스할 수 없음#

메트릭 엔드포인트에 액세스할 수 없는 경우:

1. 파드 사양에 메트릭 포트 구성이 포함되어 있는지 확인합니다.

2. 러너 파드가 실행 중이고 정상인지 확인합니다:

   kubectl get pods -l app.kubernetes.io/component=runner -n gitlab-runner-system
   kubectl describe pod <runner-pod-name> -n gitlab-runner-system
   

3. 메트릭 엔드포인트에 대한 연결을 테스트합니다:

   kubectl port-forward pod/<runner-pod-name> 9252:9252 -n gitlab-runner-system
   curl "http://localhost:9252/metrics"
   

Prometheus에서 메트릭이 누락됨#

Prometheus에 메트릭이 나타나지 않는 경우:

1. PodMonitor가 올바르게 구성되고 적용되었는지 확인합니다.

2. 네임스페이스 및 레이블 셀렉터가 러너 파드와 일치하는지 확인합니다.

3. 스크랩 오류를 위해 Prometheus 로그를 검토합니다.

4. PodMonitor가 Prometheus Operator에 의해 검색 가능한지 확인합니다:

   kubectl get podmonitor gitlab-runner-metrics -n kube-prometheus-stack
   kubectl describe podmonitor gitlab-runner-metrics -n kube-prometheus-stack