메트릭 리포트

메트릭 리포트 (Metrics reports)

메트릭 리포트는 머지 리퀘스트에 사용자 정의 메트릭을 표시해 브랜치 간 성능, 메모리 사용량, 기타 측정값을 추적할 수 있게 해줘요.

메트릭 리포트를 사용해:

  • 메모리 사용량 변화를 모니터링하세요.
  • 부하 테스트 결과를 추적하세요.
  • 코드 복잡도를 측정하세요.
  • 코드 커버리지 통계를 비교하세요.

출처: 문서

본문

메트릭 처리 워크플로우

파이프라인이 실행되면 GitLab은 리포트 아티팩트에서 메트릭을 읽어 비교를 위해 문자열 값으로 저장해요. 기본 파일 이름은 metrics.txt이에요.

머지 리퀘스트의 경우 GitLab은 기능 브랜치의 메트릭을 대상 브랜치의 값과 비교해 머지 리퀘스트 위젯에 다음 순서로 표시해요:

  • 값이 변경된 기존 메트릭.
  • 머지 리퀘스트가 추가한 메트릭(New 배지로 표시).
  • 머지 리퀘스트가 제거한 메트릭(Removed 배지로 표시).
  • 값이 변경되지 않은 기존 메트릭.

기준 파이프라인 선택

브랜치 간 메트릭을 비교하기 위해 GitLab은 다음 과정으로 대상 브랜치에서 기준 파이프라인(baseline pipeline)을 식별해요:

  1. 이런 커밋 SHA에 일치하는 대상 브랜치의 파이프라인을 순서대로 확인해요:머지 리퀘스트 파이프라인이 생성된 시점의 대상 브랜치 팁. 이 SHA는 머지 리퀘스트 파이프라인에서만 사용할 수 있어요.머지 베이스 커밋(소스 브랜치와 대상 브랜치의 공통 조상).머지 리퀘스트 diff의 시작 커밋.
  2. 일치하는 파이프라인이 있는 첫 번째 SHA에 대해 가장 최근에 생성된 파이프라인(파이프라인 ID 기준)을 선택해요.

기준 파이프라인 선택은:

  • 파이프라인 상태로 필터링하지 않아요. 어떤 상태(success, failed, canceled, skipped)의 파이프라인이든 기준으로 선택될 수 있어요.
  • 기준 파이프라인에 메트릭 리포트 아티팩트가 있는지 확인하지 않아요. 기준 파이프라인이 존재하지만 메트릭 아티팩트가 없다면 기능 브랜치의 모든 메트릭이 새 것으로 표시돼요.

메트릭 비교 위젯은 기능 브랜치 파이프라인이 완료 상태이고 메트릭 리포트 아티팩트가 있을 때만 나타나요.

파이프라인 유형은 어떤 커밋 SHA가 먼저 일치하는지에 영향을 줘요:

  • 머지 리퀘스트 파이프라인: 대상 브랜치 팁 SHA가 보통 사용 가능하므로, 기준은 머지 리퀘스트 파이프라인 생성 시점의 대상 브랜치 팁에 있는 최신 파이프라인인 경우가 많아요.
  • 브랜치 파이프라인: 대상 브랜치 팁 SHA를 사용할 수 없으므로 대신 머지 베이스 커밋을 사용해요. 기준은 공통 조상 커밋에서 대상 브랜치의 최신 파이프라인이에요.

비교에 사용할 기준이 항상 있도록 하려면:

  • 메트릭 리포트 아티팩트를 생성하는 대상 브랜치 파이프라인을 실행하세요.
  • 브랜치 파이프라인을 사용한다면 머지 베이스 커밋에 대상 브랜치의 파이프라인이 있는지 확인하세요.

메트릭 리포트 구성하기

머지 리퀘스트에서 사용자 정의 메트릭을 추적하려면 CI/CD 파이프라인에 메트릭 리포트를 추가하세요.

전제 조건:

  • 메트릭 파일이 OpenMetrics 텍스트 형식이어야 해요.

메트릭 리포트를 구성하려면:

  1. .gitlab-ci.yml 파일에 메트릭 리포트를 생성하는 잡을 추가하세요.
  2. OpenMetrics 형식으로 메트릭을 생성하는 스크립트를 잡에 추가하세요.
  3. artifacts:reports:metrics로 메트릭 파일을 업로드하도록 잡을 구성하세요.

예를 들면:

metrics:
  stage: test
  script:
    - echo 'memory_usage_bytes 2621440' > metrics.txt
    - echo 'response_time_seconds 0.234' >> metrics.txt
    - echo 'test_coverage_percent 87.5' >> metrics.txt
    - echo '# EOF' >> metrics.txt
  artifacts:
    reports:
      metrics: metrics.txt

파이프라인이 실행된 후 메트릭 리포트가 머지 리퀘스트 위젯에 표시돼요.

Metrics report widget in a merge request displaying metric names and values.

추가 형식 사양과 예시는 Prometheus 텍스트 형식 상세를 참고하세요.

문제 해결

메트릭 리포트를 사용할 때 다음 문제가 발생할 수 있어요.

메트릭 리포트가 변경되지 않음

머지 리퀘스트에서 메트릭 리포트를 볼 때 Metrics report scanning detected no new changes가 표시될 수 있어요.

이 문제는 다음 때 발생해요:

  • 대상 브랜치에 비교할 기준 메트릭 리포트가 없는 경우.
  • GitLab 구독에 메트릭 리포트가 포함되지 않은 경우(Premium 또는 Ultimate 필요).

이 문제를 해결하려면:

  1. GitLab 구독 등급에 메트릭 리포트가 포함되어 있는지 확인하세요.
  2. 대상 브랜치에 메트릭 리포트가 구성된 파이프라인이 있는지 확인하세요. 기준이 있도록 메트릭 리포트 아티팩트를 생성하는 대상 브랜치 파이프라인을 실행하세요.
  3. 메트릭 파일이 유효한 OpenMetrics 형식인지 확인하세요.

더 알아보기

다음으로는 artifacts:reports:metrics 키워드와 부하 성능 테스트 문서를 함께 보면, 성능·메모리 등 다양한 측정값을 MR에서 한눈에 추적하는 방법을 익힐 수 있어요.