내 PC에서 Unity 성능 실행 비교하기 (파일럿)

직접 관리하는 PC에서 재현 가능한 시나리오를 측정하고 Framedash에서 집계 결과를 비교하는 선택적 파일럿입니다. 먼저 수동으로 결과를 확인하세요. CI와 자동 판정은 별도 단계이며, 이 비공간 비교에는 맵 등록이 필요하지 않습니다.

전제 조건

Unity 2022.3 이상과 Framedash Unity SDK 0.1.8, Node.js 20 이상과 CLI 0.1.11. Unity 0.1.7 / CLI 0.1.10 이전 버전에는 이 기능이 없습니다.
Framedash 프로젝트, 플레이어 전송용 events:write 키, 비교용 별도 analytics:read 키. 환경 변수나 비공개 파일로 관리하고 커밋하지 마세요.
COPPA가 활성화되지 않은 조직. 보호 처리가 필수 속성을 제거하므로 API는 403을 반환합니다. 필요한 개인정보 보호 설정을 유지하세요. 로컬 완료나 HTTP 응답은 사용 자격의 증거가 아닙니다.

Unity Package Manager에서 태그가 고정된 Git URL을 사용하고 CLI를 설치하세요.

https://github.com/crane-valley/framedash-unity-sdk.git#v0.1.8

npm install --global @framedash/cli@0.1.11

1. 조건 유지

동일한 기준 빌드를 두 번 실행한 뒤 후보를 실행하세요. 재시도를 포함해 매 실행마다 새로운 소문자 UUID v4를 사용합니다. 시나리오, 하드웨어 구성, 그래픽, 해상도, 설정, 엔진/OS, SDK 버전, 워밍업과 프레임 수를 동일하게 유지하세요. 변경 없는 반복은 빌드 ID와 커밋도 기준과 같아야 합니다. 드라이버, 전원/온도 정책, VSync/FPS 제한을 기록하세요. 같은 라벨이 실제로 같은 환경을 보장하지는 않습니다.

2. 시나리오 측정

설정 후 플레이어의 메인 스레드에서 호출하고 실제 빌드/커밋과 설정으로 바꾸세요. 라벨에는 구성 이름을 사용하며 일련번호나 개인정보를 넣지 마세요. 공백만 있는 값, 128 UTF-16 코드 단위를 넘는 값, ASCII 제어 문자는 허용되지 않습니다. 실행 ID를 저장하고 started가 false이면 진행하지 마세요.

var sdk = Framedash.TelemetrySDK.Initialize(
    apiKey: System.Environment.GetEnvironmentVariable("FRAMEDASH_API_KEY"),
    buildId: "build-a");
var options = new Framedash.PerformanceRunOptions
{
    RunId = System.Guid.NewGuid().ToString("D"),
    Scenario = "route-a",
    Hardware = "lab-pc-a",
    Graphics = "high-vsync-off",
    Resolution = "1920x1080",
    Configuration = "release-dx12-driver-profile-a",
    Commit = "commit-sha",
    Branch = "main",
    WarmupFrames = 120,
    TargetFrames = 3600,
};
bool started = sdk.BeginPerformanceRun(options);
UnityEngine.Debug.Log("Performance run: " + options.RunId + ", started=" + started);

Unity 플레이어 루프를 실행하면서 시나리오를 수행합니다. 예제는 워밍업 120개 간격을 제외한 뒤 3,600개 간격을 수집합니다. 고정 시간은 보장하지 않습니다. 측정 구간을 채울 수 있는 시나리오를 선택하고 프로세스 시간 제한도 별도로 설정하세요. 완료 후 메인 스레드에서 호출합니다.

bool complete = sdk.EndPerformanceRun();
bool acknowledged = sdk.FlushBlocking(5000);
UnityEngine.Debug.Log("complete=" + complete + ", acknowledged=" + acknowledged);

두 반환값을 확인한 뒤 서버 결과도 확인하세요. complete는 로컬 증거이며 마커 추가 실패, 버퍼 초과, 누락, 조기 종료는 성공할 수 없습니다. acknowledged는 HTTP 응답 확인으로 영구 저장 증명이 아닙니다. 중단은 EndPerformanceRun(completed: false)를 사용합니다. 활성 측정 중 충돌이나 SDK 종료는 미완료입니다. run-profile-test만으로는 측정이 시작되지 않습니다.

3. 비교 읽기

로그의 프로젝트 ID와 세 실행 ID를 설정하세요. 최근 7일만 읽습니다. 반복 실행이 없으면 --repeat를 생략할 수 있지만 측정 안정성을 입증한 것으로 해석하지 마세요.

framedash run-diff --project-id "$FRAMEDASH_PROJECT_ID" \
  --api-key-file analytics-read.key \
  --baseline "$BASELINE_RUN_ID" --candidate "$CANDIDATE_RUN_ID" \
  --repeat "$REPEAT_RUN_ID" --format json

증거 해석

JSON에는 조건, 타임스탬프, 수집/누락/워밍업 수, 시간, P50/P95/P99 구간, 1,000/60·1,000/30·50·100ms를 엄격히 초과한 횟수와 1,000프레임당 비율이 포함됩니다. table/csv는 분위수 요약입니다.

SDK Update 콜백 사이의 경과 시간을 측정하며 GPU 시간이나 화면 표시 간격이 아닙니다. 첫 콜백은 제외됩니다. 분위수는 상한을 제외하는 히스토그램 구간이며 차이는 후보에서 기준을 보수적으로 뺀 범위입니다. 양수는 더 긴 프레임 간격을 뜻합니다. 이 범위와 변경 없는 반복 차이는 통계적 신뢰 구간이 아닙니다. 반복 한 번과 최소 1,000프레임은 노이즈나 통계적 신뢰성을 확정하지 않습니다.

종료 코드	의미
`0`	비교 가능한 증거. 후보가 느려져도 0이며 회귀 판정이 아닙니다.
`2`	판단 불가. 누락/미완료 또는 조건 불일치를 확인하세요.
`1`	명령/API 오류. 잘못된 응답도 포함됩니다.

문제 해결

기록 없음: 전송 키, 프로젝트, 실행 ID, 7일 범위를 확인하고 제한된 횟수로 수집 완료를 기다리세요. flush 성공만으로는 충분하지 않습니다.
미완료: 종료 결과, 프레임 수, 누락을 확인하세요. 무효/0 이하/32,768ms 이상 간격은 누락으로 측정 예산을 소비합니다. 워밍업은 0..60,000, 목표는 1,000..1,000,000입니다. 새 ID로 전체 시나리오를 다시 실행하세요.
조건 불일치: 실제 환경과 라벨을 맞추세요. 다른 장비나 빌드를 같은 이름으로 바꿔 통과시키지 마세요. 반복은 기준 빌드/커밋이어야 합니다.
충돌/기록 과다: ID를 재사용하지 마세요. 중복 처리 전 실행당 원시 기록 16개로 제한합니다.
403: 프로젝트 접근, analytics:read, 계정 사용 조건, COPPA 적격성을 확인하세요. 개인정보 보호 설정을 약화하지 마세요.

팀원과 결과를 검토하고 다음 조사와 설정 시간을 기록한 뒤 수정 후 재측정하세요. 근본 원인이나 출시 안전성을 보장하지 않습니다. 기존 CI 성능 게이트는 유지됩니다. API 개요와 Unity SDK 설정도 참고하세요.

AI 에이전트용: llms.txt

서비스 상태