로컬 프로파일링을 위한 디버그 명령어

ProfilingManager 통합을 로컬에서 테스트할 때 비율 제한으로 인해 요청이 제한되거나 트리거를 테스트할 때 백그라운드 trace가 활성화되지 않을 수 있습니다. 이 페이지의 adb 명령어를 사용하여 테스트 기기에서 제한을 사용 중지하고, 프로필을 가져오고, 수정되지 않은 트레이스를 유지하고, 캡처를 트리거하고, 서비스 상태를 검사합니다.

비율 제한기 사용 중지

로컬 테스트 중에 requestProfiling 요청에 대한 앱 프로세스 및 시스템 비율 제한기를 사용 중지하려면 다음 device_config 명령어를 실행합니다.

adb shell device_config put profiling_testing rate_limiter.disabled true

테스트를 완료하면 플래그를 재설정합니다.

adb shell device_config delete profiling_testing rate_limiter.disabled

ADB를 사용하여 프로필 가져오기

루트 액세스 권한이 있는 기기에서 수정된 프로필을 로컬로 검사하려면 getResultFilePath에서 반환한 경로를 사용하여 adb pull를 실행합니다.

# Pull a profile
adb pull /data/user/0/<com.example.myapp>/files/profiling/<profile-file-name>

임시 및 수정되지 않은 결과 보관

로컬에서 프로파일링을 테스트할 때 /data/misc/perfetto-traces/profiling/의 임시 디렉터리에 결과를 보관할 수 있습니다. 수정되지 않은 시스템 트레이스를 수정된 시스템 트레이스와 비교하면 수정 중에 삭제되는 데이터를 파악하는 데 도움이 됩니다.

임시 및 수정되지 않은 결과가 유지되는 방식은 기기에서 실행되는 Android 버전에 따라 다릅니다.

  • Android 16(API 수준 36) 이상: 수정되지 않은 결과(해당하는 경우)와 수정된 결과를 모두 임시 디렉터리에 보관할 수 있습니다. 이 디렉터리는 Android 16에서 루트 액세스 없이 모든 빌드 유형에서 adb pull를 사용하여 액세스할 수 있도록 확장되었습니다(Android 15에서는 /data/misc/perfetto-traces/profiling/를 읽으려면 루트 액세스가 필요함). 시스템에서 임시 결과를 삭제하지 못하도록 하려면 다음 명령어를 실행합니다.

    adb shell device_config put profiling_testing delete_temporary_results.disabled true

  • Android 15(API 수준 35): 임시 디렉터리에는 수정되지 않은 결과만 보관할 수 있으며, 루트 액세스 권한이 있는 빌드에서만 adb를 통해 액세스할 수 있습니다. (앱은 자체 /data/user/0/<app>/files/profiling/ 디렉터리에서 수정된 프로필을 계속 수신하며, 앱 코드는 모든 빌드에서 이를 읽거나 복사할 수 있습니다. 하지만 adb pull를 사용하여 /data/user/0/...에서 직접 가져오려면 루트 액세스 권한이 필요하거나 디버그 가능한 빌드에서 adb shell run-as <app>가 필요합니다.) 시스템에서 수정되지 않은 trace를 삭제하지 못하도록 하려면 다음 명령어를 실행합니다.

    adb shell device_config put profiling_testing delete_unredacted_trace.disabled true

프로필을 캡처한 후 임시 디렉터리에서 유지된 파일을 가져옵니다.

# Pull a retained redacted profile (Android 16 and higher)
adb pull /data/misc/perfetto-traces/profiling/<trace-name>.<profile-type-ext>

# Pull an unredacted system trace
adb pull /data/misc/perfetto-traces/profiling/<trace-name>.perfetto-trace-unredacted

이러한 명령어에서 <trace-name>는 ProfilingResult.getResultFilePath에서 반환된 경로의 기본 파일 이름(확장자 제외)이며, 수정되지 않은 시스템 트레이스 사본은 .perfetto-trace 확장자에 -unredacted를 추가합니다. 파일 이름 구조 및 <profile-type-ext> 값에 대한 자세한 내용은 파일 위치 및 이름 지정 형식을 참조하세요.

adb shell device_config delete profiling_testing delete_temporary_results.disabled
adb shell device_config delete profiling_testing delete_unredacted_trace.disabled

트리거 테스트를 위해 백그라운드 trace 강제 사용 설정

