메트릭 사전 가이드

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

메트릭 정의 및 유효성 검사

메트릭 정의를 유효성 검사하기 위해 JSON 스키마를 사용합니다.

이 프로세스는 서비스 핑에 대한 일관된 및 유효한 메트릭이 정의되도록 하는 데 목적이 있습니다. 모든 메트릭은 반드시 다음을 준수해야 합니다:

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

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

config/metrics

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

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

필드	필수	추가 정보
`key_path`	예	메트릭의 JSON 키 경로, 서비스 핑 페이로드 내의 위치.
`description`	예
`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`, `devops_report` 중 하나로 설정할 수 있습니다.
`tier`	예	`array`; `free`, `premium`, `ultimate` 중 하나 또는 조합을 포함할 수 있습니다. 추적된 기능이 제공되는 티어입니다. 이것은 상세하게 작성되어 메트릭이 제공되는 모든 티어를 포함해야 합니다.
`milestone`	예	메트릭이 소개된 마일스톤 및 공식 GitLab 릴리스와 함께 오픈 소스로 이용 가능해진 마일스톤.
`milestone_removed`	아니오	메트릭이 제거된 마일스톤. 제거된 메트릭에 필요합니다.
`introduced_by_url`	예	메트릭을 오픈 소스 인스턴스에서 이용 가능하게 한 병합 요청의 URL.
`removed_by_url`	아니오	메트릭이 제거된 병합 요청의 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 fallback) 또는 데이터를 전혀 보고하지 않습니다. 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	설명
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: 데이터 수집 시 포함되는 표준 식별자 집합입니다.

YAML 메트릭 정의의 예

링크된 uuid YAML 파일에는 uuid 메트릭이 GitLab 인스턴스의 고유 식별자인 예제 메트릭 정의가 포함되어 있으며 다음과 같은 내용을 담고 있습니다.

key_path: uuid
description: GitLab 인스턴스 고유 식별자
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 형식의 타임스탬프 접두사가 포함됩니다.

성능 지표 메트릭

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

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