청구 가능 이벤트 스키마

요약

청구 가능 이벤트 스키마는 고객 청구에 기여하는 사용 이벤트를 추적하기 위한 구조와 필드를 정의합니다. 이 문서는 billable_usage jsonschema를 기반으로 한 청구 가능 사용 이벤트 스키마의 참조로 사용됩니다.

개요#

청구 가능 이벤트 스키마는 고객 청구에 기여하는 사용 이벤트를 추적하기 위한 구조와 필드를 정의합니다. 이 스키마는 청구 목적으로 표준화된 사용 데이터를 캡처하기 위해 GitLab.com, Dedicated, Self-Managed 배포 전반에 걸쳐 사용됩니다.

이 문서는 billable_usage jsonschema를 기반으로 한 청구 가능 사용 이벤트 스키마의 참조로 사용됩니다.

필드 설명#

이벤트 식별 필드#

청구 가능 이벤트를 고유하게 식별하고 분류하는 필드.

필드	설명	Snowplow 필드	유형
`event_id`	이벤트의 고유 식별자 (RFC9562 UUID)	`event_id`	UUID (String)
`app_id`	애플리케이션 식별자 (예: GitLab Duo Workflow, Dedicated Hosted Runners)	`app_id`	String
`event_type`	청구 가능 이벤트 이름 (기능의 세분화, 예: `code_review`)	`event_type`	String
`timestamp`	이벤트가 발생한 타임스탬프	`context_generated_at`	String
`correlation_id`	각 요청의 고유 요청 ID	`correlation_id`	String

인스턴스 및 환경 필드#

GitLab 배포 환경과 인스턴스를 식별하는 필드.

필드	설명	Snowplow 필드	유형
`realm`	`SaaS`, `Dedicated`, 또는 `SM` (Self-Managed)	`realm`	String (enum)
`deployment_type`	배포 유형: `.com`, `dedicated`, 또는 `self-managed`. 향후 `realm`을 대체하기 위해 생성됨	`deployment_type`	String (enum)
`unique_instance_id`	요청이 발생하는 GitLab 인스턴스의 고유 ID	`unique_instance_id`	UUID (String)
`instance_id`	요청이 발생하는 GitLab 인스턴스의 고유 ID (GitLab 버전 < 17.11)	`instance_id`	UUID (String)
`host_name`	요청이 발생하는 GitLab 인스턴스의 호스트명 (예: `abc.xyz.com`)	`host_name`	String

사용자 및 리소스 식별 필드#

청구 가능 이벤트와 관련된 사용자, 시트, 리소스를 식별하는 필드.

필드	설명	Snowplow 필드	유형
`subject`	고객 조직의 사용자 식별자 또는 사용자 식별이 없는 러너의 식별자	`subject`	String
`global_user_id`	인스턴스 간에 고유한 익명화된 전역 사용자 ID	`global_user_id`	String
`assignments`	이벤트 생성 시 사용자와 관련된 제품 할당 (예: `Duo Pro`, `Duo Enterprise`)	-	Array[String]
`project_id`	관련 프로젝트의 ID (예: `122344`)	`project_id`	Integer
`namespace_id`	관련 네임스페이스의 ID (예: `3445555`)	`namespace_id`	Integer
`root_namespace_id`	관련 최상위 부모 네임스페이스의 ID (예: `5343322`)	`root_namespace_id`	Integer
`entity_id`	이벤트와 관련된 엔티티의 ID	`entity_id`	String
`organization_id`	관련 조직의 ID (예: `1445`)	`organization_id`	Integer

사용량 측정 필드#

청구를 위한 실제 사용량을 캡처하는 필드.

필드	설명	Snowplow 필드	유형
`unit_of_measure`	측정 및 청구에 사용되는 기본 단위 (예: 'byte', 'second', 'request'). 정확한 단위 변환 및 청구 계산에 사용됩니다.	`unit_of_measure`	String
`quantity`	지정된 단위로 측정된 사용량 수량	`quantity`	Decimal (Number)
`metadata`	추가 컨텍스트를 포함하는 키-값 쌍 또는 중첩 객체를 위한 유연한 메타데이터 필드	`metadata`	Object (JSON)

구현 가이드라인#

청구에 필요한 필드#

다음 필드는 청구 계산에 중요하며 모든 청구 가능 이벤트에 있어야 합니다:

event_id: 이벤트 고유성 및 중복 제거 보장
event_type: 청구 가능한 활동 분류
unit_of_measure: 청구 단위 정의
realm: 배포 모델 식별
timestamp: 시간 기반 청구 및 분석 가능

필드 채우기 가이드라인#

이벤트 식별: event_id에 항상 고유한 RFC9562 UUID를 생성합니다
타임스탬프: ISO 8601 형식 사용 (예: 2025-11-04T10:30:00Z)
측정 단위: 적절한 단위 선택 (byte, second, token, request 등)
수량: 실제 사용량을 나타내는 음수가 아닌 비제로 숫자여야 합니다
메타데이터: 분석에 도움이 되지만 청구에 필요하지 않은 추가 컨텍스트에 사용합니다

GitLab Duo Agent Platform의 메타데이터 필드#

필드	유형	설명	필수 여부
`workflow_id`	String	워크플로우 실행의 고유 식별자	예
`execution_environment`	String	워크플로우가 실행된 환경 (예: `duo_agent_platform`)	예
`llm_operations`	Array	워크플로우 중 수행된 LLM 작업 목록	예
`llm_operations[].token_count`	Integer	작업에서 사용된 총 토큰 수	예
`llm_operations[].model_id`	String	사용된 LLM 모델의 식별자 (예: `claude-3-sonnet-20240229`)	예
`llm_operations[].prompt_tokens`	Integer	프롬프트의 토큰 수	예
`llm_operations[].completion_tokens`	Integer	완료/응답의 토큰 수	예
`orbit_called`	Boolean	워크플로우 세션 중 Orbit 도구가 호출되었는지 여부	아니오

예시:

{
    "workflow_id": "wf_123456",
    "execution_environment": "duo_agent_platform",
    "llm_operations": [
        {
            "token_count": 5328,
            "model_id": "claude-3-sonnet-20240229",
            "prompt_tokens": 3150,
            "completion_tokens": 2178
        },
        {
            "token_count": 5328,
            "model_id": "claude-opus-4.1",
            "prompt_tokens": 3150,
            "completion_tokens": 2178
        }
    ],
    "orbit_called": true
}