InfoGrab DocsInfoGrab Docs

메트릭 딕셔너리 가이드

요약

Service Ping 메트릭은 개별 YAML 파일 정의에서 정의되며, 이를 바탕으로 메트릭 딕셔너리가 구축됩니다. YAML 파일에서 메트릭에 대한 변경이 이루어지면, 해당 변경이 프로덕션에 배포된 후 1시간 이내에 딕셔너리에서 확인할 수 있습니다.

Service Ping 메트릭은 개별 YAML 파일 정의에서 정의되며, 이를 바탕으로 메트릭 딕셔너리가 구축됩니다. 현재 메트릭 딕셔너리는 매 시간마다 자동으로 빌드됩니다.

  • YAML 파일에서 메트릭에 대한 변경이 이루어지면, 해당 변경이 프로덕션에 배포된 후 1시간 이내에 딕셔너리에서 확인할 수 있습니다.

  • YAML 파일에서 이벤트에 대한 변경이 이루어지면, 해당 변경이 master 브랜치에 머지된 후 1시간 이내에 딕셔너리에서 확인할 수 있습니다.

이 가이드는 딕셔너리와 그 구현 방식을 설명합니다.

메트릭 정의 및 유효성 검사#

JSON Schema를 사용하여 메트릭 정의의 유효성을 검사합니다.

이 프로세스는 Service Ping에 정의된 메트릭의 일관성과 유효성을 보장하기 위한 것입니다. 모든 메트릭은 다음 조건을 충족해야 합니다:

  • 정의된 JSON 스키마를 준수해야 합니다.

  • 고유한 key_path를 가져야 합니다.

  • 소유자(owner)가 있어야 합니다.

현재 tier는 메트릭 정의 파일의 필수 필드 중 하나이지만, tier를 tiers로 교체하는 작업을 진행 중입니다. 이를 위해 메트릭 정의 파일에 tiers를 필드로 추가하는 것도 유효합니다. 교체 프로세스가 완료될 때까지 tier와 tiers 모두 메트릭 정의 파일에 추가할 수 있는 유효한 필드입니다.

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

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

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

필드 필수 여부 추가 정보
key_path 예 메트릭의 JSON 키 경로, Service Ping 페이로드 내 위치.
description 예
product_group 예 해당 메트릭을 소유하는 그룹.
product_categories 예 배열; 메트릭이 나타내는 기능 카테고리.
value_type 예 문자열; string, number, boolean, object 중 하나.
status 예 문자열; 메트릭의 상태, active, removed, broken으로 설정 가능.
time_frame 예 문자열 또는 배열; 7d, 28d, all, none 또는 none을 제외한 이 값들의 조합을 포함하는 배열로 설정 가능.
data_source 예 문자열; database, redis, redis_hll, prometheus, system, license, internal_events 등의 값으로 설정 가능.
data_category 예 문자열; 메트릭의 카테고리, operational, optional, subscription, standard로 설정 가능. 기본값은 optional.
instrumentation_class 아니오 문자열; internal_events 이외의 data_source를 가진 메트릭에 사용됩니다. 메트릭을 구현하는 클래스를 참조하세요.
performance_indicator_type 아니오 배열; gmau, smau, paid_gmau, umau, customer_health_score, devops_report, lighthouse, leading_indicator 중 하나로 설정 가능.
tiers 예 배열; free, premium, ultimate 중 하나 또는 조합을 포함할 수 있습니다. 추적하는 기능이 사용 가능한 티어를 나타내며, 메트릭이 사용 가능한 모든 티어를 포함하여 상세하게 작성해야 합니다.
milestone 예 메트릭이 도입된 마일스톤 및 공식 GitLab 릴리즈와 함께 GitLab Self-Managed 인스턴스에서 사용 가능해지는 시점.
milestone_removed 아니오 메트릭이 제거된 마일스톤. 제거된 메트릭에 필수.
introduced_by_url 예 GitLab Self-Managed 인스턴스에서 사용할 수 있도록 메트릭을 도입한 머지 리퀘스트의 URL.
removed_by_url 아니오 메트릭을 제거한 머지 리퀘스트의 URL. 제거된 메트릭에 필수.
repair_issue_url 아니오 broken 상태의 메트릭을 수정하기 위해 생성된 이슈의 URL.
options 아니오 오브젝트: 메트릭 값 계산에 필요한 옵션 정보.

