과금 이벤트 추적(Ruby)
GitLab v19.6요약
Gitlab::BillingEvents::Client로 GitLab Rails 모놀리스에서 과금 대상 사용 이벤트를 추적합니다. 이벤트는 GitLab.com 스테이징, GitLab QA 인스턴스, CUSTOMER_PORTAL_URL이 스테이징 Customers Portal을 가리키는 인스턴스를 제외하고 프로덕션 과금 수집기로 전송됩니다.
Gitlab::BillingEvents::Client로 GitLab Rails 모놀리스에서 과금 대상 사용 이벤트를 추적합니다. 클라이언트는 billable_usage 컨텍스트가 포함된 Snowplow 구조화 이벤트를 Data Insights Platform 과금 수집기로 보냅니다.
이벤트는 GitLab.com 스테이징, GitLab QA 인스턴스, CUSTOMER_PORTAL_URL이 스테이징 Customers Portal을 가리키는 인스턴스를 제외하고
프로덕션 과금 수집기로 전송됩니다.
이러한 인스턴스는 스테이징 과금 수집기를 사용하므로, 사용량이 구독과 같은 CustomersDot
환경에 도달합니다.
클라이언트에는 진입점이 두 가지 있습니다. 누적 집계에는 track_billing_event를,
특정 시점의 측정값에는 track_billing_snapshot을 사용합니다.
카운터와 스냅샷을 참고합니다.
에어 갭 인스턴스에서는 같은 호출이 사용량을 전송하는 대신 로컬에 저장합니다. 에어 갭 인스턴스를 참고합니다.
스키마 필드 참조는 과금 대상 이벤트 스키마를 참고합니다.
과금 이벤트 추적#
과금 이벤트를 트리거하려면 원하는 인수와 함께 Gitlab::BillingEvents::Client.track_billing_event 메서드를 호출합니다.
Gitlab::BillingEvents::Client.track_billing_event(
event_type: 'secrets_read',
category: self.class.name,
unit_of_measure: 'request',
quantity: 1,
namespace: namespace,
user: current_user,
idempotency_key: "secrets_read:#{unique_request_id}",
metadata: {
mount_path: '/secrets/group-123',
audit_request_id: 'abc123'
}
)
매개변수#
| 매개변수 | 필수 | 기본값 | 설명 |
|---|---|---|---|
event_type |
예 | 과금 대상 이벤트 이름입니다. 예: secrets_read. |
|
category |
예 | 이벤트를 발생시킨 클래스 또는 모듈입니다. self.class.name을 사용합니다. |
|
unit_of_measure |
예 | 과금 단위입니다. request, secret, tokens, bytes 등입니다. |
|
quantity |
예 | 사용량입니다. 양수여야 합니다. | |
namespace |
예 | Namespace 레코드입니다. namespace_id와 root_namespace_id를 설정합니다. |
|
project |
아니요 | nil |
Project 레코드입니다. project_id를 설정합니다. |
user |
아니요 | nil |
User 레코드입니다. subject, subject_type, global_user_id를 설정합니다. |
idempotency_key |
아니요 | nil |
event_id를 생성하는 데 사용하는 문자열입니다. 다운스트림 과금 수집기는 event_id를 기준으로 이벤트를 중복 제거하므로, 제공하는 값은 과금되어야 하는 이벤트마다 고유해야 합니다. 값이 없으면 track_billing_event 호출마다 임의의 UUID가 생성됩니다. |
timestamp |
아니요 | Time.current |
과금 대상 활동의 시각입니다. 기본값은 현재 시각입니다. 이벤트가 다른 보고 기간을 나타내야 하면 특정 시각을 전달합니다. |
metadata |
아니요 | nil |
제품별 컨텍스트가 담긴 해시이며 이벤트 페이로드에 JSON 객체로 저장됩니다. 과금되어야 하는 이벤트에는 feature_qualified_name을 설정합니다. CustomersDot는 이 값이 없는 이벤트를 과금 불가로 처리합니다. |
전송되는 페이로드 예시#
다음은 클라이언트가 생성하는 billable_usage 컨텍스트의 예시입니다. 페이로드는 과금 대상 이벤트 스키마를 따릅니다.
{
"event_id": "a1b2c3d4-5678-5aaa-bbbb-ccccddddeeee",
"event_type": "secrets_read",
"unit_of_measure": "request",
"quantity": 1,
"timestamp": "2026-06-22T14:30:00Z",
"namespace_id": 9870,
"root_namespace_id": 9870,
"project_id": null,
"subject": "12345",
"subject_type": "User",
"global_user_id": "gid:abc123def456",
"realm": "SaaS",
"deployment_type": ".com",
"instance_id": "b8e45d3c-57f8-4a6f-b106-511801fd1155",
"unique_instance_id": "6680b88f-8a28-5d0b-8387-4c8d4e07d1bd",
"instance_version": "19.2.0",
"host_name": "gitlab.com",
"correlation_id": "c15c2216ec4d0679bccead19f5e1e9d0",
"metadata": {
"mount_path": "/secrets/group-123",
"audit_request_id": "abc123"
}
}
인스턴스 식별자#
instance_id는 인스턴스 UUID(Gitlab::CurrentSettings.uuid)입니다.unique_instance_id는 CustomersDot가 이벤트를 구독 또는 체험판에 대응시키는 데 사용하는 식별자입니다. GitLab.com에서는Gitlab::GlobalAnonymousId.instance_uuid입니다. GitLab Self-Managed와 GitLab Dedicated에서는 CustomersDot가 인스턴스에 발급한 Cloud Connector 토큰의gitlab_instance_uid클레임입니다. 사용할 수 있는 토큰이 없으면 클라이언트는Gitlab::GlobalAnonymousId.instance_uuid로 대체하며, CustomersDot는 이벤트를 대응시킬 수 없습니다.
카운터와 스냅샷#
두 메서드는 같은 인수를 받으며, 하루 동안의 반복 호출을 처리하는 방식만 다릅니다.
| 메서드 | 사용 대상 | 하루 동안의 반복 호출 |
|---|---|---|
track_billing_event |
일어난 일. 시크릿을 읽었거나 워크플로가 완료된 경우 | 누적됩니다 |
track_billing_snapshot |
현재 총계. 시크릿이 몇 개 있는지, 아티팩트 버전이 몇 개 보존되는지 | 서로 대체됩니다 |
값을 얼마나 자주 보내는지가 아니라 그 숫자가 무엇을 의미하는지에 따라 선택합니다. 특정 시점의
측정값을 track_billing_event로 보내면 합산되므로, 같은 사용량이 여러 번 계산되어
총계가 부풀려집니다.
이 구분은 사용량이 하루 단위 행으로 합쳐지는 에어 갭 인스턴스에만 영향을 줍니다. 두 메서드는 네트워크로는 똑같이 전송합니다.
에어 갭 인스턴스#
에어 갭 인스턴스는 과금 수집기에 접근할 수 없으므로 네트워크로 보낸 사용량이
유실됩니다. 이러한 인스턴스가 오프라인으로 라이선스를 받으면 클라이언트는 전송하는 대신
로컬 일별 집계 테이블에 기록하며, 관리자가 이 데이터를 내보내
업로드합니다. 이 동작은 local_billing_persistence 기능 플래그 뒤에 있으며 기본적으로
활성화되어 있습니다.
호출하는 쪽에서 이를 감지할 필요는 없습니다. 같은 호출이 두 종류의 인스턴스에서 모두 동작합니다.
상관관계를 위한 내부 이벤트#
track_billing_event를 호출할 때마다 다음을 포함한 usage_billing_event
내부 이벤트도 발생합니다.
label: 과금event_id(UUID)이며 과금 데이터와 분석 데이터를 연결하는 데 사용합니다.property: 과금event_type(예:secrets_read)입니다.
클라이언트는 같은 user, namespace, project 인수를 내부 이벤트에 전달하므로,
Service Ping 메트릭이 네임스페이스, 사용자, 프로젝트별로 과금
활동을 집계할 수 있습니다.
과금 이벤트 유형에 대한 Service Ping 메트릭 추가#
구현에 메트릭 추가가 필수는 아니지만 분석을 위한 데이터를 더 제공하는 데 도움이 될 수 있습니다.
새 메트릭을 만들려면 내부 이벤트 CLI를 사용해 메트릭 정의를 생성합니다. 안내가 나타나면 다음을 수행합니다.
- 이벤트 이름으로
usage_billing_event를 선택합니다. - 과금
event_type값(예:secrets_read)으로property에filter를 추가합니다. 이렇게 하면 해당 기능의 과금 이벤트만 선택됩니다. - 고유 개수 메트릭(예: 고유 네임스페이스 또는 사용자)이 필요하면
unique를 추가합니다.
필터와 고유 속성에 대한 자세한 내용은 내부 이벤트 메트릭 정의 가이드를 참고합니다.
또는 기존 메트릭 정의를 수동으로 복사합니다.
예를 들어
ee/config/metrics/counts_all/count_total_usage_billing_event_secrets_read.yml을
복사해 기능에 맞게 필드(key_path,
product_group, filter 속성 값 등)를 업데이트합니다.
로컬에서 테스트#
-
Snowplow Micro를 시작합니다.
gdk start snowplow-micro -
Rails 콘솔을 열고 이벤트를 보냅니다. 예를 들면 다음과 같습니다.
ns = Namespace.first Gitlab::BillingEvents::Client.track_billing_event( event_type: 'secrets_read', category: 'TestConsole', unit_of_measure: 'request', quantity: 1, namespace: ns, metadata: { test: true } ) -
UI 대시보드를 방문해 Snowplow Micro가 수신한 과금 이벤트를 확인합니다.