명명법
작동 방식
데이터베이스 메트릭
- 최적화 권장 및 예시
- 데이터베이스 메트릭 예시
집계된 지표
숫자 지표
일반적인 지표
프로메테우스 지표
새로운 지표 계기 클래스 생성
서비스 핑 지표를 계기 클래스로 마이그레이션
지표 문제 해결

메트릭 이성구성 가이드

이 가이드에서는 메트릭 이성구성을 사용하여 Service Ping 메트릭을 개발하는 방법에 대해 설명합니다.

비디오 자습서는 instrumentation 클래스를 통한 Service Ping 메트릭 추가를 참조하십시오.

명명법

이성구성 클래스:
- 메트릭 클래스 중 하나를 상속함: DatabaseMetric, NumbersMetric 또는 GenericMetric.
- Service Ping 메트릭의 값을 계산하는 논리를 구현함.
메트릭 정의: 서비스 데이터 메트릭 YAML 정의입니다.
강화: 메서드 강화는 메서드가 안전하게 실패하여 -1과 같은 대체 값을 반환하도록 하는 프로세스입니다.

작동 방식

메트릭 정의에는 instrumentation_class 필드가 있으며, 클래스로 설정할 수 있습니다.

지정된 이성구성 클래스는 기존의 메트릭 클래스 중 하나를 상속해야 합니다: DatabaseMetric, NumbersMetric 또는 GenericMetric.

현재의 관례는 단일 이성구성 클래스가 단일 메트릭에 해당한다는 것입니다.

이성구성 클래스를 사용하면 메트릭이 개별적으로 안전하게 실패하여 Service Ping 생성 전체 프로세스를 중단시키지 않을 수 있습니다.

데이터베이스 메트릭

가능한 경우 데이터베이스 메트릭 대신 내부 이벤트 추적을 사용하는 것이 좋습니다. 데이터베이스 메트릭은 큰 GitLab 인스턴스의 데이터베이스에 불필요한 부하를 줄 수 있으며, 잠재적인 최적화가 인스턴스 성능에 영향을 미칠 수 있습니다.

데이터베이스 메트릭을 사용하여 데이터베이스에 저장된 데이터를 추적할 수 있습니다. 예를 들어, 특정 인스턴스에 존재하는 이슈 수를 카운트할 수 있습니다.

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을 참조하세요:
- 예시 1
- 예시 2
정의된 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 값이 반환됩니다.

이 기능은 주어진 열의 특정 ActiveRecord_Relation에 대한 고유한 값의 추정 카운트를 처리하는 것으로, 이는 HyperLogLog 알고리즘을 사용합니다. HyperLogLog 알고리즘이 확률적이므로 결과에는 항상 오류가 포함됩니다. 가장 높게 발견된 오류율은 4.9%입니다.

올바르게 사용하면 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))
```

집계된 지표

Product Intelligence Office Hours Oct 6th에서 집계된 지표 소개 영상을 시청하세요.

집계된 지표 기능은 예를 들어 의사 난수화된 사용자 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에서 테스트 제거.

지표 문제 해결

가끔씩 지표가 즉시 명백하지 않은 이유로 실패할 때가 있습니다. 이러한 실패는 성능 문제나 다른 문제와 관련될 수 있습니다. 다음의 페어링 세션 비디오는 실제로 실패한 지표에 대한 조사 예시를 보여줍니다.

다음 위치에서 비디오를 확인하세요: Product Intelligence Office Hours Oct 27th. 지표 문제 해결 프로세스에 대해 더 알아보세요.

메트릭 이성구성 가이드

명명법

작동 방식

데이터베이스 메트릭

최적화 권장 및 예시

데이터베이스 메트릭 예시

카운트 예시

배치 카운터 예시

고유한 배치 카운터 예시

합계 예시

평균 예시

예상 배치 카운터

`estimate_batch_distinct_count` 메서드

집계된 지표

이벤트 소스 집계된 지표

데이터베이스 소스 집계된 지표

집계를 위해 지표를 지속

새로운 집계된 지표 정의 추가

이용 제약이 있는 집계된 지표

숫자 지표

일반적인 지표

프로메테우스 지표

새로운 지표 계기 클래스 생성

서비스 핑 지표를 계기 클래스로 마이그레이션

지표 문제 해결

도움말

기능 사용 가능성과 제품 평가판

도움받기

메트릭 이성구성 가이드

명명법

작동 방식

데이터베이스 메트릭

최적화 권장 및 예시

데이터베이스 메트릭 예시

카운트 예시

배치 카운터 예시

고유한 배치 카운터 예시

합계 예시

평균 예시

예상 배치 카운터

estimate_batch_distinct_count 메서드

집계된 지표

이벤트 소스 집계된 지표

데이터베이스 소스 집계된 지표

집계를 위해 지표를 지속

새로운 집계된 지표 정의 추가

이용 제약이 있는 집계된 지표

숫자 지표

일반적인 지표

프로메테우스 지표

새로운 지표 계기 클래스 생성

서비스 핑 지표를 계기 클래스로 마이그레이션

지표 문제 해결

도움말

기능 사용 가능성과 제품 평가판

도움받기

`estimate_batch_distinct_count` 메서드