메트릭 key_path#

메트릭의 key_path는 JSON Service Ping 페이로드에서의 위치를 나타냅니다.

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

메트릭 정의에 배열 형태의 time_frame이 있는 경우, YAML 파일에 정의된 key_path에는 포함된 각 시간 프레임에 대한 접미사가 자동으로 추가됩니다:

time_frame key_path 접미사
all 접미사 없음
7d _weekly
28d _monthly

메트릭 딕셔너리에 표시된 key_path에는 이러한 접미사가 포함됩니다.

메트릭 상태#

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

  • 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를 기반으로 계산됩니다. time_frame이 배열인 경우, 메트릭의 값은 포함된 각 시간 프레임에 대해 계산됩니다.

data_source time_frame 설명
모두 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 instance unique identifier
product_group: analytics_instrumentation
product_categories:
- service_ping
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
tier:
- free
- premium
- ultimate
tiers:
- free
- premium
- ultimate

새 메트릭 정의 생성#

GitLab 코드베이스는 새 메트릭을 생성하기 위한 전용 생성기를 제공하며, 유효한 메트릭 정의 파일도 함께 생성합니다:

고유성을 위해 생성된 파일에는 ISO 8601 형식의 타임스탬프 접두사가 포함됩니다.

성과 지표 메트릭#

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

  • 관련 변경 사항을 포함한 머지 리퀘스트를 생성합니다.

  • ~"analytics instrumentation", "~Data Warehouse::Impact Check" 라벨을 사용합니다.

  • 메트릭 정의의 performance_indicator_type 필드를 업데이트합니다.

  • PI Chart Help 템플릿을 사용하여 GitLab Product Data Insights 프로젝트에 이슈를 생성하고 새 메트릭을 시각화합니다.

메트릭 딕셔너리#

메트릭 딕셔너리는 별도의 애플리케이션입니다.

Service Ping에서 사용 가능한 모든 메트릭은 메트릭 딕셔너리에 있습니다.

메트릭 딕셔너리 가이드

GitLab v19.1
원문 보기
요약

Service Ping 메트릭은 개별 YAML 파일 정의에서 정의되며, 이를 바탕으로 메트릭 딕셔너리가 구축됩니다. YAML 파일에서 메트릭에 대한 변경이 이루어지면, 해당 변경이 프로덕션에 배포된 후 1시간 이내에 딕셔너리에서 확인할 수 있습니다.

Service Ping 메트릭은 개별 YAML 파일 정의에서 정의되며, 이를 바탕으로 메트릭 딕셔너리가 구축됩니다. 현재 메트릭 딕셔너리는 매 시간마다 자동으로 빌드됩니다.

  • YAML 파일에서 메트릭에 대한 변경이 이루어지면, 해당 변경이 프로덕션에 배포된 후 1시간 이내에 딕셔너리에서 확인할 수 있습니다.

  • YAML 파일에서 이벤트에 대한 변경이 이루어지면, 해당 변경이 master 브랜치에 머지된 후 1시간 이내에 딕셔너리에서 확인할 수 있습니다.

이 가이드는 딕셔너리와 그 구현 방식을 설명합니다.

메트릭 정의 및 유효성 검사#

JSON Schema를 사용하여 메트릭 정의의 유효성을 검사합니다.

이 프로세스는 Service Ping에 정의된 메트릭의 일관성과 유효성을 보장하기 위한 것입니다. 모든 메트릭은 다음 조건을 충족해야 합니다:

  • 정의된 JSON 스키마를 준수해야 합니다.

  • 고유한 key_path를 가져야 합니다.

  • 소유자(owner)가 있어야 합니다.

현재 tier는 메트릭 정의 파일의 필수 필드 중 하나이지만, tier를 tiers로 교체하는 작업을 진행 중입니다. 이를 위해 메트릭 정의 파일에 tiers를 필드로 추가하는 것도 유효합니다. 교체 프로세스가 완료될 때까지 tier와 tiers 모두 메트릭 정의 파일에 추가할 수 있는 유효한 필드입니다.

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

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

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

