InfoGrab DocsInfoGrab Docs

과금 이벤트 추적(Ruby)

요약

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 속성 값 등)를 업데이트합니다.

로컬에서 테스트#

  1. Snowplow Micro를 시작합니다.

    gdk start snowplow-micro
    
  2. 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 }
    )
    
  3. UI 대시보드를 방문해 Snowplow Micro가 수신한 과금 이벤트를 확인합니다.

과금 이벤트 추적(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 속성 값 등)를 업데이트합니다.

로컬에서 테스트#

  1. Snowplow Micro를 시작합니다.

    gdk start snowplow-micro
    
  2. 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 }
    )
    
  3. UI 대시보드를 방문해 Snowplow Micro가 수신한 과금 이벤트를 확인합니다.