메트릭 사전 가이드

Service Ping 메트릭은 개별 YAML 파일 정의에서 정의되며 메트릭 사전은 여기에서 구축됩니다. 현재 메트릭 사전은 매일 자동으로 구축됩니다. YAML 파일에서 메트릭에 대한 변경이 발생하면 해당 변경이 24시간 이내에 사전에서 확인됩니다. 이 가이드에서는 사전 및 해당 구현에 대해 설명합니다.

메트릭 정의 및 유효성 검사

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

이 프로세스는 Service Ping을 위해 일관되고 유효한 메트릭을 보장하기 위한 것입니다. 모든 메트릭은 반드시 다음과 같아야 합니다:

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

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

caution
메트릭 정의 YAML이 있는 메트릭만이 상태가 removed가 아닌 경우 Service Ping JSON 페이로드에 추가됩니다.

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

필드 필수 여부 추가 정보
key_path 예 메트릭의 JSON 키 경로, Service Ping 페이로드 내의 위치.
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를 가진 메트릭에 사용됩니다. 메트릭을 구현하는 클래스를 참조하십시오(metrics_instrumentation.md).
distribution 예 ce, ee 또는 ee 중 하나로 설정할 수 있습니다. 추적되는 기능이 제공되는 분산으로 구성됩니다.
performance_indicator_type 아니오 gmau, smau, paid_gmau, umau 또는 customer_health_score 중 하나로 설정할 수 있습니다.
tier 예 free, premium, 또는 그 조합 중 하나 이상을 포함할 수 있습니다. 추적되는 기능을 사용할 수 있는 티어입니다. 이는 자세히 설명되어야 하며 메트릭이 사용 가능한 모든 티어를 포함해야 합니다.
milestone 예 메트릭이 소개된 마일스톤 및 공식 GitLab 릴리스를 통해 Self-Managed 인스턴스에서 사용 가능한 마일스톤입니다.
milestone_removed 아니오 메트릭이 제거된 마일스톤입니다. 제거된 메트릭의 경우 필수입니다.
introduced_by_url 아니오 Self-Managed 인스턴스에서 사용 가능한 메트릭을 소개하는 머지 요청의 URL입니다.
removed_by_url 아니오 메트릭을 제거한 머지 요청의 URL입니다. 제거된 메트릭의 경우 필수입니다.
repair_issue_url 아니오 broken 상태의 메트릭을 복구하기 위해 생성된 이슈의 URL입니다.
options 아니오 object: 메트릭 값을 계산하는 데 필요한 옵션 정보입니다.

메트릭 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 가장 최근의 완전한 주
internal_events 28d 가장 최근 4주 완전한 주

데이터 카테고리

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

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

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

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 Help 템플릿을 사용하세요.

메트릭 사전

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

서비스 핑에서 사용 가능한 모든 메트릭은 메트릭 사전에 있습니다.