CI 통합 프로파일링

CI 통합 프로파일링은 자동 빌드에서 전송하는 텔레메트리에 build_id를 붙이고 Framedash에서 빌드별 퍼포먼스를 확인하는 방식입니다. 현재 제공되는 기능은 빌드 필터, Regression 페이지, framedash builds, CI에서 실행하는 framedash perf-diff 게이트, framedash run-profile-test 러너, 임계값 프로파일, 정적 임계값 알림입니다. Framedash가 호스팅하는 프로파일링 작업이나 이전 빌드 대비 알림은 아직 제공되지 않습니다.

작동 원리

CI 빌드: 게임 빌드 생성
자동 테스트: 사전 정의된 시나리오를 자동 실행
텔레메트리 수집: SDK가 CI build_id와 함께 퍼포먼스 데이터를 전송
대시보드 확인: Regression 페이지나 빌드 필터로 빌드를 비교
CI 게이트: framedash run-profile-test (또는 framedash builds + framedash perf-diff)를 실행해 빌드 간 회귀 발생 시 빌드를 실패시킴
선택적 알림: 임계값 프로파일과 알림 규칙으로 FPS, 프레임 타임, 메모리의 정적 기준을 감시

설정

1. CI 환경에서의 SDK 설정

SDK 초기화 시 build_id를 CI 환경 변수에서 설정합니다.

Unity / Godot

TelemetrySDK.Initialize(
    apiKey: System.Environment.GetEnvironmentVariable("FRAMEDASH_API_KEY"),
    buildId: System.Environment.GetEnvironmentVariable("FRAMEDASH_BUILD_ID"));

UE5

if (auto* Subsystem = GetGameInstance()->GetSubsystem<UFramedashSubsystem>())
{
    FString ApiKey = FPlatformMisc::GetEnvironmentVariable(TEXT("FRAMEDASH_API_KEY"));
    FString BuildId = FPlatformMisc::GetEnvironmentVariable(TEXT("FRAMEDASH_BUILD_ID"));
    // EndpointUrl에 빈 문자열을 전달하여 기본값을 사용합니다.
    Subsystem->InitializeTelemetry(ApiKey, TEXT(""), BuildId);
}

2. 자동 세션 태그 지정

자동화 테스트 진입점에서 자동 세션 API를 한 번 호출하면 모든 이벤트에 CI 빌드 및 브랜치/커밋/시나리오 정보가 태그됩니다. BeginAutomatedSessionFromEnvironment()는 framedash run-profile-test가 내보내는 FRAMEDASH_BUILD_ID / FRAMEDASH_GIT_BRANCH / FRAMEDASH_GIT_COMMIT / FRAMEDASH_TEST_SCENARIO 변수를 읽습니다:

Unity / Godot

TelemetrySDK.Instance.BeginAutomatedSessionFromEnvironment();
// ... 프로파일링 시나리오 실행 ...
TelemetrySDK.Instance.EndAutomatedSession();

UE5

if (auto* Subsystem = GetGameInstance()->GetSubsystem<UFramedashSubsystem>())
{
    Subsystem->BeginAutomatedSessionFromEnvironment();
    // ... 프로파일링 시나리오 실행 ...
    Subsystem->EndAutomatedSession();
}

빌드 ID는 최상위 build_id 필드로 기록되고, 브랜치, 커밋, 시나리오는 ci.branch / ci.commit / ci.scenario 어트리뷰트로 전달됩니다.

3. 테스트 시나리오 정의

각 맵/영역을 순회하는 테스트 시나리오를 작성하여 일관된 데이터를 수집합니다.

4. 프로파일링 게이트 실행

일괄 실행 방법은 framedash run-profile-test입니다: FRAMEDASH_* 세션 변수를 내보내고 프로파일링 빌드를 실행한 뒤, 텔레메트리가 수집될 때까지 대기하고 빌드 간 회귀 발생 시 잡을 실패시킵니다.

framedash run-profile-test \
  --command "./Build/Game.exe -nullrhi -ExecCmds='Automation RunTest Perf'" \
  --scenario nightly --api-key-file ci-read.key \
  --baseline "$BASE_SHA" --threshold 5 --fail-on-regression

또는 단계를 수동으로 실행합니다: 비교 가능한 빌드 ID를 목록에서 확인한 뒤, 후보 빌드가 임계값을 초과해 악화되면 파이프라인을 실패시킵니다:

framedash builds --days 30

framedash perf-diff --baseline "$BASE_SHA" --candidate "$GITHUB_SHA" \
  --threshold 5 --fail-on-regression

perf-diff는 프레임 타임, 메모리, GPU 시간, 맵 로드 시간(load_time_ms), 디스크 I/O(io.read_bytes / io.read_time_ms / io.read_ops), GPU VRAM(mem.vram)을 lower-is-better 지표로 비교합니다. 맵 로드와 io.* 샘플에는 Unity 0.1.3 / UE5 0.1.6 / Godot 0.1.4 이상의 SDK가 필요하며, mem.vram에는 UE5 SDK 0.1.7 이상(옵트인, 비헤드리스), Unity SDK 0.1.4 이상, 또는 Godot SDK 0.1.5 이상이 필요합니다. mem.vram 데이터가 없는 빌드는 해당 지표에서 비교 불가로 처리됩니다. 이는 호스팅되는 이전 빌드 알림이 아니라 CI가 실행하고 합격/불합격을 관리하는 명령 게이트입니다.

대시보드에서는 정적 임계값도 설정할 수 있습니다:

FPS가 허용 하한보다 낮음
프레임 타임이 33ms 초과
메모리 사용량이 예산을 초과

활용 사례

풀 리퀘스트 퍼포먼스 체크: PR 빌드에 텔레메트리를 연결하고 병합 전에 확인
나이틀리 빌드 모니터링: build ID별 일일 퍼포먼스 스냅샷 유지
릴리스 전 품질 게이트: framedash perf-diff 또는 CI 소유 정적 임계값으로 판정

다음 단계

CLI 레퍼런스: CI 파이프라인에서의 CLI 활용
히트맵: 퍼포먼스의 시각화

AI 에이전트용: llms.txt