다음 가이드라인은 메트릭 수명 주기의 각 단계에서 따라야 할 절차를 설명합니다.

새 메트릭 추가#

메트릭 계측 가이드를 따릅니다.

기존 메트릭 변경#

메트릭을 변경할 때는 모든 GitLab 인스턴스가 최신 버전으로 실행되지는 않는다는 점을 고려해야 합니다. 오래된 인스턴스는 여전히 이전 버전의 메트릭을 보고합니다. 또한 메트릭이 보고하는 수치는 이전에 보고된 수치와 비교할 때 주로 의미가 있습니다. 따라서 메트릭의 다음 항목 중 하나를 변경해야 한다면, 대신 새 메트릭을 추가해야 합니다. 기존 메트릭을 새 메트릭과 함께 유지할지 제거할지는 선택할 수 있습니다.

• 계산 로직: 이전 구현과 다른 값을 만들어 낼 수 있는 모든 변경을 뜻합니다
• YAML 속성: 다음 속성은 분석이나 계산에 직접 사용됩니다: key_path, time_frame, value_type, data_source.

메트릭의 performance_indicator_type 속성을 변경하거나 위에 정리한 규칙의 예외가 필요하다고 판단되면, 머지 리퀘스트나 이슈의 댓글에서 해당 그룹을 @로 멘션하여 Customer Success Ops 팀(@csops-team), Analytics Engineers(@gitlab-data/analytics-engineers), Product Analysts(@gitlab-data/product-analysts) 팀에 알립니다.

그 외 속성은 계산이나 분석에 영향을 주지 않고 변경할 수 있습니다. 메트릭 속성 갱신에 대한 도움말은 이 동영상 튜토리얼을 참고합니다.

현재 메트릭 사전은 하루에 한 번 자동으로 빌드됩니다. 메트릭의 YAML 파일을 변경하면 24시간 이내에 사전에서 변경 내용을 확인할 수 있습니다.

메트릭 제거#

1. 메트릭 제거 이슈가 아직 없다면 생성합니다. 이슈에는 해당 메트릭을 제거해야 하는 이유를 정리해야 합니다. 이 이슈로 제거 과정을 기록할 수 있습니다.

   • 메트릭에 [x]mau 또는 customer_health_score 계열의 performance_indicator_type 이 하나 이상 있는 경우: 이슈의 댓글에서 해당 그룹을 @로 멘션하여 Customer Success Ops 팀(@csops-team), Analytics Engineers(@gitlab-data/analytics-engineers), Product Analysts(@gitlab-data/product-analysts)에 알립니다. 이러한 메트릭이 예기치 않게 변경되면 리포팅이 깨질 수 있습니다.
   • 메트릭의 소유 그룹이 제거를 수행하는 그룹과 다른 경우: stages 파일에 따라 소유 그룹의 PM과 EM을 태그합니다.

2. data_source에 따라 메트릭 계측 코드를 제거합니다.

   • database/system: 메트릭에 instrumentation_class가 있고 해당 클래스를 다른 메트릭이 더 이상 사용하지 않는다면 클래스와 스펙을 제거할 수 있습니다. 메트릭이 lib/gitlab/usage_data.rb 또는 ee/lib/ee/gitlab/usage_data.rb 안에서 계측된다면 관련 코드와 스펙을 제거합니다 (예시).
   • redis_hll/redis/internal_events: track_internal_event 같은 추적 코드와 관련 스펙을 제거합니다.

3. 메트릭 YAML 정의의 속성을 갱신합니다.

   • status:를 removed로 설정합니다.
   • removed_by_url:을 메트릭을 제거하는 MR의 URL로 설정합니다
   • milestone_removed:를 메트릭이 제거된 마일스톤 번호로 설정합니다.

   메트릭의 YAML 정의 자체를 통째로 제거하지 않습니다. 일부 GitLab Self-Managed 인스턴스는 최신 GitLab 버전으로 즉시 업데이트하지 않아 제거된 메트릭을 계속 보고할 수 있습니다. Analytics Instrumentation 팀은 제거된 모든 메트릭을 식별하고 필터링하기 위해 그 기록이 필요합니다.

그룹 이름 변경#

이벤트나 메트릭을 소유한 그룹의 이름이 바뀌면, 해당 그룹에 속한 모든 메트릭 정의와 이벤트 정의에서 product_group 속성을 갱신해야 합니다.

product_group_renamer 스크립트가 모든 정의를 갱신하므로 수동으로 수정하지 않아도 됩니다.

예를 들어 5-min-app 그룹의 이름이 2-min-app으로 바뀌었다면 다음과 같이 관련 파일을 갱신할 수 있습니다.

$ scripts/internal_events/product_group_renamer.rb 5-min-app 2-min-app
Updated '5-min-app' to '2-min-app' in 3 files

Updated files:
  config/metrics/schema/product_groups.json
  config/metrics/counts_28d/20210216184517_p_ci_templates_5_min_production_app_monthly.yml
  config/metrics/counts_7d/20210216184515_p_ci_templates_5_min_production_app_weekly.yml

스크립트를 실행한 뒤에는 변경된 모든 파일을 Git에 커밋하고 머지 리퀘스트를 생성해야 합니다.

이 스크립트는 GDK의 일부이며, 프론트엔드 또는 백엔드 개발자가 스크립트를 실행하고 머지 리퀘스트를 준비할 수 있습니다.

그룹이 여러 그룹으로 분할된 경우에는 product_group을 직접 갱신해야 합니다.