시스템 백그라운드 트레이스는 프로덕션에서 무작위 간격으로 실행되므로 로컬에서 트리거 기반 프로파일링을 테스트하기가 어려울 수 있습니다. 시스템이 연속 백그라운드 트레이스를 실행하고 앱 트리거의 시스템 수준 비율 제한기를 우회하도록 하려면 system_triggered_profiling.testing_package_name를 설정합니다.

adb shell device_config put profiling_testing system_triggered_profiling.testing_package_name <com.example.myapp>

setRateLimitingPeriodHours로 구성된 트리거별 대기 시간은 계속 적용됩니다. 이 모드는 삭제할 때까지 계속 실행되므로 테스트가 완료되면 플래그를 삭제합니다.

adb shell device_config delete profiling_testing system_triggered_profiling.testing_package_name

유용한 디버깅 명령어

최신 Profiling 모듈 버전이 설치된 Android 16(API 수준 36) 이상에서는 adb를 통해 cmd profiling_service 도구를 사용하여 상세 로깅을 사용 설정하고, 주문형 프로필 수집을 트리거하고, 명령줄에서 직접 트리거를 테스트할 수 있습니다.

상세 디버그 로깅 사용 설정

logcat에서 자세한 ProfilingService 로그를 사용 설정하고 요청 처리 및 전송을 진단하려면 다음 명령어를 실행합니다.

adb shell cmd profiling_service enable-logs true

주문형 프로필 수집 요청

명령줄에서 특정 패키지의 프로필 캡처를 즉시 시작하려면 다음 명령어를 실행합니다.

adb shell cmd profiling_service request-profiling <profiling_type> <com.example.myapp> [--user <user_id>] [--duration <duration_ms>] [--sources <sources>]

이 명령어에서 <profiling_type>는 ProfilingManager의 정수 상수 값입니다(Java 힙 덤프의 경우 1, 힙 프로필의 경우 2, 스택 샘플링의 경우 3, 시스템 트레이스의 경우 4). 메모리 및 스택 프로필의 경우 대상 앱 프로세스가 실행 중이어야 하고, 요청은 사용 중지되지 않는 한 비율 제한기의 적용을 받으며, 완료된 ProfilingResult는 registerForAllProfilingResults에 등록된 전역 리스너에만 전달됩니다.

트리거 등록 및 시뮬레이션

패키지의 트리거를 등록하거나 시뮬레이션된 트리거 이벤트를 실행하고 트리거 콜백 처리를 확인하려면 다음 명령어를 실행합니다.

adb shell cmd profiling_service add-trigger <trigger_type> <com.example.myapp> [--user <user_id>]
adb shell cmd profiling_service trigger <trigger_type> <com.example.myapp> [--user <user_id>]

이 명령어에서 <trigger_type>는 ProfilingTrigger의 정수 상수 값입니다(예: TRIGGER_TYPE_APP_FULLY_DRAWN의 경우 1, TRIGGER_TYPE_ANR의 경우 2, TRIGGER_TYPE_OOM의 경우 7). add-trigger를 실행하면 0시간의 대기 시간으로 트리거가 등록되어 해당 트리거 유형의 기존 등록이 재정의됩니다. 백그라운드 트레이스의 스냅샷을 저장하는 트리거(예: 1 또는 2)를 시뮬레이션하려면 활성 백그라운드 트레이스가 필요합니다(트리거 테스트를 위해 백그라운드 트레이스 강제 사용 설정 참고).

전반적인 ProfilingManager 상태 수집

최신 Profiling 모듈 버전이 설치된 Android 16(API 수준 36) 이상에서는 profiling_service에 대해 dumpsys를 실행하여 문제를 진단하고 ProfilingManager의 현재 상태를 검사할 수 있습니다.

adb shell dumpsys profiling_service

dumpsys profiling_service 출력은 정보 및 디버깅 목적으로만 사용되며 형식은 변경될 수 있습니다. 다음을 포함하여 서비스의 내부 상태에 대한 스냅샷을 제공합니다.

  • 활성 제한 및 비율 제한기 상태입니다.
  • 활성 기기 설정
  • 등록된 앱 트리거 및 비율 제한 쿨다운
  • 활성 및 큐에 추가된 프로파일링 세션입니다.
  • 최근 프로파일링 요청, 트리거 발생, 결과 전송 이벤트입니다.