macOS-Trace: 자율적 애플리케이션 성능 최적화

macOS-Trace는 macOS 네이티브 애플리케이션(SwiftUI, AppKit, Metal, CoreAudio, WebKit 및 네이티브 바이너리)을 위한 폐루프 성능 최적화 엔진입니다.

목표는 수동 Instruments GUI 상호작용을 없애는 것입니다. AI 에이전트는 자율적으로 병목 현상을 진단, 위치 파악, 코드 변경을 구현하고, 차등 벤치마킹으로 재테스트하며, 실증 데이터로 성능 목표가 검증될 때까지 반복할 수 있습니다.

+-------------------------------------------------------------------------+
|                  자율 최적화 루프                                      |
|                                                                         |
|  1. 목표 정렬 ──> 2. 진단 트레이스 ──> 3. 표적 코드 수정               |
|         ^                                                 │             |
|         │                                                 ▼             |
|         └────── 목표 미달 시 반복 <── 4. 재테스트 검증                  |
+-------------------------------------------------------------------------+

1단계: 사용자 목표 정렬 (사전 설문)

코드를 수정하거나 트레이스를 수집하기 전에, 에이전트는 최적화 목표 및 성공 기준을 사용자와 일치시켜야 합니다.

모달 도구 vs 채팅 상호작용

에이전트 플랫폼이 대화형 설문지/모달 도구를 제공하는 경우(예: ask_question, 입력 대화상자, 선택 가능한 옵션 목록), 이를 호출하여 이러한 선택 사항을 사용자에게 깔끔하게 제시합니다.
모달 도구를 사용할 수 없는 경우, 구조화된 옵션과 구체적인 권장 값과 함께 대화에서 사용자에게 직접 질문합니다.

사용자에게 질문할 사항

기본 최적화 목표:
- 옵션 A: CPU 사용률, 전력 소비 및 열 쓰로틀링 감소.
- 옵션 B: 메모리 사용량, 일시적 할당 스파이크 감소 또는 누수 제거.
- 옵션 C: UI 프레임 끊김 및 드롭된 애니메이션 프레임(Hitches) 제거.
- 옵션 D: 애플리케이션 콜드 실행 시간 단축.
구체적인 성능 목표(권장 기본값 제공):
- CPU/에너지 목표:
  - 유휴 기준 목표: 명령어 < 20 M/s, CPU 영향 < 0.5.
  - 활성 워크로드 목표: 명령어 < 100 M/s (또는 지정: 30% - 50% 감소).
- 메모리 목표:
  - 최대 상주 RAM: 150 MB (유틸리티/오디오) 또는 300 MB (미디어/풍부한 UI) 미만.
  - 할당 이벤트 속도: 정상 상태 실행 중 < 500 events/sec.
  - 메모리 누수: 정확히 0개의 지속적인 누수.
- UI 부드러움 목표:
  - 히치 비율: < 5.0 ms/s (허용 가능), < 1.0 ms/s (부드러움/드롭 프레임 없음).
- 실행 시간 목표:
  - 첫 프레임까지의 시간: < 400 ms (우수), < 800 ms (허용 가능).
벤치마크 사용자 시나리오:
- 사용자에게 벤치마크할 특정 화면, 사용자 상호작용 또는 워크로드를 질문합니다.

목표가 확인되면 2단계로 진행합니다.

범위 및 사전 요구 사항

대상 플랫폼: macOS 네이티브 데스크탑 애플리케이션만 해당(SwiftUI, AppKit, Metal, CoreAudio / AVAudioEngine, WebKit 호스트 뷰, 네이티브 CLI 실행 파일). iOS 시뮬레이터, 원격 모바일 장치 또는 외부 브라우저 전용 웹 앱은 지원하지 않습니다.
Xcode 도구: macOS 12+ 및 전체 Xcode 또는 Xcode 명령줄 도구 필요(xcode-select -p, xcrun xctrace version).
Python: Python 3.8+ (macOS에 사전 설치됨; 외부 pip 종속성 없음).
프로세스 권한: Hardened Runtime에서 --attach <PID>를 위해 디버그 빌드 또는 get-task-allow 권한이 있는 바이너리가 필요합니다.

에이전트 규칙

자동화된 프로파일링 중에는 다음의 불가침 규칙을 따르십시오:

