sequenceDiagram
    participant Runner
    participant GitLab API
    participant Redis
    participant Database
Note over Runner,GitLab API: 작업 요청 단계
Runner->>GitLab API: POST /api/v4/jobs/request
GitLab API-->>Runner: 대기 중인 작업 반환
Note over GitLab API: 작업 상태: pending → running<br/>started_at 타임스탬프 설정

Note over Runner,Database: 작업 실행 단계
loop 주기적 업데이트
    Runner->>GitLab API: PUT /api/v4/jobs/{id}<br/>(작업 상태 업데이트)
    GitLab API->>Redis: 현재 실행 중인 빌드 사용량 조회
    GitLab API->>Database: 완료된 빌드 사용량 조회
    Note over GitLab API: 남은 할당량 계산
    alt 할당량 + 임계값 초과
        GitLab API-->>Runner: Job-Status 헤더: failure
    else 할당량 내
        GitLab API-->>Runner: Job-Status 헤더: running
    end

    Runner->>GitLab API: PATCH /api/v4/jobs/{id}/trace<br/>(빌드 로그 추가)
    GitLab API->>Redis: 현재 실행 중인 빌드 사용량 조회
    GitLab API->>Database: 완료된 빌드 사용량 조회
    Note over GitLab API: 남은 할당량 계산
    alt 할당량 + 임계값 초과
        GitLab API-->>Runner: Job-Status 헤더: failure
    else 할당량 내
        GitLab API-->>Runner: Job-Status 헤더: running
    end
end

Note over Runner,Database: 작업 완료 단계
Runner->>GitLab API: 작업 상태 전송 (success/failure/canceled)
Note over GitLab API: 작업이 완료 상태로 이동
GitLab API->>Database: 사용량 데이터 집계
Note over Database: 테이블 업데이트&lt;br/&gt;---&lt;br/&gt;ci_namespace_monthly_usages&lt;br/&gt;(네임스페이스당 월 1개 레코드)&lt;br/&gt;---&lt;br/&gt;ci_project_monthly_usages&lt;br/&gt;(프로젝트당 월 1개 레코드)</code></pre></details></div>

러너 통신#
러너는 여러 단계를 통해 GitLab과 통신합니다:
1. 작업 요청 단계
러너가 POST /api/v4/jobs/request를 폴링하여 실행할 pending 작업을 찾습니다. 작업이 할당될 때:

작업 상태가 GitLab에서 running으로 변경됩니다
started_at 타임스탬프가 설정됩니다
작업이 러너에서 실행을 시작합니다

Note
작업이 할당량을 초과한 경우 러너에 할당되지 않습니다. 이 로직은 RegisterJobService에서
호출되는 BuildQueueService에서 처리됩니다.

2. 작업 실행 단계
작업이 running 상태가 되면, 러너는 두 GitLab 엔드포인트를 주기적으로 업데이트합니다:

PUT /api/v4/jobs/{id} - 작업 상태 업데이트
PATCH /api/v4/jobs/{id}/trace - 빌드 로그 추가

3. 작업 실행 중 할당량 적용
실시간 할당량 적용은 오래 실행되는 작업이 할당량 제한을 우회하지 못하도록 방지하는 악용 방지 조치입니다.
예를 들어, 무료 플랜 네임스페이스에서 크립토 마이너가 월간 할당된 할당량이 10분 남아있는 상태에서
120분 실행되는 여러 작업을 시작합니다.
러너가 위의 엔드포인트를 통해 GitLab에 연락할 때마다 시스템은 할당량 한도를 확인합니다:

Ci::Minutes::TrackLiveConsumptionService가 실행되어 다음을 결합합니다:

현재 실행 중인 빌드의 Redis 기반 사용량
완료된 빌드의 데이터베이스 기반 사용량


남은 할당량이 Gitlab::Ci::Minutes::CachedQuota를 통해 계산됩니다
네임스페이스가 할당량 + 유예 기간 임계값을 초과한 경우, PUT/PATCH 응답의 Job-Status 헤더를 통해 러너에 실패 상태를 전송하여 빌드가 삭제됩니다

4. 작업 완료 및 데이터베이스 저장
빌드가 완료되면:

러너가 최종 작업 상태(success, failure, 또는 canceled)를 전송합니다
Rails가 finished_at 타임스탬프를 설정합니다
사용량 집계가 ::Ci::Minutes::UpdateBuildMinutesService에 의해 트리거되어 다음을 기록합니다:

