메트릭 사전 가이드
Service Ping 메트릭은 개별 YAML 파일 정의에서 정의되며, 이를 통해 Metrics Dictionary가 구축됩니다. 현재 메트릭 사전은 하루에 한 번 자동으로 구축됩니다. YAML 파일에서 메트릭에 대한 변경이 이루어지면, 24시간 이내에 사전에서 변경 사항을 확인할 수 있습니다.
이 가이드는 사전 및 구현하는 방법에 대해 설명합니다.
메트릭 정의 및 검증
우리는 메트릭 정의를 검증하기 위해 JSON Schema를 사용하고 있습니다.
이 과정은 Service Ping에 대해 일관되고 유효한 메트릭이 정의되도록 보장하기 위한 것입니다. 모든 메트릭은 반드시 다음과 같아야 합니다:
-
정의된 JSON 스키마를 준수해야 합니다.
-
고유한
key_path를 가져야 합니다. -
소유자가 있어야 합니다.
모든 메트릭은 YAML 파일에 저장됩니다:
경고:
메트릭 정의 YAML이 있으며 상태가 removed가 아닌 메트릭만 Service Ping JSON 페이로드에 추가됩니다.
각 메트릭은 여러 필드로 구성된 개별 YAML 파일에 정의됩니다:
| 필드 | 필수 | 추가 정보 |
|---|---|---|
key_path |
예 | 메트릭에 대한 JSON 키 경로, Service Ping 페이로드의 위치. |
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 |
예 |
string; 메트릭의 카테고리, 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의 조합을 포함할 수 있습니다. 추적된 기능이 사용 가능한 tier. 이 항목은 자세하게 작성되어야 하며 메트릭이 사용 가능한 모든 티어를 포함해야 합니다. |
milestone |
예 | 메트릭이 도입되는 마일스톤 및 공식 GitLab 릴리스로 셀프 관리 인스턴스에서 사용할 수 있는 시점. |
milestone_removed |
아니오 | 메트릭이 제거되는 마일스톤. 제거된 메트릭에 필요합니다. |
introduced_by_url |
예 | 메트릭이 셀프 관리 인스턴스에서 사용 가능하도록 도입된 머지 요청의 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에 대해 다음 값 중 하나를 가질 수 있습니다:
booleannumberstring-
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_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필드를 업데이트합니다. - 새로운 메트릭 시각화를 위해 PI 차트 도움말 템플릿으로 GitLab 제품 데이터 통찰력 프로젝트에 이슈를 생성합니다.
메트릭 사전
Service Ping에서 사용 가능한 모든 메트릭은 메트릭 사전에 있습니다.
도움말