콘텐츠로 이동

Grafana 연동

Tuist 데이터 소스를 사용하면 Grafana에서 빌드, 테스트 및 캐시 메트릭(지속 시간, 실패 횟수, 캐싱으로 보고된 절감 시간 등)을 활용할 수 있습니다. 팀이 중요하게 생각하는 프로젝트와 메트릭을 중심으로 대시보드를 구성하거나, 회사 기존 대시보드에서 Tuist 메트릭을 다른 데이터 소스와 결합하세요. Grafana의 알림 규칙과 알림 채널을 활용해 빌드가 느려지거나 실패가 증가할 때 팀에 알리세요.

사용 가능한 메트릭#

테이블에는 읽기 쉬운 라벨과 해당 쿼리 식별자가 나열되어 있습니다. 빌드 헬스 쿼리는 metric 필드의 식별자를 사용하며, 빌드 및 테스트 지속 시간 쿼리는 series 필드에서 average, p50, p90 또는 p99를 선택합니다.

빌드 횟수 및 신뢰성#

메트릭 식별자 측정 항목
빌드 횟수 builds 기록된 빌드 수입니다.
성공한 빌드 successful_builds 성공적으로 완료된 빌드입니다.
실패한 빌드 failed_builds 실패한 빌드입니다.
취소된 빌드 cancelled_builds 취소된 것으로 기록된 빌드입니다. 빌드 시스템 차이점을 참조하세요.
빌드 성공률 success_rate 성공 ÷ (성공 + 실패), 백분율로 표시합니다.
실패 또는 느린 빌드 builds_needing_attention 실패하거나 느린 빌드로, 빌드당 한 번씩 계산됩니다.

빌드 및 테스트 지속 시간#

메트릭 식별자 측정 항목
평균 지속 시간 average 선택된 실행의 평균 지속 시간입니다.
중간값 지속 시간 p50 실행 지속 시간의 50번째 백분위수입니다.
90번째 백분위수 지속 시간 p90 실행의 90%가 이 값 이하인 지속 시간입니다.
99번째 백분위수 지속 시간 p99 실행의 99%가 이 값 이하인 지속 시간입니다.
느린 빌드 임계값 slow_build_threshold 90번째 백분위수 지속 시간, 또는 밀리초 단위로 설정한 고정 제한 값입니다.

테스트 지속 시간 메트릭은 Tuist에 기록된 테스트 실행을 사용합니다. 느린 빌드 임계값은 빌드에만 적용됩니다. 빌드 지속 시간이 해당 임계값을 초과하면 느린 빌드로 간주됩니다. 취소된 빌드는 별도로 계산되며 빌드 성공률에서 제외됩니다.

캐시 절감 효과#

메트릭 식별자 측정 항목
누적 작업 시간 절감(Gradle) cache_work_avoided 캐시 히트로 인해 피한 추정 작업 실행 시간의 합계입니다.
누적 작업 시간을 보고하는 빌드 cache_work_avoided_samples 완전한 추정값을 가진 빌드입니다.
보고된 캐시 시간 절감 cache_time_saved 보고된 경과 시간 절감의 합계입니다.
캐시 시간 절감을 보고하는 빌드 cache_time_saved_samples 유효한 절감 값을 가진 빌드입니다.

Gradle 플러그인은 로컬 및 원격 작업 캐시 히트에 대해 피한 작업을 자동으로 보고합니다. 각 캐시된 작업에 대해 Gradle이 저장한 원래 실행 시간에서 작업 복원 지속 시간을 차감하며, 최소값은 0입니다. 빌드 추정치는 이러한 값을 모두 더합니다. 병렬 작업은 중복될 수 있으므로 이는 누적 작업 시간이며, 절감된 경과 빌드 시간이 아닙니다. 최신 상태인 작업과 건너뛴 작업은 제외됩니다.

작업 캐시 히트가 없는 빌드는 0을 보고합니다. 캐시된 작업 중 원래 타이밍이 없거나, 텔레메트리가 불완전하거나, 사용자 정의 메타데이터 맵에 공간이 부족하면 플러그인은 추정치를 생략합니다. 이전 플러그인 버전과 다른 빌드 시스템은 이를 보고하지 않습니다. 커버리지를 확인하려면 보고 횟수를 총 빌드 수와 비교하세요.

보고된 경과 시간 절감은 tuist.cache_time_saved_ms 메타데이터에서 비롯됩니다. 이 메트릭은 자동 추정치와 별도로 유지됩니다.