먼저 기준을 설정하십시오: 활성 워크로드만 기록하지 마십시오. 활성 상태를 기록하기 전에 항상 유휴 기준(앱이 포그라운드에서 열려 있고 워크로드가 일시 중지된 상태)을 캡처하십시오. 계산: 델타 = 활성 - 기준.
기록 전 대상 상태를 확인하십시오: pgrep -x <ProcessName>을 사용하여 프로세스가 존재하는지, 기록 창 동안 대상 기능이 활발히 실행 중인지 확인하십시오.
창을 포그라운드에 유지하십시오: macOS는 가려지거나 최소화된 창(NSWindowOcclusionState)에 대한 렌더링 및 디스플레이 링크를 제한합니다. 가려진 창은 거짓으로 낮은 GPU 및 CPU 판독값을 생성합니다.
동일한 테스트 매개변수를 사용하십시오: 동일한 샘플 기간(기본값: 60s), 동일한 디스플레이 스케일, 동일한 창 크기 및 동일한 테스트 입력 데이터로 실행을 비교하십시오. 디버그 빌드를 릴리스 빌드와 절대 비교하지 마십시오.
타사 Python 종속성 없음: 번들된 모든 스크립트(scripts/compare_elements.py, scripts/parse_power.py, scripts/top_categories.py)는 Python 3 표준 라이브러리만 사용합니다. pip 패키지를 설치하지 마십시오.
출력을 /tmp/macos-traces/에 저장하십시오: 모든 .trace 번들 및 .xml 내보내기를 타임스탬프 및 시나리오 태그가 지정된 파일 이름으로 /tmp/macos-traces/에 저장하십시오.
대화 컨텍스트 예산을 보호하십시오: 트레이스 파일 및 원시 내보낸 XML 문서는 수십 또는 수백 메가바이트가 될 수 있습니다. 원시 .trace 출력, 전체 호출 트리 또는 구문 분석되지 않은 할당 XML을 에이전트 대화 컨텍스트에 덤프하지 마십시오. 항상 번들된 Python 스크립트를 사용하여 데이터를 스트리밍, 필터링, 순위 지정 및 요약한 후 읽으십시오.
기본 병목 현상에 집중하십시오: 수십 개의 무고한 유틸리티 함수에 마이크로 최적화를 분산시키지 마십시오. 먼저 프로파일링하여 주요 기여자(예: 중복 표면 인스턴스, 고주파 타이머 재평가, 버퍼링되지 않은 I/O)를 확인하고 최적화 노력을 해당 근본 원인에만 집중하십시오.
UI, 시각 효과 또는 핵심 동작을 조용히 변경하지 마십시오: 성능 병목 현상이 시각적 충실도(예: 블러/유리 재질, 프레임 애니메이션, 그림자, 레이아웃 전환) 또는 필수 소프트웨어 동작과 관련된 경우:
- 시각적 기능을 일방적으로 제거하거나 다운그레이드하지 마십시오.
- 먼저 사용자에게 공식적으로 허가를 요청하십시오(대화형 프롬프트 또는 명시적 채팅 메시지 사용).
- 절충점을 명확히 설명하십시오: 변경 전후의 시각적 변화를 설명하고, 기능이 리소스를 소비하는 이유를 설명하며, 구체적인 예상 성능 이점을 제시하십시오(예: "동적 배경 블러를 비활성화하면 활성 GPU 영향을 1.5에서 0.2로 줄이고 약 50 M/s CPU 명령어를 절약할 수 있습니다").
기록 아티팩트를 정리하십시오: 모든 xctrace 기록은 수 GB의 임시 커널 트레이스(instruments*.ktrace)와 Instruments CLI 캐시(C/com.apple.dt.InstrumentsCLI)를 사용자별 시스템 임시 폴더($TMPDIR)에 씁니다. scripts/run_trace.sh는 종료 시(성공 및 실패 모두) 이들을 자동으로 제거합니다. xctrace를 직접 실행하는 경우, 결론을 내리기 전에 직접 정리하십시오:
```
find "${TMPDIR:-/tmp}" -maxdepth 1 -type f -name 'instruments*.ktrace' -delete 2>/dev/null || true
```
수백 GB의 임시 기록 데이터를 남겨두고 세션을 절대 종료하지 마십시오.

4단계 최적화 프로토콜

2단계: 진단 프로파일링 및 귀인

코드를 작성하기 전에 현재 상태를 측정하고 근본 원인을 분리하십시오:

