메트릭 사전 가이드

서비스 핑 메트릭은 개별 YAML 파일 정의에 정의되어 있으며 메트릭 사전 에서 구축됩니다. 현재 메트릭 사전은 자동으로 매일 구축됩니다. YAML 파일에서 메트릭에 대한 변경이 발생하면, 해당 변경 내용은 24시간 이내에 사전에서 확인할 수 있습니다. 본 안내서에서는 사전 및 해당 구현에 대해 설명합니다.

메트릭 정의 및 유효성 검사

우리는 JSON Schema를 사용하여 메트릭을 유효성 검사하고 있습니다.

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

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

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

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

각 메트릭은 다음과 같은 여러 필드로 이루어진 별도의 YAML 파일에 정의됩니다:

필드 필수 추가 정보
key_path 예 해당 메트릭의 JSON 키 경로입니다. 서비스 핑 페이로드에서의 위치.
description 예  
product_section 예 해당 메트릭의 섹션입니다.
product_stage 예 해당 메트릭의 스테이지입니다.
product_group 예 해당 메트릭을 소유하는 그룹입니다.
value_type 예 string일 수 있으며, string, number, boolean, object 중 하나여야 합니다.
status 예 메트릭의 상태로, 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 예 ce, ee 또는 ee 중 하나로 설정될 수 있는 array입니다. 추적된 기능이 있는 배포입니다.
performance_indicator_type 아니요 array이며, gmau, smau, paid_gmau, umau 또는 customer_health_score 중 하나로 설정될 수 있습니다.
tier 예 array입니다. free, premium, ultimate 중 하나 또는 조합을 포함할 수 있습니다. 티어입니다. 해당 메트릭을 사용할 수 있는 모든 티어를 자세히 포함해야 합니다.
milestone 예 해당 메트릭이 소개된 마일스톤 및 공식 GitLab 릴리즈를 통해 자체 관리형 인스턴스에서 사용 가능한 마일스톤입니다.
milestone_removed 아니요 메트릭이 제거된 마일스톤입니다. 제거된 메트릭에 대해 필요합니다.
introduced_by_url 아니요 자체 관리형 인스턴스에서 사용할 수 있도록 메트릭을 소개한 머지 요청의 URL입니다.
removed_by_url 아니요 메트릭을 제거한 머지 요청의 URL입니다. 제거된 메트릭에 대해 필요합니다.
repair_issue_url 아니요 broken 상태의 메트릭을 복구하기 위해 생성된 이슈의 URL입니다.
options 아니요 메트릭 값을 계산하는 데 필요한 옵션 정보입니다.

메트릭 key_path

메트릭의 key_path는 JSON Service Ping 페이로드 내의 위치입니다.

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

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

  • settings: 설정 관련 메트릭에 대해
  • counts_weekly: 가장 최근 7일간 데이터가 있는 카운터에 대해
  • counts_monthly: 가장 최근 28일간 데이터가 있는 카운터에 대해
  • counts: 모든 시간에 대한 데이터가 있는 카운터에 대해

메트릭 상태

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

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

메트릭 value_type

메트릭 정의는 value_type에 대해 다음 값을 가질 수 있습니다:

  • boolean
  • number
  • string
  • object: value_type: object를 가진 메트릭은 객체에 대한 JSON 스키마 링크인 value_json_schema를 가져야 합니다. 일반적으로 복잡한 객체를 피하고 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 설명
any none 시간에 따라 추적되지 않는 데이터 유형, 예: 설정 및 구성 정보
database all 메트릭이 활성화된 전체 시간(전체 시간 간격)
database 7d 9일 전부터 2일 전까지
database 28d 30일 전부터 2일 전까지
internal_events all 메트릭이 활성화된 전체 시간(전체 시간 간격)
internal_events 7d 최근 완전한 1주일
internal_events 28d 최근 완전한 4주간

데이터 범주

우리는 메트릭을 분류하기 위해 다음 범주를 사용합니다:

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

집계 메트릭은 두 개 이상의 하위 메트릭의 합계인 메트릭입니다. Service Ping은 집계 메트릭의 데이터 범주를 사용하여 보고된 Service 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. 관련 변경 사항이 포함된 병합 요청을 생성하십시오.
  2. ~"analytics instrumentation", "~Data Warehouse::Impact Check" 레이블을 사용하십시오.
  3. 메트릭 정의 performance_indicator_type 필드를 업데이트하십시오.
  4. PI Chart Help 템플릿을 사용하여 GitLab Product Data Insights 프로젝트에 이슈를 생성하여 새로운 메트릭을 시각화하십시오.

메트릭 사전

메트릭 사전은 별도의 애플리케이션입니다.

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