빌드가 보고하지 않으면 캐시 절감 효과는 값이 없습니다. Once는 현재 이 측정을 기록하지 않습니다. 캐시 히트 및 미스율은 이 데이터 소스를 통해 사용할 수 없습니다.

테이블#

이러한 식별자는 쿼리의 queryType 필드 값입니다.

테이블 쿼리 유형 내용
워크로드별 헬스 buildWorkloads 빌드 횟수, 성공률, 중간값 및 90번째 백분위수 지속 시간입니다.
실패 카테고리 buildFailureReasons 모든 실패와 실패 카테고리별 횟수입니다.
최근 실패한 빌드 buildRecentFailures Tuist 링크가 포함된 최신 실패 100건입니다.

최근 실패에는 시작 시간, 지속 시간, 사용자, 브랜치 및 요청된 작업이 포함됩니다. 실패 카테고리는 verification, infrastructure_tooling 및 unknown입니다.

워크로드 요약 및 브랜치/워크로드 값 목록은 최대 1000개의 값을 반환합니다. 빌드 헬스 변수 쿼리는 최근 90일을 사용하며, 레거시 Gradle 변수 쿼리는 기존 기록 기간을 유지합니다. Bazel은 도구에서 보고한 빌드 사용자를 표시합니다. 다른 통합은 보고 자격 증명과 연결된 계정을 표시합니다. 기록된 사용자가 없을 경우 과거 Bazel 및 Once 실행, 그리고 프로젝트 자격 증명으로 보고된 Once 실행은 알 수 없음(Unknown)으로 표시됩니다.

일치하는 실패를 찾으려면 빌드 실행에서 실패 카테고리 필터를 사용하세요. 카테고리는 빌드 세부 정보에 표시되며 의미를 설명하는 정보 힌트가 제공됩니다. 기본 개요 및 빌드 실행 테이블은 기존 열을 유지합니다. 성공, 취소 및 완료되지 않은 빌드에는 실패 카테고리가 없습니다. Gradle의 캐시 분석 카드와 빌드 세부 정보는 누적 작업 시간 절감을 표시하며, 툴팁은 추정치와 병렬 작업의 영향을 설명합니다. 캐시 위젯은 동일한 필터를 사용하여 선택한 범위를 바로 직전의 동일 길이 기간과 비교합니다. 비교는 중립적입니다. 더 큰 총합은 더 많은 빌드를 반영할 수 있습니다. 이전 추정치가 누락되면 비교가 표시되지 않으며, 기록된 기준선이 0인 경우 백분율이 아닌 절대 증가분을 표시합니다.

표준 대시보드#

빌드 헬스 대시보드를 가져온 다음 데이터 소스와 프로젝트를 선택하세요. 여기에는 빌드 횟수, 성공률, 중간값 및 90번째 백분위수 지속 시간, 느린 빌드 임계값, 중립적인 실패 또는 느린 빌드 횟수, 그룹화된 캐시 절감 효과 및 보고 커버리지, 그리고 세 가지 실패 및 워크로드 테이블이 포함됩니다. 필요에 따라 다른 사용 가능한 메트릭용 패널을 추가하세요. 자동 느린 임계값은 선택한 기간 자체의 90번째 백분위수입니다. 이를 초과하는 빌드가 반드시 회귀를 나타내는 것은 아닙니다. 지속 시간 대상 알림을 위해 고정 임계값을 설정하세요. 캐시 패널은 Gradle의 자동 누적 작업 시간 추정치를 그 커버리지와 함께 우선시하고, 그다음으로 명시적으로 보고된 경과 시간 절감 효과를 해당 커버리지와 함께 표시합니다.

빌드 시스템#

빌드 헬스 쿼리와 표준 대시보드는 Bazel, Cargo, Once, Gradle 및 Xcode를 지원합니다. Tuist는 프로젝트에서 빌드 시스템을 선택합니다. 혼합 프로젝트는 현재 빌드 헬스 쿼리나 표준 대시보드에서 지원되지 않습니다.

빌드 시스템 워크로드 취소 보고 캐시 절감 효과
Bazel 명령어 종료 코드 8(run 제외) 사용자 정의 메타데이터 필요
Cargo 명령어 구분되지 않음; 횟수는 0 경과 시간 절감 효과는 사용자 정의 메타데이터가 필요합니다. 컴파일러 작업 회피는 경과 시간 절감 효과가 아닙니다.
Once 명령어 종류 기록된 취소 사유 기록되지 않음
Gradle 작업 그룹 보고된 취소 자동 작업 회피 추정치; 경과 시간 절감 효과는 사용자 정의 메타데이터 필요
Xcode 스킴 구분되지 않음; 횟수는 0 사용자 정의 메타데이터 필요