초 단위 duration (started_at과 finished_at 타임스탬프로 계산)
CI 컴퓨팅 분 사용량 (비용 인수 적용: Job duration / 60 * Cost factor)


Gitlab::Ci::Minutes::Consumption 클래스는 빌드의 러너와 프로젝트 기반 할인을 기반으로 적절한 비용 인수를 검색합니다

데이터베이스 저장#
GitLab.com 사용량을 추적하기 위해 두 테이블을 유지합니다:

ci_namespace_monthly_usages - 네임스페이스당 월 1개 레코드
ci_project_monthly_usages - 프로젝트당 월 1개 레코드

이 테이블은 Ci::Minutes::NamespaceMonthlyUsage 및 Ci::Minutes::ProjectMonthlyUsage 클래스로 지원됩니다.
네임스페이스 및 프로젝트 수준에서 데이터를 사전 집계하면 다음과 같은 몇 가지 이점이 있습니다:

할당량 적용 및 빌드 삭제를 위한 효율적인 실시간 쿼리 가능
프로젝트 및 네임스페이스별 분 사용량 시각화 지원
쿼리 시간에 개별 빌드 수준 데이터를 집계하는 성능 문제 방지

Dedicated의 호스팅 러너 시각화#
2024년에 dedicated 호스팅 러너를 위한 목적별 시각화를 개발했습니다. 이 시각화는 Dedicated 인스턴스의
모든 루트 네임스페이스에서 사용량을 추정하는 임시 솔루션으로 만들어졌으며, GA 요구 사항을 충족하기 위해 필요했습니다.
기존 GitLab 시각화가 불충분했던 이유:

단일 네임스페이스 제한: 기존 시각화는 단일 루트 네임스페이스의 사용량만 표시하지만, Dedicated 고객은 인스턴스의 모든 네임스페이스에 걸쳐 가시성이 필요합니다
러너 유형 구분 없음: 관리자가 관리하는 인스턴스 러너와 GitLab 호스팅 인스턴스 러너가 함께 실행될 수 있습니다. 모든 인스턴스 러너 사용량을 함께 추적하기 때문에 기존 시각화가 호스팅 러너 메트릭에 자체 관리 인스턴스 러너를 잘못 포함할 수 있습니다

작동 방식#
이 시각화는 표준 추적 시스템과 유사하게 작동하지만 한 가지 주요 차이점이 있습니다:
러너를 프로비저닝할 때 instrumentor가 hosted_runner=true를 보냈는지 여부를 기반으로
Dedicated 특화 테이블(ci_gitlab_hosted_runner_monthly_usages)에 데이터를 추적합니다.
인스턴스 할당량 및 빌드 삭제는 이 테이블의 데이터에 적용되지 않습니다.
현재 구현#
비용 인수는 다음 방법 중 하나를 통해 설정해야 합니다:

Rails 콘솔
Instrumentor (러너 프로비저닝 시)
데이터베이스 마이그레이션

이 비용 인수는 시각화가 근사치를 유지하기 위해 청구 시스템의 비용 인수와 일치해야 합니다.
시각화는 현재 다음을 제공합니다:

러너별 사용량 분류
네임스페이스별 사용량 분류

미래 비전#
장기적 목표는 다음 방법 중 하나로 Customers Portal의 데이터를 직접 사용하여 이 시각화를 지원하는 것입니다:

GitLab에 Customers Portal 데이터 복제
Customers Portal API 직접 쿼리

