메트릭 사전 가이드
서비스 핑 메트릭은 개별 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 형식의 타임스탬프 접두어가 포함됩니다.
성능 지표 메트릭
성능 지표를 관리하기 위해 메트릭 정의를 사용하려면 성능 지표 가이드에서 안내하는 대로:
- 관련 변경 사항이 포함된 병합 요청을 생성하십시오.
-
~"analytics instrumentation"
,"~Data Warehouse::Impact Check"
레이블을 사용하십시오. - 메트릭 정의
performance_indicator_type
필드를 업데이트하십시오. - PI Chart Help 템플릿을 사용하여 GitLab Product Data Insights 프로젝트에 이슈를 생성하여 새로운 메트릭을 시각화하십시오.
메트릭 사전
메트릭 사전은 별도의 애플리케이션입니다.
Service Ping에서 이용 가능한 모든 메트릭은 메트릭 사전에 포함되어 있습니다.