GitLab은 고객에게 사용량 분석을 제공하기 위해 AI 사용량 데이터를 저장합니다. AI 사용량 추적은 개발자가 새로운 사용량 이벤트와 메트릭을 쉽게 추가할 수 있도록 일반화되었습니다.

사용량 이벤트 레코드 구조#

사용량 레코드에는 다음과 같이 설명된 필수 및 선택적 필드가 있습니다:

이벤트는 Postgres의 ai_usage_events 테이블과 ClickHouse의 ai_usage_events 테이블(사용 가능하고 분석을 위해 활성화된 경우)에 저장됩니다.

추적을 위한 새 이벤트 추가#

새 이벤트를 추가하려면 먼저 InternalEvents 서브시스템에 해당 이벤트를 선언해야 합니다. 내부 이벤트 빠른 시작 가이드를 참조하세요. 이벤트를 정의한 후 AI 추적을 위해 등록해야 합니다:

1. Gitlab::Tracking::AiTracking에 이벤트 이름과 고유 ID를 추가합니다:

   events(troubleshoot_job: 7)
   

   [!note] 이벤트 유형 ID는 고유해야 하며 데이터베이스에 저장됩니다. 기존 이벤트의 ID를 변경하는 경우 기존 데이터의 적절한 마이그레이션을 확인하세요.

   이벤트에 저장해야 할 추가 메타데이터가 있는 경우 변환과 함께 이벤트를 선언해야 합니다.

   events(troubleshoot_job: 7) do |context|
     { job_id: context['job'].id }
   end
   

   transformation 메서드로 추가 변환 블록을 선언할 수 있습니다.

   [!note] 변환 블록은 데이터베이스의 jsonb 컬럼에 직렬화되므로 직렬화 가능한 해시를 반환해야 합니다.

2. 이벤트를 트리거하기 위해 코드베이스의 적절한 위치에서 새 이벤트로 InternalEvents.track_event를 호출합니다.

AI 사용량 추적에서 이벤트 제거#

AI 사용량 추적 시스템에서 이벤트를 제거하려면:

1. AiTracking 정의에서 모든 변환 블록을 제거합니다.
2. 이벤트 정의를 deprecated_events(troubleshoot_job: 7)로 변경하여 이전 데이터를 위한 ID와 이름을 예약합니다.
3. bundle exec rake gitlab:graphql:compile_docs로 GraphQL 문서를 재생성합니다.

해당 ID의 데이터가 데이터베이스나 버퍼에 더 이상 존재하지 않는다고 확신하는 경우에만 AiTracking의 정의를 완전히 제거할 수 있습니다.

GraphQL 노출#

AI 추적을 위해 선언된 모든 이벤트는 AiUsageData.all GraphQL 필드에 자동으로 노출될 수 있습니다. 이 필드가 새 이벤트 유형을 지원하도록 하려면:

1. ee/app/graphql/types/analytics/ai_usage/ai_usage_event_type_enum.rb의 유형 enum에 이벤트 유형을 추가합니다.
2. bundle exec rake gitlab:graphql:compile_docs로 GraphQL 문서를 재생성합니다.

이벤트를 편집하거나 제거할 때 API에 대한 임의적인 breaking changes를 방지하기 위해 이 작업을 수동으로 수행해야 합니다. GraphQL에서 이벤트 유형을 완전히 제거하려면 GraphQL 필드 deprecated 프로세스를 따르세요.

외부 호출 노출#

AI 추적을 위해 선언된 모든 이벤트는 외부 이벤트 추적을 위해 자동으로 노출됩니다. 이는 Rails 앱 외부에서 이벤트를 추적할 때 유용합니다. 예를 들어 IDE 확장에서. 외부 이벤트는 additional_properties 필드에 해당 페이로드와 함께 /api/v4/usage_data/track_event 엔드포인트를 호출하여 추적할 수 있습니다. 예를 들어:

curl "https://gitlab.com/api/v4/usage_data/track_event" --request POST --header "Authorization: Bearer glpat-XXX" --header 'Content-Type: application/json' --data '{"event": "code_suggestion_accepted_in_ide", "additional_properties": {"language": "javascript", "suggestion_size": 9, "timestamp": "2025-07-02 12:55:11 UTC", "branch_name": "my-new-feature"}, "project_id": 4}'