이 페이지는 Analytics Instrumentation 리뷰에 대한 입문 자료를 포함합니다. 코드 리뷰에 대한 더 넓은 조언과 일반적인 모범 사례는 코드 리뷰 가이드를 참조하세요.

리뷰 프로세스#

머지 리퀘스트(MR)가 내부 분석 코드에 접촉하거나 사용하는 경우 Analytics Instrumentation 리뷰가 의무적으로 요구됩니다. 이에는 다음이 포함되지만 이에 한정되지 않습니다:

• 메트릭, 예를 들어:

config/metrics의 파일.

• ee/config/metrics의 파일.

• schema.json.

• 내부 이벤트, 예를 들어 config/events의 파일.

• Analytics Instrumentation 툴링, 예를 들어 Internal events CLI.

대부분의 경우 Analytics Instrumentation 리뷰는 자동으로 추가되지만, 자동화가 관련 변경을 감지하지 못한 경우 수동으로 요청할 수도 있습니다.

역할 및 프로세스#

Analytics Instrumentation 리뷰에는 세 가지 역할이 참여합니다:

• 머지 리퀘스트 작성자: 분석 변경을 수행하는 개발자.

• Analytics Instrumentation 리뷰어: Analytics Instrumentation 팀의 구성원. 엣지 케이스와 예외를 포함한 전체 리뷰를 담당합니다.

• 외부 리뷰어: 해당 Stage의 일반적인 분석 변경을 승인하는 Stage 레벨 CODEOWNER. 아래 체크리스트 범위를 벗어나는 항목은 Analytics Instrumentation 팀에 위임합니다.

머지 리퀘스트 작성자가 해야 할 사항#

• Analytics Instrumentation 리뷰가 필요한지 결정합니다. 변경 사항이 Analytics Instrumentation 도메인과 관련이 없는 경우 Analytics Instrumentation 리뷰를 건너뛰고 라벨을 제거할 수 있습니다.

• Analytics Instrumentation 리뷰가 필요하고 자동으로 할당되지 않은 경우, ~analytics instrumentation 및 ~analytics instrumentation::review pending 라벨을 추가합니다.

• MR의 일부로 이벤트에 대한 변경이 있는 경우:

사용 가능한 테스트 도구 중 하나를 사용하여 이벤트가 로컬에서 발화되는지 확인합니다.

• MR의 일부로 메트릭에 대한 변경이 있는 경우:

require_relative 'spec/support/helpers/service_ping_helpers.rb'; ServicePingHelpers.get_current_usage_metric_value(key_path)를 실행하여 새 메트릭이 Service Ping 페이로드에서 사용 가능하고 데이터를 보고하는지 확인합니다. key_path는 새 메트릭의 key_path로 대체합니다.

• 리뷰어 룰렛을 사용하여 작성자가 아닌 Analytics Instrumentation 리뷰어를 할당합니다.

• 필요에 따라 다른 리뷰를 할당합니다.

• ~analytics instrumentation 리뷰는 Maintainer 리뷰를 필요로 하지 않습니다.

Analytics Instrumentation 리뷰어가 해야 할 사항#

• 머지 리퀘스트에 대한 1차 리뷰를 수행하고 작성자에게 개선 사항을 제안합니다.

• 더 이상 사용되지 않는 분석 방법이 사용되지 않았는지 확인합니다.

• 리뷰의 일부로 이벤트에 대한 변경이 있는 경우:

발화되는 이벤트에 대응하는 정의 파일이 있는지 확인합니다.

• 이벤트 정의 파일이 올바른지 확인합니다.

• 추적 파라미터에 민감한 정보가 포함되지 않았는지 확인합니다.

• 리뷰의 일부로 메트릭에 대한 변경이 있는 경우:

데이터베이스 기반 메트릭에 대해 ~database 라벨을 추가하고 데이터베이스 리뷰를 요청합니다.

• 메트릭의 YAML 정의에 대해:

메트릭의 description을 확인합니다.

• 메트릭의 key_path를 확인합니다.

• product_group 필드를 확인합니다. stages 파일과 일치해야 합니다.

• 파일 위치를 확인합니다. 시간 프레임을 고려하고, 파일이 ee 하위에 있어야 하는지 확인합니다.

• 티어를 확인합니다.

• 메트릭이 변경되거나 제거된 경우: MR 작성자가 MR의 이슈 댓글에서 Customer Success Ops 팀(@csops-team), Analytics Engineers(@gitlab-data/analytics-engineers), Product Analysts(@gitlab-data/product-analysts)를 @ 멘션하여 알리고, 이 모든 그룹이 제거를 확인했는지 확인합니다.

• 리뷰의 일부로 Internal Events CLI에 대한 변경이 있는 경우:

변경 사항이 CLI 스타일 가이드를 따르는지 확인합니다.

• CLI를 실행하고 변경 사항의 UX를 확인합니다:

콘텐츠를 훑어보기 쉬운가?

• 이 콘텐츠가 팀 외부 사람들에게도 이해될 수 있는가?

• 이 정보가 필요한가? 도움이 되는가?

• 이 플로를 처음 경험하는 경우 어떤 의문점이 생길 수 있는가?

• 모든 입력의 의미나 효과가 명확한가?

• 엣지 케이스나 주의 사항을 설명하는 경우, 사용자가 이를 신경 써야 하는지 검증할 수 있는 지침이 있는가?

• MR을 승인하고 MR에 ~"analytics instrumentation::approved" 라벨을 다시 붙입니다.

외부 리뷰어가 해야 할 사항#

스키마 유효성 검사기와 린터는 누락된 필수 필드와 잘못된 형식의 YAML을 감지하므로, 이 체크리스트는 자동화가 수행할 수 없는 판단이 필요한 항목에 집중합니다.

• 새 이벤트의 경우:

action 이름이 명명 규칙을 따르는지 확인합니다.

• description이 팀 외부 독자들에게 명확한지 확인합니다.

• 이벤트가 EE 코드에서만 발화되는 경우 파일이 ee/config/events에 있는지 확인합니다.

• 추적 파라미터와 additional_properties에 민감하거나 개인적인 데이터가 포함되지 않았는지 확인합니다.

• 이벤트가 track_internal_event(백엔드) 또는 trackEvent(프론트엔드)를 사용하는지 확인합니다. Gitlab::Tracking.event와 같은 직접 Snowplow 호출 및 Redis 또는 RedisHLL 추적은 더 이상 사용되지 않습니다.

• 업데이트된 이벤트의 경우:

action 필드가 변경된 경우, 작성자가 이름 변경의 영향을 고려했는지 확인합니다.

• 제거된 이벤트의 경우:

이벤트 제거 프로세스가 따라졌는지 확인합니다.

• 새 메트릭의 경우:

YAML을 스팟 체크합니다: description, key_path, product_group, tiers, 그리고 EE 전용 메트릭의 경우 파일이 ee/config/metrics 하위에 있는지 확인합니다.

• 새 메트릭에 권장되는 소스인 data_source: internal_events를 선호합니다.

• 메트릭에 data_source: database가 있는 경우, 리뷰를 Analytics Instrumentation 팀에 넘깁니다.

• 메트릭이 더 이상 사용되지 않는 redis 또는 redis_hll 데이터 소스를 기반으로 하지 않는지 확인합니다. 마이그레이션 가이드를 참조하세요.

• 업데이트된 메트릭의 경우:

메트릭 변경 절차가 따라졌는지 확인합니다.