메트릭 이성구성 가이드

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

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

명명법

  • 이성구성 클래스:
    • 메트릭 클래스 중 하나를 상속함: DatabaseMetric, NumbersMetric 또는 GenericMetric.
    • Service Ping 메트릭의 값을 계산하는 논리를 구현함.
  • 메트릭 정의: 서비스 데이터 메트릭 YAML 정의입니다.

  • 강화: 메서드 강화는 메서드가 안전하게 실패하여 -1과 같은 대체 값을 반환하도록 하는 프로세스입니다.

작동 방식

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

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

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

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

데이터베이스 메트릭

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

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

  • operation: 주어진 relation에 대한 작업 중 하나인 count, distinct_count, sumaverage.
  • relation: 수행할 operation을 위한 ActiveRecord::Relation을 반환하는 람다를 할당합니다. 할당된 람다는 최대 하나의 매개변수를 허용할 수 있습니다. 매개변수는 메트릭 정의의 options 키 아래에 해시로 저장됩니다.
  • start: 배치 카운팅의 시작 값을 지정합니다. 기본값은 relation.minimum(:id)입니다.
  • finish: 배치 카운팅의 끝 값을 지정합니다. 기본값은 relation.maximum(:id)입니다.
  • cache_start_and_finish_as: startfinish 값의 캐시 키를 지정하고 그 값을 캐싱합니다. startfinish가 비용이 많이 드는 쿼리인 경우에는 이 호출을 사용하여 여러 메트릭 계산 사이에서 다시 사용되어야 합니다.
  • available?: 메트릭이 보고되어야 하는지를 지정합니다. 기본값은 true입니다.
  • timestamp_column: 선택적으로 메트릭에 사용되는 타임스탬프 열을 지정합니다. 기본값은 created_at입니다.

데이터베이스 메트릭을 추가하는 Merge Request의 예시를 참조하세요.

최적화 권장 및 예시

Service Ping 메트릭에 대한 단일 쿼리는 콜드 캐시를 가진 1초 실행 시간 이하로 유지해야 합니다.

  • 전용 인덱스를 사용하세요. 예시는 다음 Merge Request을 참조하세요:
  • 정의된 startfinish를 사용하세요. 이러한 값은 메모이제이션되어 재사용될 수 있으며, 다음과 같은 예시 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 값이 반환됩니다.

caution
이 기능은 주어진 열의 특정 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와 같은 일대다 관계를 가져서는 안됩니다.
  • startfinish 인수는 항상 다른 열을 의미하는 고유한 값에 대한 기본 키 관계 값을 나타내어야 합니다. 예를 들어:

      estimate_batch_distinct_count(::Note, :author_id, start: ::Note.minimum(:id), finish: ::Note.maximum(:id))
    

예시:

  1. 단순 실행의, 제공된 관계만 있는 추정 배치 카운터 실행, 반환된 값은 Project 관계의 id 열(기본 키)에 있는 고유한 값의 추정 개수를 나타냅니다:

      estimate_batch_distinct_count(::Project)
    
  2. 추정 배치 카운터 실행의 복잡한 예시, 제공된 관계에 추가 필터 적용 (.where(time_period)), 사용자 지정 열(:author_id)에 있는 고유한 값의 추정 개수, 그리고 startfinish 매개변수가 함께 제공된 관계의 범위를 정의하는 경계를 적용합니다:

      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 metricsEvent sourced aggregated metrics에 설명되어 있습니다.
  • options.aggregate.attribute: 이벤트를 통해 집계되는 속성을 가리키는 정보입니다.
  • time_frame: 하나 이상의 유효한 시간 프레임. 이를 사용하여 특정 기간 내의 이벤트를 대상으로 한 집계된 지표에 포함된 데이터를 제한할 수 있습니다. 유효한 시간 프레임은 다음과 같습니다:
    • 7일: 최근 7일간의 데이터.
    • 28일: 최근 28일간의 데이터.
    • 전체: 모든 과거 데이터, database 소스의 집계된 지표에만 사용 가능합니다.
  • data_source: 집계된 지표에 포함된 모든 이벤트 데이터를 수집하는 데 사용되는 데이터 소스입니다. 유효한 데이터 소스는 다음과 같습니다:

예를 들어, 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 인스턴스에서 수집된 데이터 간에 큰 차이가 있을 수 있다는 점을 기억하는 것이 중요합니다.

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

데이터베이스에서 수집한 이벤트들을 기반으로 한 지표의 집계를 선언하려면, 다음 단계를 따르십시오:

  1. 집계를 위해 지표를 지속.
  2. 새로운 집계 지표 정의 추가.

집계를 위해 지표를 지속

추정 배치 카운터로 계산된 지표만 집계된 지표에 유지될 수 있습니다. 지속하려면, 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 databasenumbers 유형에 필요합니다.
    • 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에서 서비스 핑 지표를 계기 클래스로 마이그레이션하는 방법을 설명합니다.

  1. 지표 유형 선택:
  1. 계기 클래스의 위치 결정: ee 내부에 있는지 여부이거나 ee 외부에 있는지.

  2. 계기 클래스 파일 생성.

  3. 계기 클래스 본문 채우기:

    • 지표에 대한 코드 논리 추가. 이는 usage_data.rb에서의 지표 구현과 유사할 수 있습니다.
    • 개별 지표에 대한 테스트 추가 spec/lib/gitlab/usage/metrics/instrumentations/.
    • 서비스 핑에 대한 테스트 추가.
  4. 지표 정의 파일 생성.

  5. lib/gitlab/usage_data.rb 또는 ee/lib/ee/gitlab/usage_data.rb에서 코드 제거.

  6. spec/lib/gitlab/usage_data.rb 또는 ee/spec/lib/ee/gitlab/usage_data.rb에서 테스트 제거.

지표 문제 해결

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

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