이 가이드는 메트릭 인스트루멘테이션을 사용하여 Service Ping 메트릭을 개발하는 방법을 설명합니다.

동영상 튜토리얼은 인스트루멘테이션 클래스를 통한 Service Ping 메트릭 추가를 참조하세요.

명명법#

• 인스트루멘테이션 클래스:

메트릭 클래스 중 하나인 DatabaseMetric, NumbersMetric 또는 GenericMetric을 상속합니다.

• Service Ping 메트릭의 값을 계산하는 로직을 구현합니다.

• 메트릭 정의 Service Data 메트릭 YAML 정의입니다.

• 하드닝(Hardening): 메서드를 하드닝한다는 것은 메서드가 안전하게 실패하도록 보장하는 프로세스로, -1과 같은 폴백 값을 반환합니다.

메트릭 인스트루멘테이션 작동 방식#

모든 메트릭은 service ping 페이로드에 포함되기 위해 대응하는 메트릭 정의가 있어야 합니다. 메트릭 정의에는 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입니다.

데이터베이스 메트릭을 추가하는 머지 리퀘스트 예시.

최적화 권장 사항 및 예시#

Service Ping 메트릭에 대한 단일 쿼리는 콜드 캐시로 1초 실행 시간을 초과해서는 안 됩니다.

• 특화된 인덱스를 사용하세요. 예시는 다음 머지 리퀘스트를 참조하세요:

예시 1

• 예시 2

• 정의된 start와 finish를 사용하세요. 이 값들은 메모이제이션되어 재사용될 수 있습니다. 이 예시 머지 리퀘스트를 참조하세요.

• 쿼리에서 조인 및 불필요한 복잡성을 피하세요. 이 예시 머지 리퀘스트를 참조하세요.

• distinct_count에 대해 사용자 정의 batch_size를 설정하세요. 이 예시 머지 리퀘스트를 참조하세요.

데이터베이스 메트릭 예시#

Count 예시#

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

Sum 예시#

# 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

Average 예시#

# 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 값을 반환합니다.

이 기능은 HyperLogLog 알고리즘을 사용하는 특정 칼럼에서 특정 ActiveRecord_Relation의 고유 개수를 추정합니다. 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))

Numbers 메트릭#

• 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 설정에 인스트루멘테이션 클래스 이름도 포함해야 합니다.

time_frame: 28d
instrumentation_class: IssuesBoardsCountMetric

Generic 메트릭#

generic 메트릭은 예를 들어 인스턴스의 데이터베이스 버전과 같이 다른 메트릭에 사용할 수 있습니다.

• value: 메트릭의 값을 지정합니다.

• available?: 메트릭을 보고해야 하는지 여부를 지정합니다. 기본값은 true입니다.

generic 메트릭을 추가하는 머지 리퀘스트 예시.

module Gitlab
  module Usage
    module Metrics
      module Instrumentations
        class UuidMetric < GenericMetric
          value do
            Gitlab::CurrentSettings.uuid
          end
        end
      end
    end
  end
end

Prometheus 메트릭#

이 인스트루멘테이션 클래스를 사용하면 Prometheus 클라이언트 객체를 value 블록의 인수로 전달하여 Prometheus 쿼리를 처리할 수 있습니다. 모든 Prometheus 오류 처리는 블록 자체에서 수행해야 합니다.

• value: 메트릭의 값을 지정합니다. Prometheus 클라이언트 객체가 첫 번째 인수로 전달됩니다.

• available?: 메트릭을 보고해야 하는지 여부를 지정합니다. 기본값은 true입니다.

Prometheus 메트릭을 추가하는 머지 리퀘스트 예시.

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

구현 후, 메트릭이 포함되고 예상대로 작동하는지 확인하기 위해 로컬에서 service ping을 실행해야 합니다.

Service Ping 메트릭을 인스트루멘테이션 클래스로 마이그레이션#

이 가이드는 Service Ping 메트릭을 lib/gitlab/usage_data.rb 또는 ee/lib/ee/gitlab/usage_data.rb에서 인스트루멘테이션 클래스로 마이그레이션하는 방법을 설명합니다.

• 메트릭 유형 선택:

• 데이터베이스 메트릭

• Numbers 메트릭

• Generic 메트릭

인스트루멘테이션 클래스의 위치 결정: ee 아래 또는 ee 외부.

인스트루멘테이션 클래스 파일 생성.

인스트루멘테이션 클래스 본문 채우기:

메트릭에 대한 코드 로직을 추가합니다. 이는 usage_data.rb의 메트릭 구현과 유사할 수 있습니다.

• 개별 메트릭에 대한 테스트를 추가합니다 spec/lib/gitlab/usage/metrics/instrumentations/.

• Service Ping에 대한 테스트를 추가합니다.

메트릭 정의 파일 생성.

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 동영상을 통해 메트릭 문제 해결 프로세스에 대해 자세히 알아보세요.