GitLab 내부 이벤트 트래킹(Internal Events Tracking)은 더 이상 사용되지 않는 Snowplow 및 Redis/RedisHLL 이벤트 트래킹 옵션 위에 통합 API를 제공합니다.

이 페이지에서는 이전 방식 중 하나에서 내부 이벤트 트래킹으로 전환하는 방법을 설명합니다.

Snowplow, Redis/RedisHLL을 통한 직접 이벤트 트래킹은 더 이상 사용되지 않지만 가까운 미래에 제거되지는 않습니다. 내부 이벤트 트래킹으로 마이그레이션할 것을 권장하지만, 더 이상 사용되지 않는 방식도 기존 이벤트 및 메트릭에 대해 계속 작동합니다.

기존 Snowplow 트래킹에서 마이그레이션#

이미 Snowplow에서 이벤트를 트래킹하고 있다면, 내부 이벤트 트래킹으로 전환하여 GitLab Self-Managed 인스턴스에서도 메트릭을 수집할 수 있습니다. GitLab 18.0부터 Self-Managed 인스턴스는 기본적으로 이벤트 데이터를 수집하므로, 이전 버전에서 수집된 집계 메트릭보다 더 상세한 인사이트를 제공합니다.

내부 이벤트로 트리거된 이벤트는 이전에 Snowplow로 직접 트래킹하던 것과 비교해 몇 가지 특별한 속성이 있습니다:

• category는 이벤트가 발생한 위치로 자동 설정됩니다. 프론트엔드 이벤트의 경우 페이지 이름이, 백엔드 이벤트의 경우 클래스 이름이 사용됩니다. 페이지 이름이나 클래스 이름이 사용되지 않는 경우 기본값인 "InternalEventTracking"이 사용됩니다.

마이그레이션 전에 이 변경 사항이 문제없는지 확인하고, 대시보드도 그에 맞게 변경하세요.

백엔드#

이미 Gitlab::Tracking.event를 사용하여 Snowplow 이벤트를 트래킹하고 있으며 내부 이벤트 트래킹으로 마이그레이션하려면 다음과 같은 코드에서 시작할 수 있습니다:

Gitlab::Tracking.event(name, 'ci_templates_unique', namespace: namespace,
                               project: project, context: [context], user: user, label: label)

위 코드는 다음으로 대체할 수 있습니다:

include Gitlab::InternalEventsTracking

track_internal_event('ci_templates_unique', namespace: namespace, project: project, user: user, additional_properties: { label: label })

label, property, value 속성은 additional_properties 해시 안에 전달해야 합니다. 원래 호출에 포함되지 않은 경우 additional_properties 인수는 생략할 수 있습니다.

또한 트래킹하려는 메트릭의 정의를 생성해야 합니다.

메트릭 정의를 생성하려면 다음 생성기를 사용할 수 있습니다:

scripts/internal_events/cli.rb

생성기는 필요한 입력을 단계별로 안내합니다.

마이그레이션된 이벤트가 이전에 RedisHLL 메트릭 트래킹에 사용된 경우, migrated internal event shared examples를 사용하여 마이그레이션을 테스트하세요 (사용 예시).

프론트엔드#

Vue 컴포넌트에서 Tracking 믹스인을 사용하고 있다면 InternalEvents 믹스인으로 교체할 수 있습니다.

예를 들어, 현재 Vue 컴포넌트가 다음과 같다면:

import Tracking from '~/tracking';
...
mixins: [Tracking.mixin()]
...
...
this.track('some_label', options)

내부 이벤트 트래킹으로 변환하면 다음과 같아야 합니다:

import { InternalEvents } from '~/tracking';
...
mixins: [InternalEvents.mixin()]
...
...
this.trackEvent('action', {}, 'category')

현재 category를 전달하고 있으며 이를 유지해야 하는 경우, 이전 예시에서 보여준 것처럼 trackEvent 메서드의 세 번째 인수로 전달할 수 있습니다. 그러나 새 이벤트에는 category 파라미터를 사용하지 않도록 강력히 권장합니다. 이는 기본적으로 category 필드가 이벤트가 트리거된 위치에 대한 정보로 채워지기 때문입니다.

이 머지 리퀘스트를 예시로 사용할 수 있습니다. devops_adoption_app 컴포넌트를 내부 이벤트 트래킹으로 마이그레이션하는 예시입니다.

Snowplow 트래킹에서 label, value, property를 사용하고 있다면, trackEvent 함수의 세 번째 인수로 객체 형태로 전달할 수 있습니다. 선택적 파라미터입니다.

Vue Mixin의 경우:

   this.trackEvent('i_code_review_user_apply_suggestion', {
    label: 'push_event',
    property: 'golang',
    value: 20
   });

