메트릭사전 가이드

서비스 핑 메트릭은 개별 YAML 파일 정의에 정의되며 여기에서 메트릭사전이 작성됩니다. 현재 메트릭사전은 매일 자동으로 작성됩니다. YAML 파일에서 메트릭에 대한 변경 사항이 있는 경우 24시간 이내에 사전에서 해당 변경 사항을 확인할 수 있습니다. 이 가이드에서는 사전과 해당 구현에 대해 설명합니다.

메트릭 정의 및 유효성 검사

우리는 JSON Schema를 사용하여 메트릭 정의를 유효성 검사합니다.

이 프로세스는 서비스 핑을 위해 일관된 및 유효한 메트릭이 정의되도록 보장하기 위한 것입니다. 모든 메트릭은 반드시 다음을 준수해야 합니다:

  • 정의된 JSON schema을 준수해야 합니다.
  • 고유한 key_path를 가져야 합니다.
  • 소유자가 있어야 합니다.

모든 메트릭은 YAML 파일에 저장됩니다:

caution
메트릭 정의 YAML이 있는 것이며 상태가 removed가 아닌 메트릭만 서비스 핑 JSON 페이로드에 추가됩니다.

각 메트릭은 별도의 YAML 파일에 정의되며 여러 필드로 구성됩니다:

필드 필수 추가 정보
key_path 예 메트릭의 JSON 키 경로, 서비스 핑 페이로드 내의 위치.
description 예  
product_section 예 섹션입니다.
product_stage 예 메트릭을 위한 단계입니다.
product_group 예 메트릭 소유 그룹입니다.
value_type 예 string; string, number, boolean, object 중 하나입니다.
status 예 string; 메트릭의 상태로, active, removed, broken 중 하나여야 합니다.
time_frame 예 string; 7d, 28d, all, none과 같은 값으로 설정할 수 있습니다.
data_source 예 string; database, redis, redis_hll, prometheus, system, license, internal_events 등의 값으로 설정할 수 있습니다.
data_category 예 메트릭의 카테고리로, operational, optional, subscription, standard와 같은 값으로 설정할 수 있습니다. 기본값은 optional입니다.
instrumentation_class 아니오 string; internal_events 이외의 data_source를 가진 메트릭에 사용됩니다. 메트릭을 구현하는 클래스를 참조하세요.
distribution 예 array; ce, ee 또는 ee 중 하나로 설정할 수 있습니다. 추적된 기능이 제공되는 분포입니다.
performance_indicator_type 아니오 array; gmau, smau, paid_gmau, umau 또는 customer_health_score 중 하나로 설정할 수 있습니다.
tier 예 array; free, premium, ultimate 중 하나 또는 조합을 포함할 수 있습니다. 추적된 기능이 제공되는 티어입니다. 메트릭이 사용 가능한 모든 티어를 자세히 설명하는 것이 좋습니다.
milestone 예 메트릭이 도입된 이벤트와 공식 GitLab 릴리스를 사용하는 Self-managed 인스턴스에 사용 가능해지는 이벤트입니다.
milestone_removed 아니오 메트릭이 제거된 이벤트입니다. 제거된 메트릭에 필요합니다.
introduced_by_url 아니오 Self-managed 인스턴스에서 사용할 수 있는 메트릭을 도입한 Merge Request의 URL입니다.
removed_by_url 아니오 메트릭을 제거한 Merge Request의 URL입니다. 제거된 메트릭에 필요합니다.
repair_issue_url 아니오 broken 상태의 메트릭을 수리하는 데 생성된 이슈의 URL입니다.
options 아니오 object: 메트릭 값 계산에 필요한 옵션 정보입니다.

메트릭 key_path

메트릭의 key_path는 JSON 서비스 핑 페이로드 내의 위치입니다.

key_path는 .로 구분된 여러 부분으로 구성될 수 있으며 고유해야 합니다.

우리는 메트릭을 다음 중 하나의 최상위 키에 추가하는 것을 권장합니다:

  • settings: 설정 관련 메트릭을 위한 것입니다.
  • counts_weekly: 가장 최근 7일간의 데이터가 있는 카운터용입니다.
  • counts_monthly: 가장 최근 28일간의 데이터가 있는 카운터용입니다.
  • counts: 모든 시간에 대한 데이터가 있는 카운터용입니다.