처리 중인 기록과 완료되지 않은 실행은 제외됩니다. Bazel에는 빌드, 테스트, 실행 및 커버리지 명령어가 포함됩니다. Once에는 finalized된 빌드, 테스트 및 일반 실행이 포함됩니다. Cargo에는 build, check 및 test-build와 같은 빌드 명령어가 포함되며, 레거시 테스트 실행 보고서는 빌드 헬스에서 제외됩니다. Cargo의 최근 실패는 기록된 시작 시간을 사용하며(가능한 경우), 없으면 삽입 시간을 대체합니다. 누락된 지속 시간은 0 대신 사용 불가 상태로 유지됩니다.

Gradle은 작업을 계측된 테스트, 단위 테스트, 린트/검사, 어셈블/패키지 또는 기타 순서로 우선순위에 따라 그룹화합니다. 각 빌드는 하나의 워크로드에 속합니다. 사용자 정의 메타데이터는 Xcode, Bazel, Cargo 및 Gradle의 워크로드를 재정의할 수 있습니다.

실패 카테고리#

카테고리 의미 기록된 증거
verification 코드 컴파일, 링크, 테스트 또는 검사 실패. Gradle 검증 또는 컴파일 예외 및 알려진 실패 작업 유형; Xcode 컴파일러 및 링커 문제; Bazel 구조화된 비영 컴파일러/테스트 액션 결과; Cargo 기록된 rustc 컴파일 실패; Once 테스트 실패 또는 컴파일, 링크, 테스트, 린트 또는 검사로 명시적으로 선언된 실패한 액션.
infrastructure_tooling 도구, 의존성 또는 환경 실패로 인해 빌드를 정상적으로 실행할 수 없습니다. Gradle 구성, 의존성 해결, 입출력 또는 메모리 실패; Bazel 구조화된 인프라 실패 및 문서화된 종료 코드; Once 인프라 액션 오류.
unknown 보고서에 실패를 분류할 충분한 증거가 포함되어 있지 않습니다. 임의의 명령어, 누락된 진단 정보 및 구조화된 증거가 없는 이전 보고서.

빌드 스크립트의 오류를 포함한 Gradle 구성 단계 실패는 작업 실행을 진행할 수 없으므로 인프라/툴링 아래에 그룹화됩니다.

명시적인 카테고리 메타데이터나 기록된 rustc 컴파일 실패가 없는 Cargo 실패는 unknown로 유지됩니다. 실패한 check 또는 test-build 명령어만으로는 검증 실패로 간주되지 않습니다. Cargo 작업 재사용 카운터와 추정된 컴파일러 작업 회피는 경과 캐시 절감 효과나 Gradle의 누적 작업 시간 메트릭을 제공하지 않습니다.

명시적인 tuist.failure_category 메타데이터는 자동 분류를 재정의합니다. 그렇지 않으면, 빌드에서 둘 다 발생하는 경우 인프라 증거가 검증보다 우선합니다. 실패한 임의의 스크립트는 컴파일러 또는 테스트 실패로 가정되지 않습니다. 과거 보고서는 Tuist가 이미 저장한 증거를 사용할 수 있지만, 새로운 리포터 필드는 누락된 정보를 백필하지 않습니다. 자동 리포터 메타데이터는 기존 20개 항목 사용자 정의 메타데이터 제한 내의 사용 가능한 공간을 사용합니다.

buildFailureReasons 응답은 호환성을 위해 all 행을 유지합니다. 표준 대시보드는 실패 카테고리 차트에서 해당 합계를 필터링하고 총 실패 횟수를 별도로 표시합니다. 레거시 gradleFailureReasons 쿼리는 원래의 세 가지 카테고리 행을 유지합니다.

쿼리 옵션#

수치형 쿼리는 다음 queryType 값을 사용합니다:

쿼리 쿼리 유형
빌드 헬스 buildHealth
Xcode 빌드 지속 시간 buildDuration
테스트 지속 시간 testDuration

resultMode 필드는 결과가 반환되는 방식을 제어합니다:

결과 값 동작
시계열 series 각 간격에 대한 값입니다.
전체 기간 total 범위 내 모든 실행에서 계산된 단일 값입니다.

필터 레이블은 다음 쿼리 필드에 매핑됩니다:

필터 쿼리 필드 사용 가능 위치
환경 environment 모든 쿼리
브랜치 gitBranch 빌드 헬스 쿼리 및 테이블
워크로드 workload 빌드 헬스 쿼리 및 테이블
상태 status 빌드 헬스 쿼리, 테이블 및 Xcode 지속 시간
스킴 scheme Xcode 빌드 및 테스트 지속 시간
구성 configuration Xcode 빌드 지속 시간
빌드 유형 category Xcode 빌드 지속 시간

환경 값은 any, ci(자동화된 빌드) 및 local입니다. 상태 값은 success, failure이며, 빌드 헬스 쿼리의 경우 cancelled입니다. 모든 상태를 포함하려면 값을 생략하세요. 빌드 유형 값은 clean 및 incremental입니다. 둘 다 포함하려면 값을 생략하세요.

빈 빌드 헬스 간격은 카운트가 0이며 평균 지속 시간, 지속 시간 백분위수 또는 성공률 값이 없습니다. 느린 빌드 임계값은 여전히 선택한 전체 범위를 사용합니다. 별도의 테스트 지속 시간 쿼리는 빈 시계열 간격에 대해 0을 반환합니다. 전체 기간 백분위수는 간격 백분위수가 아닌 실행에서 계산됩니다. 빌드 헬스 백분위수는 정확한 집계를 사용하며, 별도의 Xcode 및 테스트 지속 시간 쿼리는 근사 백분위수를 사용합니다.

빌드 헬스 시계열은 선택한 범위의 시작 부분에 부분적인 첫 번째 버킷을 배치하여 표시되도록 합니다. 레거시 Gradle 쿼리는 원래 버킷 타임스탬프를 유지합니다.

모든 쿼리는 최대 366일까지의 날짜 범위를 허용합니다. 경계와 타임스탬프는 다음과 같이 다릅니다:

쿼리 사용된 타임스탬프 범위 경계
빌드 헬스: Xcode, Bazel, Cargo, Gradle 레코드 삽입 시간 시작 포함, 종료 제외
빌드 헬스: Once 실행 시작 시간 시작 포함, 종료 제외
Xcode 빌드 지속 시간 레코드 삽입 시간 시작 및 종료 제외
테스트 지속 시간 기록된 실행 시간 시작 및 종료 포함

대시보드 변수#

프로젝트와 지원되는 필터에 대시보드 변수를 사용하세요. 브랜치와 워크로드 변수는 다음 쿼리를 사용합니다:

변수 쿼리
브랜치 buildBranches account/project
워크로드 buildWorkloads account/project

필터는 하나의 정확한 값을 허용합니다. 브랜치와 워크로드 변수의 경우, 모두(All) 옵션의 사용자 지정 값을 __tuist_all__로 설정하세요. 다른 필터는 내장된 모두(Any) 옵션이나 빈 값을 사용합니다. 다중 선택과 정규식은 지원되지 않습니다.

사용자 지정 메타데이터 보고#

Xcode, Bazel, Cargo 및 Gradle 빌드는 다음 선택적 메타데이터 값을 허용합니다:

키 허용된 값
tuist.workload 기본 그룹화를 대체하는 워크로드 이름입니다.
tuist.failure_category verification 또는 infrastructure_tooling.
tuist.cache_work_avoided_ms Gradle 전용. 자동으로 보고되는 작업 회피 추정치로, 최대 365일까지의 정수 밀리초 단위입니다.
tuist.cache_time_saved_ms 0에서 31,536,000,000(365일)까지의 정수 밀리초입니다.

빌드 통합의 사용자 지정 메타데이터 구성을 통해 이를 제공하세요:

json
{
"custom_metadata": {
"values": {
"tuist.workload": "Release verification",
"tuist.failure_category": "verification",
"tuist.cache_time_saved_ms": "12000"
}
}
}

해당 빌드에 대한 경과 시간 측정값이나 문서화된 추정치가 있을 때만 캐시 절감량을 보고하세요. 작업이 동시에 실행될 때는 캐시 히트와 누적 작업 지속 시간만으로 경과 절감량을 결정할 수 없습니다. 누락된 캐시 절감량은 알 수 없는 상태로 남습니다. 누락된 실패 카테고리 메타데이터는 빌드 시스템에서 설명한 대로 기록된 증거로 대체됩니다. 데이터 보존 정책은 변경되지 않습니다.

알림 및 Slack#

숫자 지표를 사용하여 Grafana 관리 알림 규칙을 생성하세요. 예를 들어:

지표 식별자 예시 조건
빌드 성공률 success_rate 99% 미만
실패한 빌드 failed_builds 0 초과
90번째 백분위수 지속 시간 p90 팀의 지속 시간 제한 초과