GitLab.com의 현재 제한 사항#
1. 감사 가능성 제한
프로젝트 및 네임스페이스 수준에서만 사용량 데이터를 저장하므로 빌드 수준의 컴퓨팅 분 데이터가 없습니다.
이 집계는 성능을 위해 필요하지만(실시간 할당량 확인을 위해 모든 개별 빌드를 쿼리하는 것은 너무 느림),
세밀한 수준에서 사용량을 감사하는 능력을 제한합니다.
2. GitLab 엔드포인트가 응답하지 않을 때도 청구 계속
러너가 GitLab에서 500 에러를 받으면 포기하기 전에 여러 번 재시도하며, 그러면 작업이 완료되지 않은 상태로 유지됩니다.
결국 GitLab.com 측의 워커가 멈춘 작업을 정리하여 완료로 표시하고 분 저장을 트리거합니다.
이로 인해 실제로 러너가 소비한 것보다 더 많은 사용량을 나타내는 추가 GitLab duration과 컴퓨팅 분 사용량이 발생합니다.
이는 Redis의 로그/추적 저장이 공간 부족으로 인해 업데이트/추가 엔드포인트에서 장애를 일으킨 사건과 같이,
고객을 위해 수동으로 분을 재설정하거나 회사 비용으로 추가 팩을 제공해야 했던 인시던트에서 문제를 일으켰습니다.
러너가 직접 duration을 기록할 수 있도록 허용하면 러너로부터 확인을 받을 때까지 고객에게 청구하는 현재 방식보다
복원력이 향상될 것입니다.
3. SOX 컴플라이언스 격차
GitLab Rails 저장소는 SOX 제어 하에 있지 않습니다. 오버리지와 함께 소비 기반 청구로 전환함에 따라
금융 데이터를 처리하는 저장소에 엄격한 SOX 제어가 필요합니다.
4. 데이터베이스 경합
동일한 네임스페이스에 대해 많은 빌드가 동시에 실행될 때 데이터베이스 경합으로 인해 일부 Dedicated 인스턴스 고객을 위해
추적 메커니즘을 비활성화해야 했습니다. 참조: https://gitlab.com/gitlab-org/gitlab/-/issues/490968
5. 플랫폼별 설계
현재 시스템은 모든 인스턴스 러너가 호스팅 러너인 플랫폼으로서 GitLab.com을 위해 특별히 설계되었습니다.
이것이 러너 호스팅 상태를 결정하는 방법입니다. 그러나 다른 플랫폼에서는 인스턴스 러너가 자체 관리될 수 있습니다.
호스팅 러너를 다른 플랫폼으로 이동하려면 호스팅 러너와 자체 관리 러너를 구분하는 방법이 필요합니다.
.com의 미래 비전#
모든 호스팅 러너 사용량은 러너 단일 소스(SSoT)와 Customers Portal 추적을 기반으로 하는 통합 시스템을 사용하여
추적 및 관리되어야 합니다.
.com의 마이그레이션 경로#
.com 호스팅 인스턴스 러너를 이 새로운 추적 시스템을 사용하도록 마이그레이션해야 합니다. 이 마이그레이션은
추가 요구 사항인 할당량 적용을 도입하며, 이는 루트 네임스페이스 수준에서 집계된 실시간 데이터가 필요합니다.
소비 기반 청구를 .com에서 기존 고객에게 채택하더라도 할당량 적용은 .com에만 필요하고 다른 플랫폼에는 필요하지 않습니다.
악용을 방지하기 위해 무료 플랜에 대한 할당량 적용 및 빌드 삭제가 여전히 필요합니다.
확장된 기능#
이 통합 접근 방식을 통해 다음을 수행할 수 있습니다:

Dedicated 인스턴스에서 GitLab 호스팅 인스턴스 러너 판매
모든 플랫폼에서 GitLab 호스팅 그룹 또는 프로젝트 러너 판매
자체 관리에서 GitLab 호스팅 러너 판매
호스팅 러너가 .com의 인스턴스 러너여야 한다는 현재 패러다임 탈피

하위 호환성 유지#
.com 호스팅 인스턴스 러너를 Customers Portal 및 러너 추적 시스템으로 마이그레이션할 때,
자체 관리 고객의 워크플로우를 깨뜨리지 않기 위해 기존 인스턴스 러너 추적을 유지해야 합니다.
자체 호스팅 인스턴스 러너를 모니터링하기 위해 인스턴스 러너 추적을 사용하는 자체 관리 고객의
지원 티켓을 받았습니다.
두 가지 별도의 추적 시스템이 병렬로 실행될 필요가 있을 수 있습니다:

자체 관리 인스턴스 러너 - Rails에서 사용량 추적 및 적용, 인스턴스 관리자가 관리
GitLab 호스팅 러너 - Customers Portal에서 사용량 추적 및 적용, GitLab이 관리

.com이 더 이상 인스턴스 러너 추적의 주요 고객이 아니게 되면, 자체 관리 인스턴스에서 사용 데이터를 수집하여
그들의 필요를 이해해야 합니다. 이는 장기적으로 자체 관리 인스턴스에 인스턴스 러너 분 추적 및 할당량 적용을
유지할지 여부를 제품과 함께 결정하는 데 도움이 될 것입니다.