순수 JavaScript의 경우:

   InternalEvents.trackEvent('i_code_review_user_apply_suggestion', {
    label: 'admin',
    property: 'system',
    value: 20
   });

컴포넌트에서 data-track-action을 사용하고 있다면, 내부 이벤트 트래킹으로 마이그레이션하기 위해 data-event-tracking으로 변경해야 합니다. data-track-label, data-track-property, data-track-value 같은 추가 트래킹 속성이 있다면 각각 data-event-label, data-event-property, data-event-value로 교체할 수 있습니다. 추가 속성을 커스텀 키-값 쌍으로 전달하려면 data-event-additional 속성을 사용할 수 있습니다.

예를 들어, 버튼이 다음과 같이 정의되어 있다면:

 <gl-button
  :href="diffFile.external_url"
  :title="externalUrlLabel"
  :aria-label="externalUrlLabel"
  target="_blank"
  data-track-action="click_toggle_external_button"
  data-track-label="diff_toggle_external_button"
  data-track-property="diff_toggle_external"
  icon="external-link"
/>

내부 이벤트 트래킹으로 다음과 같이 변환할 수 있습니다:

 <gl-button
  :href="diffFile.external_url"
  :title="externalUrlLabel"
  :aria-label="externalUrlLabel"
  target="_blank"
  data-event-tracking="click_toggle_external_button"
  data-event-label="diff_toggle_external_button"
  data-event-property="diff_toggle_external"
  data-event-additional='{"key1": "value1", "key2": "value2"}'
  icon="external-link"
/>

data-event-tracking 속성에 action만 전달하면 되며, 이는 Snowplow와 RedisHLL 모두에 전달됩니다.

RedisHLL 트래킹에서 마이그레이션#

백엔드#

현재 RedisHLL에서 다음과 같이 메트릭을 트래킹하고 있다면:

  Gitlab::UsageDataCounters::HLLRedisCounter.track_event(:git_write_action, values: current_user.id)

내부 이벤트 트래킹 사용을 시작하려면 다음 단계를 따르세요:

• 이벤트가 Snowplow로 전송되지 않는 경우, 명명 규칙에 맞게 이름 변경을 고려하세요.

• git_write_action을 설명하는 이벤트 정의를 생성하세요 (가이드).

• 이벤트 섹션에 git_write_action을 나열하는 메트릭 정의 파일을 찾으세요 (20210216182041_action_monthly_active_users_git_write.yml 및 20210216184045_git_write_action_weekly.yml).

• 메트릭 정의 파일에서 data_source를 redis_hll에서 internal_events로 변경하세요.

• instrumentation_class 속성을 제거하세요. 내부 이벤트 메트릭에는 사용되지 않습니다.

• 두 메트릭 정의 파일 모두에 events 섹션을 추가하세요.

events:
  - name: git_write_action
    unique: user.id

메트릭이 고유 사용자 이외의 항목을 카운트하는 경우 user.id 대신 project.id 또는 namespace.id를 사용하세요.

• 두 메트릭 정의 파일 모두에서 options 섹션을 제거하세요.

• Gitlab::InternalEventsTracking 모듈을 포함하고 HLLRedisCounter.track_event 대신 track_internal_event를 호출하세요:

- Gitlab::UsageDataCounters::HLLRedisCounter.track_event(:git_write_action, values: current_user.id)
+ include Gitlab::InternalEventsTracking
+ track_internal_event('project_created', user: current_user)

• 선택 사항. 이벤트에 추가 값을 더하세요. 데이터 웨어하우스에서 유용한 정보이므로 일반적으로 project와 namespace를 추가하는 것이 좋습니다.

- Gitlab::UsageDataCounters::HLLRedisCounter.track_event(:git_write_action, values: current_user.id)
+ include Gitlab::InternalEventsTracking
+ track_internal_event('project_created', user: current_user, project: project, namespace: namespace)

• 테스트를 업데이트하여 internal event tracking shared example을 사용하세요.

• hll_redis_legacy_events.yml에서 이벤트 이름을 제거하세요.

• hll_redis_key_overrides.yml 파일에 이벤트를 추가하세요. 이 파일에서 사용되는 형식은 project_created-user: 'project_created'이며, 여기서 project_created는 이벤트 이름이고 user는 메트릭 정의 파일에 지정된 고유 값입니다.

프론트엔드#

믹스인, 순수 JavaScript, 또는 data-event-tracking 속성을 사용하여 trackRedisHllUserEvent 호출을 내부 이벤트로 변환할 수 있습니다.

빠른 시작 가이드에 각 방법의 예시가 있습니다.