- 명명법
- 작동 방식
- 데이터베이스 메트릭
- 집계된 지표
- 숫자 지표
- 일반적인 지표
- 프로메테우스 지표
- 새로운 지표 계기 클래스 생성
- 서비스 핑 지표를 계기 클래스로 마이그레이션
- 지표 문제 해결
메트릭 이성구성 가이드
이 가이드에서는 메트릭 이성구성을 사용하여 Service Ping 메트릭을 개발하는 방법에 대해 설명합니다.
비디오 자습서는 instrumentation 클래스를 통한 Service Ping 메트릭 추가를 참조하십시오.
명명법
-
이성구성 클래스:
- 메트릭 클래스 중 하나를 상속함:
DatabaseMetric
,NumbersMetric
또는GenericMetric
. - Service Ping 메트릭의 값을 계산하는 논리를 구현함.
- 메트릭 클래스 중 하나를 상속함:
-
메트릭 정의: 서비스 데이터 메트릭 YAML 정의입니다.
- 강화: 메서드 강화는 메서드가 안전하게 실패하여 -1과 같은 대체 값을 반환하도록 하는 프로세스입니다.
작동 방식
메트릭 정의에는 instrumentation_class
필드가 있으며, 클래스로 설정할 수 있습니다.
지정된 이성구성 클래스는 기존의 메트릭 클래스 중 하나를 상속해야 합니다: DatabaseMetric
, NumbersMetric
또는 GenericMetric
.
현재의 관례는 단일 이성구성 클래스가 단일 메트릭에 해당한다는 것입니다.
이성구성 클래스를 사용하면 메트릭이 개별적으로 안전하게 실패하여 Service Ping 생성 전체 프로세스를 중단시키지 않을 수 있습니다.
데이터베이스 메트릭
데이터베이스 메트릭을 사용하여 데이터베이스에 저장된 데이터를 추적할 수 있습니다. 예를 들어, 특정 인스턴스에 존재하는 이슈 수를 카운트할 수 있습니다.
-
operation
: 주어진relation
에 대한 작업 중 하나인count
,distinct_count
,sum
및average
. -
relation
: 수행할operation
을 위한ActiveRecord::Relation
을 반환하는 람다를 할당합니다. 할당된 람다는 최대 하나의 매개변수를 허용할 수 있습니다. 매개변수는 메트릭 정의의options
키 아래에 해시로 저장됩니다. -
start
: 배치 카운팅의 시작 값을 지정합니다. 기본값은relation.minimum(:id)
입니다. -
finish
: 배치 카운팅의 끝 값을 지정합니다. 기본값은relation.maximum(:id)
입니다. -
cache_start_and_finish_as
:start
및finish
값의 캐시 키를 지정하고 그 값을 캐싱합니다.start
및finish
가 비용이 많이 드는 쿼리인 경우에는 이 호출을 사용하여 여러 메트릭 계산 사이에서 다시 사용되어야 합니다. -
available?
: 메트릭이 보고되어야 하는지를 지정합니다. 기본값은true
입니다. -
timestamp_column
: 선택적으로 메트릭에 사용되는 타임스탬프 열을 지정합니다. 기본값은created_at
입니다.
데이터베이스 메트릭을 추가하는 Merge Request의 예시를 참조하세요.
최적화 권장 및 예시
Service Ping 메트릭에 대한 단일 쿼리는 콜드 캐시를 가진 1초 실행 시간 이하로 유지해야 합니다.
- 전용 인덱스를 사용하세요. 예시는 다음 Merge Request을 참조하세요:
- 정의된
start
및finish
를 사용하세요. 이러한 값은 메모이제이션되어 재사용될 수 있으며, 다음과 같은 예시 Merge Request과 같이 사용할 수 있습니다. - 쿼리에서 조인 및 불필요한 복잡성을 피하세요. 다음 예시 Merge Request을 참조하세요.
-
distinct_count
에 대한 사용자 지정batch_size
를 설정하세요. 이는 이 예시 Merge Request과 같이 사용할 수 있습니다.
데이터베이스 메트릭 예시
카운트 예시
module Gitlab
module Usage
module Metrics
module Instrumentations
class CountIssuesMetric < DatabaseMetric
operation :count
relation ->(options) { Issue.where(confidential: options[:confidential]) }
end
end
end
end
end
배치 카운터 예시
module Gitlab
module Usage
module Metrics
module Instrumentations
class CountIssuesMetric < DatabaseMetric
operation :count
start { Issue.minimum(:id) }
finish { Issue.maximum(:id) }
relation { Issue }
end
end
end
end
end
고유한 배치 카운터 예시
# frozen_string_literal: true
module Gitlab
module Usage
module Metrics
module Instrumentations
class CountUsersAssociatingMilestonesToReleasesMetric < DatabaseMetric
operation :distinct_count, column: :author_id
relation { Release.with_milestones }
start { Release.minimum(:author_id) }
finish { Release.maximum(:author_id) }
end
end
end
end
end
합계 예시
# frozen_string_literal: true
module Gitlab
module Usage
module Metrics
module Instrumentations
class JiraImportsTotalImportedIssuesCountMetric < DatabaseMetric
operation :sum, column: :imported_issues_count
relation { JiraImportState.finished }
end
end
end
end
end
평균 예시
# frozen_string_literal: true
module Gitlab
module Usage
module Metrics
module Instrumentations
class CountIssuesWeightAverageMetric < DatabaseMetric
operation :average, column: :weight
relation { Issue }
end
end
end
end
end
예상 배치 카운터
제공된 estimate_batch_distinct_count
메서드를 통해 ActiveRecord::StatementInvalid
오류를 처리하는 예상 배치 카운터 기능. 오류가 발생하면 -1
값이 반환됩니다.
올바르게 사용하면 estimate_batch_distinct_count
메서드를 사용하여 다른 카운터로 확신할 수 없는 고유하지 않은 값이 포함된 열을 효과적으로 계산할 수 있습니다.
estimate_batch_distinct_count
메서드
메서드:
estimate_batch_distinct_count(relation, column = nil, batch_size: nil, start: nil, finish: nil)
메서드에는 다음과 같은 인수가 포함됩니다:
-
relation
: 카운트를 수행할 ActiveRecord_Relation입니다. -
column
: 고유한 카운트를 수행할 열입니다. 기본값은 기본 키입니다. -
batch_size
:Gitlab::Database::PostgresHll::BatchDistinctCounter::DEFAULT_BATCH_SIZE
에서부터. 기본값: 10,000. -
start
: 복잡한 최솟값 계산을 피하기 위해 배치 카운트의 사용자 지정 시작입니다. -
finish
: 복잡한 최댓값 계산을 피하기 위해 배치 카운트의 사용자 지정 끝입니다.
메서드에는 다음과 같은 전제 조건이 포함됩니다:
- 제공된
relation
은 수치 열로 정의된 기본 키를 포함하여야 합니다. 예:id bigint NOT NULL
. -
estimate_batch_distinct_count
는 결합된 관계를 처리할 수 있습니다. 고유하지 않은 열을 계산하는 능력을 사용하기 위해 결합된 관계는 반드시has_many :boards
와 같은 일대다 관계를 가져서는 안됩니다. -
start
및finish
인수는 항상 다른 열을 의미하는 고유한 값에 대한 기본 키 관계 값을 나타내어야 합니다. 예를 들어:estimate_batch_distinct_count(::Note, :author_id, start: ::Note.minimum(:id), finish: ::Note.maximum(:id))
예시:
-
단순 실행의, 제공된 관계만 있는 추정 배치 카운터 실행, 반환된 값은
Project
관계의id
열(기본 키)에 있는 고유한 값의 추정 개수를 나타냅니다:estimate_batch_distinct_count(::Project)
-
추정 배치 카운터 실행의 복잡한 예시, 제공된 관계에 추가 필터 적용 (
.where(time_period)
), 사용자 지정 열(:author_id
)에 있는 고유한 값의 추정 개수, 그리고start
와finish
매개변수가 함께 제공된 관계의 범위를 정의하는 경계를 적용합니다:estimate_batch_distinct_count(::Note.with_suggestions.where(time_period), :author_id, start: ::Note.minimum(:id), finish: ::Note.maximum(:id))
집계된 지표
집계된 지표 기능은 예를 들어 의사 난수화된 사용자 ID(pseudonymized_user_ids)
와 같은 데이터 속성의 수를 보여줍니다. 예를 들어, 새 이슈를 만들고 새 Merge Request을 열기와 같이 여러 작업을 수행하는 사용자의 수를 집계할 수 있습니다.
집계된 지표를 정의하기 위해 YAML 파일을 사용할 수 있습니다. 다음 인수들이 필요합니다:
-
options.events
: 지표 데이터로 집계할 이벤트 이름 디렉터리. 이 디렉터리의 모든 이벤트들은 동일한 데이터 소스를 사용해야 합니다. 추가적인 데이터 소스 요구 사항은 Database sourced aggregated metrics 및 Event sourced aggregated metrics에 설명되어 있습니다. -
options.aggregate.attribute
: 이벤트를 통해 집계되는 속성을 가리키는 정보입니다. -
time_frame
: 하나 이상의 유효한 시간 프레임. 이를 사용하여 특정 기간 내의 이벤트를 대상으로 한 집계된 지표에 포함된 데이터를 제한할 수 있습니다. 유효한 시간 프레임은 다음과 같습니다:-
7일
: 최근 7일간의 데이터. -
28일
: 최근 28일간의 데이터. -
전체
: 모든 과거 데이터,database
소스의 집계된 지표에만 사용 가능합니다.
-
-
data_source
: 집계된 지표에 포함된 모든 이벤트 데이터를 수집하는 데 사용되는 데이터 소스입니다. 유효한 데이터 소스는 다음과 같습니다:database
internal_events
-
redis_hll
: RedisHLL을 직접 사용하는 폐기된 지표
예를 들어, 98206번 Merge Request은 AggregatedMetric
지표를 추가한 예입니다.
적어도 하나 이상의 이벤트인 incident_management_alert_status_changed
, incident_management_alert_assigned
, incident_management_alert_todo
, incident_management_alert_create_incident
에서 발생한 고유한 user.id
개수를 계산합니다.
time_frame: 28d
instrumentation_class: AggregatedMetric
data_source: internal_events
options:
aggregate:
attribute: user.id
events:
- `incident_management_alert_status_changed`
- `incident_management_alert_assigned`
- `incident_management_alert_todo`
- `incident_management_alert_create_incident`
이벤트 소스 집계된 지표
내부 이벤트로 수집된 이벤트들의 집계를 선언하려면, time_frame
이 Redis 소스의 집계된 지표에 사용 불가능한 전체
값을 포함하지 않도록 주의하십시오.
EE 전용 이벤트를 모든 GitLab 에디션에서 발생하는 이벤트들과 함께 집계하는 것이 가능하지만, 이렇게 할 경우 EE 및 CE GitLab 인스턴스에서 수집된 데이터 간에 큰 차이가 있을 수 있다는 점을 기억하는 것이 중요합니다.
데이터베이스 소스 집계된 지표
데이터베이스에서 수집한 이벤트들을 기반으로 한 지표의 집계를 선언하려면, 다음 단계를 따르십시오:
집계를 위해 지표를 지속
추정 배치 카운터로 계산된 지표만 집계된 지표에 유지될 수 있습니다. 지속하려면,
estimate_batch_distinct_count
메소드에 루비 블록을 삽입하십시오.
이 블록은 미래에 집계된 지표에서 사용하기 위해 Gitlab::Usage::Metrics::Aggregates::Sources::PostgresHll.save_aggregated_metrics
method을 호출해야 합니다.
Gitlab::Usage::Metrics::Aggregates::Sources::PostgresHll.save_aggregated_metrics
메소드는 다음과 같은 인수들을 받습니다:
-
metric_name
: 집계에 사용할 지표의 이름. 해당 지표가 서비스 핑에 추가된 키와 동일해야 합니다. -
recorded_at_timestamp
: 주어진 서비스 핑 페이로드의 수집 시점을 나타내는 타임스탬프.recorded_at
과 같은 편리한 메소드를 사용하여recorded_at_timestamp
인수를 채우십시오. -
time_period
:estimate_batch_distinct_count
에 전달되는relation
인수를 작성하는 데 사용되는 시간 기간. 모든 사용 가능한 과거 데이터로 지표를 수집하려면 시간 기간에nil
값을 설정하십시오. -
data
:relation
의 유일한 항목을 나타내는 HyperLogLog 버킷 구조.estimate_batch_distinct_count
메소드는 항상 올바른 인수를 블록으로 전달하므로,data
인수는 항상 블록 인수와 동일한 값을 가져야 합니다. 예를 들면 다음과 같습니다:data: result
집계된 지표 유지 예시:
class UsageData
def count_secure_pipelines(time_period)
...
relation = ::Security::Scan.by_scan_types(scan_type).where(time_period)
pipelines_with_secure_jobs['dependency_scanning_pipeline'] = estimate_batch_distinct_count(relation, :pipeline_id, batch_size: 1000, start: start_id, finish: finish_id) do |result|
::Gitlab::Usage::Metrics::Aggregates::Sources::PostgresHll
.save_aggregated_metrics(metric_name: 'dependency_scanning_pipeline', recorded_at_timestamp: recorded_at, time_period: time_period, data: result)
end
end
end
새로운 집계된 지표 정의 추가
모든 지표가 지속된 후에, 집계된 지표 정의를 추가할 수 있습니다. 추정 배치 카운터로 수집된 지표의 집계를 선언하려면 다음 요구 사항을 준수해야 합니다:
-
events:
속성에 나열된 지표 이름은 이전 단계에서 지속할 때 전달한metric_name
인수와 동일해야 합니다. -
events:
속성에 나열된 모든 지표는 모든 선택된time_frame:
값에 대해 지속되어야 합니다.
이용 제약이 있는 집계된 지표
집계된 지표가 특정 조건에서만 보고되어야 하는 경우, 이러한 조건을 AggregatedMetric
클래스의 자식 클래스로 지정된 새 클래스에 명시해야 합니다.
# frozen_string_literal: true
module Gitlab
module Usage
module Metrics
module Instrumentations
class MergeUsageCountAggregatedMetric < AggregatedMetric
available? { Feature.enabled?(:merge_usage_data_missing_key_paths) }
end
end
end
end
end
또한 YAML 설정에서 해당 클래스 이름을 사용해야 합니다.
time_frame: 28d
instrumentation_class: MergeUsageCountAggregatedMetric
data_source: redis_hll
options:
aggregate:
attribute: user.id
events:
- `incident_management_alert_status_changed`
- `incident_management_alert_assigned`
- `incident_management_alert_todo`
- `incident_management_alert_create_incident`
숫자 지표
-
operation
: 주어진data
블록에 대한 작업. 현재 ‘add’ 작업만 지원합니다. -
data
: 숫자 배열을 포함하는block
입니다. -
available?
: 지표가 보고되어야 하는지 여부를 지정합니다. 기본값은true
입니다.
# frozen_string_literal: true
module Gitlab
module Usage
module Metrics
module Instrumentations
class IssuesBoardsCountMetric < NumbersMetric
operation :add
data do |time_frame|
[
CountIssuesMetric.new(time_frame: time_frame).value,
CountBoardsMetric.new(time_frame: time_frame).value
]
end
end
end
end
end
end
end
또한 YAML 설정에 instrumentation 클래스 이름을 포함해야 합니다.
time_frame: 28d
instrumentation_class: IssuesBoardsCountMetric
일반적인 지표
다른 지표에 대해서도 사용할 수 있습니다. 예를 들어, 인스턴스의 데이터베이스 버전입니다.
-
value
: 지표의 값 지정 -
available?
: 지표를 보고해야 하는지 여부를 지정. 기본값은true
입니다.
일반적인 지표를 추가하는 Merge Request 예시.
module Gitlab
module Usage
module Metrics
module Instrumentations
class UuidMetric < GenericMetric
value do
Gitlab::CurrentSettings.uuid
end
end
end
end
end
end
프로메테우스 지표
이 계기 클래스를 사용하면 value
블록에 프로메테우스 클라이언트 객체를 전달하여 프로메테우스 쿼리를 처리할 수 있습니다.
프로메테우스 오류 처리는 블록 자체에서 수행되어야 합니다.
-
value
: 지표의 값 지정. 프로메테우스 클라이언트 객체가 첫 번째 인수로 전달됩니다. -
available?
: 지표를 보고해야 하는지 여부를 지정. 기본값은true
입니다.
프로메테우스 지표를 추가하는 Merge Request 예시.
module Gitlab
module Usage
module Metrics
module Instrumentations
class GitalyApdexMetric < PrometheusMetric
value do |client|
result = client.query('avg_over_time(gitlab_usage_ping:gitaly_apdex:ratio_avg_over_time_5m[1w])').first
break FALLBACK unless result
result['value'].last.to_f
end
end
end
end
end
end
새로운 지표 계기 클래스 생성
제너레이터는 클래스 이름을 인수로 사용하고 다음 옵션을 사용합니다:
-
--type=TYPE
필수입니다. 지표 유형을 나타냅니다.database
,generic
,redis
,numbers
중 하나여야 합니다. -
--operation
database
및numbers
유형에 필요합니다.-
database
의 경우:count
,distinct_count
,estimate_batch_distinct_count
,sum
,average
중 하나여야 합니다. -
numbers
의 경우:add
여야 합니다.
-
-
--ee
지표가 EE용인지 나타냅니다.
rails generate gitlab:usage_metric CountIssues --type database --operation distinct_count
create lib/gitlab/usage/metrics/instrumentations/count_issues_metric.rb
create spec/lib/gitlab/usage/metrics/instrumentations/count_issues_metric_spec.rb
서비스 핑 지표를 계기 클래스로 마이그레이션
이 가이드는 lib/gitlab/usage_data.rb
또는 ee/lib/ee/gitlab/usage_data.rb
에서 서비스 핑 지표를 계기 클래스로 마이그레이션하는 방법을 설명합니다.
- 지표 유형 선택:
-
계기 클래스의 위치 결정:
ee
내부에 있는지 여부이거나ee
외부에 있는지. -
계기 클래스 본문 채우기:
- 지표에 대한 코드 논리 추가. 이는
usage_data.rb
에서의 지표 구현과 유사할 수 있습니다. - 개별 지표에 대한 테스트 추가
spec/lib/gitlab/usage/metrics/instrumentations/
. - 서비스 핑에 대한 테스트 추가.
- 지표에 대한 코드 논리 추가. 이는
-
lib/gitlab/usage_data.rb
또는ee/lib/ee/gitlab/usage_data.rb
에서 코드 제거. -
spec/lib/gitlab/usage_data.rb
또는ee/spec/lib/ee/gitlab/usage_data.rb
에서 테스트 제거.
지표 문제 해결
가끔씩 지표가 즉시 명백하지 않은 이유로 실패할 때가 있습니다. 이러한 실패는 성능 문제나 다른 문제와 관련될 수 있습니다. 다음의 페어링 세션 비디오는 실제로 실패한 지표에 대한 조사 예시를 보여줍니다.