메트릭 상태

메트릭 정의는 다음 중 하나의 상태를 가질 수 있습니다:

  • active: 메트릭이 사용되고 데이터를 보고합니다.
  • broken: 메트릭이 손상된 데이터(예: -1로 대체)를 보고하거나 데이터를 보고하지 않습니다. broken으로 표시된 메트릭은 반드시 repair_issue_url 속성도 가져야 합니다.
  • removed: 메트릭이 제거되었지만 이전 버전의 GitLab에서 실행되는 인스턴스에서 보낸 서비스 핑 페이로드에 나타날 수 있습니다.

메트릭 value_type

메트릭 정의는 value_type에 대해 다음 중 하나의 값일 수 있습니다:

  • boolean
  • number
  • string
  • object: value_type: object를 가진 메트릭은 객체의 JSON 스키마에 대한 링크가 있어야 합니다. 일반적으로 우리는 복잡한 객체를 피하고 boolean, number, 또는 string 값 유형 중 하나를 선호합니다. value_type: object를 사용하는 메트릭의 예는 topology(/config/metrics/settings/20210323120839_topology.yml)이며, 관련 스키마는 /config/metrics/objects_schemas/topology_schema.json에 있습니다.

메트릭 time_frame

메트릭의 시간 프레임은 time_frame 필드와 메트릭의 data_source를 기반으로 계산됩니다.

data_source time_frame Description
any none 설정 및 구성 정보와 같이 시간에 따라 추적되지 않는 데이터 유형
database all 메트릭이 활성화된 전체 시간 (전체 기간)
database 7d 9일 전부터 2일 전까지
database 28d 30일 전부터 2일 전까지
internal_events all 메트릭이 활성화된 전체 시간 (전체 기간)
internal_events 7d 가장 최근의 완전한 주
internal_events 28d 최근 4주의 완전한 주

데이터 카테고리

우리는 메트릭을 분류하기 위해 다음과 같은 카테고리를 사용합니다:

  • operational: 운영 목적을 위한 필수 데이터.
  • optional: 메트릭의 기본값. 수집이 선택적인 데이터. 관리자 영역에서 활성화 또는 비활성화할 수 있습니다.
  • subscription: 라이선스 관련 데이터.
  • standard: 데이터 수집 시 포함되는 표준 식별자 세트.

집계 메트릭은 두 개 이상의 하위 메트릭의 합인 메트릭입니다. 서비스 Ping은 집계 메트릭의 데이터 카테고리를 사용하여 보고된 서비스 Ping 페이로드에 데이터가 포함되는지 여부를 결정합니다.

YAML 메트릭 정의 예

연결된 uuid YAML 파일에는 uuid 메트릭이 GitLab 인스턴스의 고유 식별자인 예제 메트릭 정의가 포함되어 있습니다. 

key_path: uuid
description: GitLab 인스턴스 고유 식별자
product_section: analytics
product_stage: analytics
product_group: analytics_instrumentation
value_type: string
status: active
milestone: 9.1
instrumentation_class: UuidMetric
introduced_by_url: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1521
time_frame: none
data_source: database
distribution:
- ce
- ee
tier:
- free
- premium
- ultimate

새로운 메트릭 정의 생성

GitLab 코드베이스는 새로운 메트릭을 생성하는 데 사용되는 전용 생성기를 제공하며, 유효한 메트릭 정의 파일도 생성합니다:

고유성을 위해 생성된 파일에는 ISO 8601 형식의 타임스탬프 접두사가 포함됩니다.

성능 지표 메트릭

성능 지표를 관리하기 위해 메트릭 정의를 사용하는 방법:

  1. 관련 변경 사항이 포함된 Merge Request을 생성합니다.
  2. 레이블 ~"analytics instrumentation", "~Data Warehouse::Impact Check"를 사용합니다.
  3. 필드인 performance_indicator_type을 업데이트합니다.
  4. 새로운 메트릭의 시각화를 위해 GitLab 제품 데이터 인사이트 프로젝트에 이슈를 생성하세요. PI Chart 도움말 템플릿을 사용하세요.

메트릭 사전

메트릭 사전은 별도의 응용프로그램입니다.

Service Ping에서 사용 가능한 모든 메트릭은 메트릭 사전에 있습니다.