# 1. 사전 확인: 앱이 실행 중이어야 하며 창이 보여야 함
APP_NAME="YourApp"
pgrep -x "$APP_NAME" || { echo "[ERROR] $APP_NAME이(가) 실행 중이 아닙니다. 먼저 실행하십시오."; exit 1; }

# SKILL_DIR = 이 스킬의 설치 디렉토리 (다른 곳에 설치된 경우 조정)
SKILL_DIR="$HOME/.claude/skills/macos-trace"

# 2. 60초 유휴 기준 기록 (워크로드 일시 중지, 창 보임)
# run_trace.sh는 프로세스 이름을 PID로 직접 확인합니다.
"$SKILL_DIR/scripts/run_trace.sh" --process "$APP_NAME" --template power --duration 60s --label "01-baseline"

# 3. 앱에서 워크로드 트리거, 활성 상태 기록
"$SKILL_DIR/scripts/run_trace.sh" --process "$APP_NAME" --template power --duration 60s --label "02-pre-opt"

# 4. 최적화 전 델타 계산
python3 "$SKILL_DIR/scripts/compare_elements.py" \
  /tmp/macos-traces/01-baseline-power.xml:"유휴 기준" \
  /tmp/macos-traces/02-pre-opt-power.xml:"활성 최적화 전"

특수 템플릿을 사용하여 병목 현상을 귀인하십시오:

--template time을 실행하여 핫 호출 트리 함수를 분리합니다.
--template alloc을 scripts/top_categories.py와 함께 실행하여 쓰레싱 할당을 식별합니다.
스크롤링 중 --template hitches를 실행하여 렌더링 대 커밋 지연을 분리합니다.

3단계: 표적 코드 수정

발견 사항에 따라 최소한의 수술적 수정을 적용하십시오:

실시간 오디오 스레드가 힙 메모리를 할당합니까? 사전 할당된 잠금 없는 링 버퍼로 교체합니다.
WebKit IPC가 포화되었습니까? 상태 업데이트를 제한하고 CSS 변환 애니메이션으로 전환합니다.
Metal 프래그먼트 셰이더가 Retina에서 오버드로잉됩니까? 동적 해상도 스케일링을 추가하거나 오프스크린 렌더 루프를 일시 중지합니다.
고해상도 이미지 디코딩 스파이크가 발생합니까? CGImageSourceCreateThumbnailAtIndex 다운샘플링을 채택합니다.

애플리케이션을 다시 빌드합니다.

4단계: 재테스트, 정량적 검토 및 결정 게이트

동일한 조건에서 프로필을 다시 실행하고 델타를 평가하십시오:

# 1. 최적화 후 활성 워크로드 기록
"$SKILL_DIR/scripts/run_trace.sh" --process "$APP_NAME" --template power --duration 60s --label "03-post-opt"

# 2. 기준과 최적화 전/후 비교
python3 "$SKILL_DIR/scripts/compare_elements.py" \
  /tmp/macos-traces/01-baseline-power.xml:"유휴 기준" \
  /tmp/macos-traces/02-pre-opt-power.xml:"활성 최적화 전" \
  /tmp/macos-traces/03-post-opt-power.xml:"활성 최적화 후"

예시 결정 출력:

시나리오                   초  CPU 평균  CPU 최대  디스플레이  GPU 평균  총 명령어    명령어 M/s
============================================================================================
유휴 기준                60     0.15     0.80     0.05     0.00        1.02G         17.0
활성 최적화 전           60     2.40     4.80     1.10     1.50       16.20G        270.0
활성 최적화 후           60     0.65     1.20     0.25     0.10        4.80G         80.0
--------------------------------------------------------------------------------------------
기준 대비 차등 [유휴 기준]:
  활성 최적화 전              +253.0 M/s 명령어, CPU 평균 델타 +2.25
  활성 최적화 후              +63.0 M/s 명령어, CPU 평균 델타 +0.50

결정 게이트:

목표 달성 시(예: 명령어 속도가 270 M/s에서 80 M/s로 떨어져 < 100 M/s 목표 충족): 최적화 전후 실증 보고서를 사용자에게 제시하고 종료합니다.
목표 미달 시: 나머지 병목 현상을 분리하고 다음 반복 주기를 시작합니다.