필드 필수 여부 추가 정보
key_path 예 메트릭의 JSON 키 경로, Service Ping 페이로드 내 위치.
description 예
product_group 예 해당 메트릭을 소유하는 그룹.
product_categories 예 배열; 메트릭이 나타내는 기능 카테고리.
value_type 예 문자열; string, number, boolean, object 중 하나.
status 예 문자열; 메트릭의 상태, active, removed, broken으로 설정 가능.
time_frame 예 문자열 또는 배열; 7d, 28d, all, none 또는 none을 제외한 이 값들의 조합을 포함하는 배열로 설정 가능.
data_source 예 문자열; database, redis, redis_hll, prometheus, system, license, internal_events 등의 값으로 설정 가능.
data_category 예 문자열; 메트릭의 카테고리, operational, optional, subscription, standard로 설정 가능. 기본값은 optional.
instrumentation_class 아니오 문자열; internal_events 이외의 data_source를 가진 메트릭에 사용됩니다. 메트릭을 구현하는 클래스를 참조하세요.
performance_indicator_type 아니오 배열; gmau, smau, paid_gmau, umau, customer_health_score, devops_report, lighthouse, leading_indicator 중 하나로 설정 가능.
tiers 예 배열; free, premium, ultimate 중 하나 또는 조합을 포함할 수 있습니다. 추적하는 기능이 사용 가능한 티어를 나타내며, 메트릭이 사용 가능한 모든 티어를 포함하여 상세하게 작성해야 합니다.
milestone 예 메트릭이 도입된 마일스톤 및 공식 GitLab 릴리즈와 함께 GitLab Self-Managed 인스턴스에서 사용 가능해지는 시점.
milestone_removed 아니오 메트릭이 제거된 마일스톤. 제거된 메트릭에 필수.
introduced_by_url 예 GitLab Self-Managed 인스턴스에서 사용할 수 있도록 메트릭을 도입한 머지 리퀘스트의 URL.
removed_by_url 아니오 메트릭을 제거한 머지 리퀘스트의 URL. 제거된 메트릭에 필수.
repair_issue_url 아니오 broken 상태의 메트릭을 수정하기 위해 생성된 이슈의 URL.
options 아니오 오브젝트: 메트릭 값 계산에 필요한 옵션 정보.

메트릭 key_path#

메트릭의 key_path는 JSON Service Ping 페이로드에서의 위치를 나타냅니다.

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

메트릭 정의에 배열 형태의 time_frame이 있는 경우, YAML 파일에 정의된 key_path에는 포함된 각 시간 프레임에 대한 접미사가 자동으로 추가됩니다:

time_frame key_path 접미사
all 접미사 없음
7d _weekly
28d _monthly

메트릭 딕셔너리에 표시된 key_path에는 이러한 접미사가 포함됩니다.

메트릭 상태#

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

  • 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를 기반으로 계산됩니다. time_frame이 배열인 경우, 메트릭의 값은 포함된 각 시간 프레임에 대해 계산됩니다.

data_source time_frame 설명
모두 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 instance unique identifier
product_group: analytics_instrumentation
product_categories:
- service_ping
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
tier:
- free
- premium
- ultimate
tiers:
- free
- premium
- ultimate

새 메트릭 정의 생성#

GitLab 코드베이스는 새 메트릭을 생성하기 위한 전용 생성기를 제공하며, 유효한 메트릭 정의 파일도 함께 생성합니다:

고유성을 위해 생성된 파일에는 ISO 8601 형식의 타임스탬프 접두사가 포함됩니다.

성과 지표 메트릭#

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

  • 관련 변경 사항을 포함한 머지 리퀘스트를 생성합니다.

  • ~"analytics instrumentation", "~Data Warehouse::Impact Check" 라벨을 사용합니다.

  • 메트릭 정의의 performance_indicator_type 필드를 업데이트합니다.

  • PI Chart Help 템플릿을 사용하여 GitLab Product Data Insights 프로젝트에 이슈를 생성하고 새 메트릭을 시각화합니다.

메트릭 딕셔너리#

메트릭 딕셔너리는 별도의 애플리케이션입니다.

Service Ping에서 사용 가능한 모든 메트릭은 메트릭 딕셔너리에 있습니다.