• 기존 Snowplow 추적에서 마이그레이션
  • 백엔드
  • 프론트엔드
• RedisHLL 추적에서의 마이그레이션
  • Backend
  • Frontend

기존 추적을 내부 이벤트 추적으로 마이그레이션하기

GitLab 내부 이벤트 추적은 폐기된 Snowplow 및 Redis/RedisHLL 이벤트 추적 옵션 위에 통합된 API를 노출합니다.

이 페이지에서는 기존 방법 중 하나에서 내부 이벤트 추적을 사용하도록 전환하는 방법에 대해 설명합니다.

참고: Snowplow, Redis/RedisHLL을 통해 직접 이벤트를 추적하는 것은 폐기되었지만 예측할 수 있는 미래에 제거되지는 않을 것입니다. 내부 이벤트 추적으로 마이그레이션할 것을 권장하지만 폐기된 방법은 기존 이벤트 및 메트릭에 대해 계속 작동합니다.

기존 Snowplow 추적에서 마이그레이션

이미 Snowplow에서 이벤트를 추적 중이라면 내부 이벤트 추적으로 전환하여 자체 관리 인스턴스에서 메트릭을 수집할 수도 있습니다.

내부 이벤트에서 트리거된 이벤트는 이전에 Snowplow로 추적하는 것과 비교해 일부 특별한 속성을 가지고 있습니다:

1. 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 인수를 생략할 수 있습니다.

또한 추적하려는 메트릭에 대한 정의를 작성해야 합니다.

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

ruby scripts/internal_events/cli.rb

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

프론트엔드

Vue 컴포넌트에서 Tracking mixin을 사용 중이라면, InternalEvents mixin으로 교체할 수 있습니다.

예를 들어, 현재 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 필드는 이벤트가 트리거된 위치에 대한 정보로 채워지기 때문입니다.

이 MR를 예로 사용할 수 있습니다. 이 MR은 devops_adoption_app 컴포넌트를 내부 이벤트 추적을 사용하도록 마이그레이션합니다.

Snowplow 추적에서 label, value, property를 사용 중인 경우, 이를 세 번째 인수로 전달하여 trackEvent 함수로 전달할 수 있습니다. 이것은 선택적인 매개변수입니다.

Vue Mixin의 경우:

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

원시 JavaScript의 경우:

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

컴포넌트에 data-track-action을 사용 중인 경우, 이를 내부 이벤트 추적으로 마이그레이션하려면 data-event-tracking로 변경해야 합니다.

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

 <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"
  icon="external-link"

data-event-tracking 속성으로 전달할 작업만 필요하다는 것에 유의하세요. 이 작업은 Snowplow와 RedisHLL 둘 다에 전달될 것입니다.

RedisHLL 추적에서의 마이그레이션

Backend

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

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

내부 이벤트 추적을 시작하려면 다음 단계를 따르세요:

1. git_write_action을 설명하는 이벤트 정의를 생성하세요 (가이드).
2. 이벤트 섹션에서 git_write_action을 나열하는 메트릭 정의를 찾으세요(20210216182041_action_monthly_active_users_git_write.yml 및 20210216184045_git_write_action_weekly.yml).
3. 메트릭 정의 파일에서 data_source를 redis_hll에서 internal_events로 변경하세요.
4. instrumentation_class 속성을 제거하세요. 내부 이벤트 메트릭에는 사용되지 않습니다.

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

    events:
      - name: git_write_action
        unique: user.id
   

   메트릭이 사용자 이외의 다른 것을 계산하는 경우 user.id 대신 project.id 또는 namespace.id를 사용하세요.

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

7. HLLRedisCounter.track_event 대신 Gitlab::InternalEventsTracking 모듈을 포함하고 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)
   

8. 선택 사항. 이벤트에 추가 값을 추가하세요. 일반적으로 데이터 웨어하우스에 필요한 유용한 정보이므로 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)
   

9. internal event tracking 공유 예제를 사용하도록 테스트를 업데이트하세요.
10. hll_redis_legacy_events에서 이벤트의 이름을 제거하세요.
11. hll_redis_key_overrides에 이벤트를 추가하세요. 이 파일에서 사용되는 형식은 project_created-user: 'project_created'이며, 여기서 project_created는 이벤트의 이름이고 user는 메트릭 정의 파일에서 지정된 고유 값입니다.

Frontend

프론트엔드에서 trackRedisHllUserEvent를 호출하여 프론트엔드 이벤트를 추적 중이라면, mixin, raw JavaScript 또는 데이터 추적 속성을 사용하여 내부 이벤트로 변환할 수 있습니다.

빠른 시작 가이드에는 각 방법에 대한 예제가 포함되어 있습니다.