평가 기간 동안 단일 값을 얻으려면 전체 기간을 사용하거나 시계열을 단일 값으로 축소하세요. 전체 기간 모드의 지속 시간 쿼리에서는 하나의 시리즈를 선택하세요.

  • 고정된 프로젝트와 필터 값을 사용하세요. 백그라운드 알림 평가 중에는 대시보드 변수를 사용할 수 없습니다.
  • 알림에는 숫자 쿼리를 사용하세요. 워크로드를 모니터링하려면 빌드 헬스 쿼리를 해당 워크로드에 맞게 필터링하세요.
  • 빌드나 보고된 캐시 절감량이 없는 간격에 대해 규칙의 데이터 없음 동작을 설정하세요.

Slack 연락처 포인트를 구성하고 Grafana의 알림 정책을 통해 규칙을 라우팅하세요. Grafana가 알림을 전송하고 Slack 자격 증명을 저장합니다.

기존 대시보드 업그레이드#

기존 지속 시간 패널은 쿼리, 필터, 시리즈 이름 및 단위를 유지합니다. 저장된 Gradle 헬스 패널과 변수도 계속 작동합니다.

공유 빌드 헬스 쿼리를 사용하려면 표준 대시보드를 별도로 가져오세요. 기존 대시보드는 자동으로 마이그레이션되지 않습니다. 공유 쿼리는 빌드 헬스 엔드포인트를 제공하는 Tuist 서버가 필요하며, 기존 지속 시간 쿼리는 이전 서버에서도 계속 작동합니다.

요구 사항#

  • Grafana 10.4 이상.
  • 차트로 표시하려는 프로젝트와 지표를 읽을 수 있는 권한이 부여된 Tuist 토큰입니다. 아래의 인증을 참조하세요.

인증#

대시보드와 백그라운드 알림 평가에는 계정 토큰을 사용하세요. 빌드 지표에는 project:builds:read를, 테스트 지속 시간에는 project:tests:read를 부여하고, 차트로 표시하려는 프로젝트에 대한 접근을 제한하세요. 사용하는 지표에 필요한 범위만 허용하면 됩니다. 토큰을 생성하려면 토큰 생성 지침을 따르세요.

이 통합은 해당 프로젝트용 기존 프로젝트 토큰과 사용자의 읽기 권한이 있는 사용자 액세스 토큰도 허용합니다. 사용자 액세스 토큰은 유효 기간이 짧습니다. Grafana는 제공한 토큰을 저장하며 갱신하거나 로컬 Tuist 로그인을 재사용하지 않으므로, 만료되면 교체하세요. 계정 토큰을 사용하면 사용자의 로그인 세션과 독립적으로 프로젝트 접근, 권한 및 만료를 제어할 수 있습니다.

구성#

데이터 소스를 추가하고 다음을 설정하세요:

필드 저장된 설정 참고
서버 URL jsonData.url 기본값은 https://tuist.dev입니다.
토큰 secureJsonData.apiToken Tuist 베어러 토큰으로, 암호화되어 저장됩니다.

연결을 확인하려면 Save & test를 선택하세요. Grafana는 접근 가능한 프로젝트를 나열한 후 첫 번째 프로젝트에 대해 빌드 및 테스트 읽기 권한을 확인합니다.

설치#

Grafana 카탈로그에서#

발행되면 Connections → Add new connection → Tuist에서 다른 데이터 소스처럼 설치하거나, grafana-cli plugins install tuist-metrics-datasource를 사용하여 설치하세요.

발행 전 (자체 호스팅 Grafana)#

플러그인은 카탈로그 승인을 받을 때까지 서명되지 않은 상태입니다. 자체 호스팅 인스턴스에서는 다음 중 하나를 수행할 수 있습니다:

  • 서명 없이 허용 — allow_loading_unsigned_plugins에 tuist-metrics-datasource를 추가하거나(또는 GF_PLUGINS_ALLOW_LOADING_UNSIGNED_PLUGINS=tuist-metrics-datasource) 빌드된 플러그인을 플러그인 디렉터리에 넣으세요.
  • 인스턴스용 개인 서명 — npm run sign -- --rootUrls https://grafana.example.com(URL은 인스턴스의 root_url와 일치해야 함)를 실행한 후 zip 파일을 배포하세요.

Grafana Cloud는 카탈로그의 플러그인만 필요하며, 서명되지 않거나 수동으로 업로드된 플러그인은 지원하지 않습니다.