보고 후 정리: 사용자가 최종 최적화 보고서를 수락한 후 /tmp/macos-traces/에 누적된 .trace 번들을 삭제합니다(각각 수십 GB가 될 수 있음). 단, 사용자가 명시적으로 보관을 요청한 경우는 제외합니다. 보고서에 표시된 최종 비교 테이블 및 .xml 내보내기로 충분한 증거가 됩니다.

직접 CLI 참조

# 실행 중인 프로세스에 연결
xcrun xctrace record \
  --template 'Power Profiler' \
  --time-limit 60s \
  --output /tmp/macos-traces/power.trace \
  --attach $PID

# 전력 영향 테이블 내보내기 (명령어, CPU, GPU, 디스플레이)
xcrun xctrace export \
  --input /tmp/macos-traces/power.trace \
  --xpath "/trace-toc/run[@number='1']/data/table[@schema='ProcessSubsystemPowerImpact']" \
  > /tmp/macos-traces/power.xml

# 할당 요약 테이블 내보내기
xcrun xctrace export \
  --input /tmp/macos-traces/alloc.trace \
  --xpath "/trace-toc/run[@number='1']/data/table[@schema='all-allocations-summary']" \
  > /tmp/macos-traces/alloc.xml

템플릿 참조

scripts/run_trace.sh 및 headless xctrace에서 지원하는 Instruments 템플릿:

컴퓨팅 및 에너지

템플릿	짧은 이름	대상 메트릭 및 내보내기 스키마	사용 사례
`Power Profiler`	`power`	초당 명령어(M/s), CPU/GPU/디스플레이 에너지 영향 (`ProcessSubsystemPowerImpact`).	목표 A/B 벤치마킹 및 전력 효율성 테스트.
`Time Profiler`	`time`	스레드별 CPU 샘플 가중치, 호출 트리 핫스팟, 메인 스레드 차단 메서드.	높은 CPU 사용률, 실행 중인 스레드 및 핫 함수 경로.
`CPU Counters`	`counters`	IPC (사이클당 명령어), L1/L2 캐시 미스, 분기 예측 실패.	저수준 컴퓨팅 및 DSP 알고리즘 성능 병목 현상.

UI 응답성 및 부드러움

템플릿	짧은 이름	대상 메트릭 및 내보내기 스키마	사용 사례
`Animation Hitches`	`hitches`	히치 지속 시간(ms), 히치 비율(ms/s), 프레임 드롭, 앱 대 렌더 단계 지연 시간.	스크롤링 끊김, 드롭된 애니메이션 프레임 및 CoreAnimation 커밋 지연.
`SwiftUI`	`swiftui`	View 본문 평가, State 무효화 횟수, 뷰 업데이트 빈도.	불필요한 뷰 재평가 및 상태 무효화 계단식 현상.
`Metal System Trace`	`metal`	GPU 인코더 시간, 정점/프래그먼트 셰이더 지속 시간, 프레임 경계 지연 시간.	셰이더 실행 병목 현상, 입자 FX 오버헤드 및 렌더 파이프라인 중단.

메모리 및 할당

템플릿	짧은 이름	대상 메트릭 및 내보내기 스키마	사용 사례
`Allocations`	`alloc`	힙 할당, 일시적 vs 영구 메모리, 카테고리 이벤트 속도 (`all-allocations-summary`).	고빈도 임시 할당, 메모리 스파이크 및 버퍼 쓰레싱.
`Leaks`	`leaks`	상위 수명 주기보다 오래 지속되는 보유 메모리 누수, 참조 사이클.	폐기된 메모리, 클로저 캡처 누수 및 해제되지 않은 델리게이트 사이클.

시작 및 동시성

템플릿	짧은 이름	대상 메트릭 및 내보내기 스키마	사용 사례
`App Launch`	`launch`	첫 프레임까지의 시간, `dyld` 로딩 시간, 정적 초기화자, runloop 설정.	콜드 스타트 최적화 (`--launch -- <binary_path>`).
`Swift Concurrency`	`concurrency`	Swift 작업(생성/실행/일시 중단), 액터 재진입, 협력 풀 사용량.	`async/await` 기아, 액터 경합 및 장기-일시 중단 작업.
`System Trace`	`sys`	스레드 상태 전환(실행 중, 대기, 차단), 스케줄러 지연 시간, 시스템 호출 오버헤드.	스레드 경합, 불균형 작업 분포 및 높은 시스템 호출 비용.

macOS-Trace: macOS 애플리케이션 자율 성능 최적화