이 페이지는 Cloud Translation API를 통해 번역되었습니다.

adb 명령어로 트레이스 캡처

Winscope 트레이스는 디버그 빌드(userdebug 및 eng 빌드)에서 adb 명령줄을 사용하여 수집할 수 있습니다. adb로 Winscope 트레이스를 수집하기 전에 adb root를 실행합니다.

Android 15부터 Winscope 트레이스가 Perfetto에 통합되고 Perfetto 명령줄을 사용하여 수집됩니다. 각 Winscope 트레이스는 자체 구성이 있는 Perfetto 데이터 소스입니다. 구성은 개별적으로 또는 단일 트레이스 세션에서 사용 설정할 수 있습니다.

Android 14 이하에서는 각 Winscope 트레이스에 다른 명령어가 있으며 각각을 독립적으로 수집할 수 있습니다. 자세한 내용은 Android 14 이하에서 트레이스 캡처를 참고하세요.

WindowManager

이 트레이스 유형에는 데이터 소스 이름 android.windowmanager를 사용합니다.

구성 옵션

로그 수준 (log_level): 로그 상세 수준을 지정합니다. 지원되는 값:
- LOG_LEVEL_VERBOSE: 최대한 많은 정보가 포함된 모든 요소를 로깅합니다.
- LOG_LEVEL_DEBUG: 모든 요소를 로깅하지만 모든 구성 데이터를 쓰지는 않습니다.
- LOG_LEVEL_CRITICAL: 최소한의 성능 오버헤드로 표시되는 요소만 로깅합니다.
로그 빈도 (log_frequency): 항목이 로깅되는 빈도를 정의합니다.
- LOG_FREQUENCY_FRAME: 프레임이 커밋될 때 상태 스냅샷을 추적합니다.
- LOG_FREQUENCY_TRANSACTION: 트랜잭션이 커밋될 때마다 상태 스냅샷을 추적합니다.
- LOG_FREQUENCY_SINGLE_DUMP: 데이터 소스가 시작될 때 단일 상태 스냅샷을 추적합니다.

구성 값에 관한 자세한 내용은 WindowManager를 참고하세요.

예

다음은 adb의 WindowManager 트레이스 유형의 예입니다.

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "android.windowmanager"
           windowmanager_config: {
              log_level: LOG_LEVEL_VERBOSE
              log_frequency: LOG_FREQUENCY_TRANSACTION
           }
       }
   }
EOF

ProtoLog

이 트레이스 유형에는 데이터 소스 이름 android.protolog를 사용합니다.

구성 옵션

트레이싱 모드 (tracing_mode): 사용할 로그 구성을 결정합니다.

DEFAULT: group_overrides에 지정된 로그 그룹과 수준만 추적합니다.
ENABLE_ALL: group_overrides에 지정되지 않는 한 모든 로그 그룹과 수준을 추적합니다.

최소 로그 수준 (default_log_from_level): 설정하면 그룹 재정의가 지정되지 않는 한 이 수준보다 높거나 이 수준인 로그 수준의 메시지가 추적됩니다. 예를 들어 모든 로그를 사용 설정하지 않고도 모든 경고 및 오류가 로깅되도록 사용합니다. 지원되는 값은 다음과 같습니다.

PROTOLOG_LEVEL_DEBUG
PROTOLOG_LEVEL_VERBOSE
PROTOLOG_LEVEL_INFO
PROTOLOG_LEVEL_WARN
PROTOLOG_LEVEL_ERROR
PROTOLOG_LEVEL_WTF

그룹 재정의 (group_overrides): 각 ProtoLog 그룹의 로그 수준을 수동으로 구성할 수 있습니다. 각 그룹에는 다음이 포함됩니다.

name: Android 소스 코드에서 사용되는 ProtoLog 그룹 이름입니다.
log_from: default_log_from_level와 동일하지만 현재 그룹에 대해서만 지정됩니다.
collect_stacktrace: true로 설정하면 추적 중인 그룹의 각 ProtoLog 메시지에 관한 스택 트레이스를 수집합니다.

경고: 스택 트레이스 로깅은 느리고 기기 성능에 영향을 미칩니다. 이 기능은 로컬 개발에 더 적합합니다.

예

다음은 adb의 ProtoLog 추적 유형의 예입니다.

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "android.protolog"
           protolog_config: {
              tracing_mode: DEFAULT
              default_log_from_level: PROTOLOG_LEVEL_WARN
              group_overrides: {
                 group_name: "WM_SHELL_STARTING_WINDOW"
                 log_from: PROTOLOG_LEVEL_DEBUG
                 collect_stacktrace: true
              }
           }
       }
   }
EOF

입력

이 트레이스 유형에는 데이터 소스 이름 android.input.inputevent를 사용합니다.

구성 옵션

트레이스 모드 (trace_mode): 입력 트레이스를 개인 정보 보호 규칙을 사용하여 시작해야 하는지 또는 모든 입력 이벤트를 기록해야 하는지 결정합니다.

TRACE_MODE_TRACE_ALL: 처리된 컨텍스트와 관계없이 시스템에서 처리한 모든 입력 이벤트를 기록합니다.
TRACE_MODE_USE_RULES: 이 구성에 정의된 추적 규칙을 사용하여 추적할 이벤트를 지정합니다. 트레이스 규칙 지정에 관한 자세한 내용은 android_input_event_config.proto를 참고하세요.

예

다음은 adb의 입력 트레이스 유형의 예입니다.

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "android.input.inputevent"
           android_input_event_config: {
              mode: TRACE_MODE_TRACE_ALL
           }
       }
   }
EOF

SurfaceFlinger (레이어)

이 트레이스 유형에는 데이터 소스 이름 android.surfaceflinger.layers를 사용합니다.

구성 옵션

추적 모드 (mode): 항목이 로깅되는 빈도를 정의합니다.

MODE_ACTIVE: 레이어 스냅샷을 추적합니다. 레이어가 변경될 때마다 스냅샷이 찍힙니다.
MODE_GENERATED: SurfaceFlinger의 내부 링 버퍼에 보관된 트랜잭션에서 레이어 스냅샷을 생성합니다. 레이어의 스냅샷 생성은 이 데이터 소스가 플러시될 때 발생합니다.
MODE_DUMP: 단일 레이어 스냅샷을 추적합니다.
MODE_GENERATED_BUGREPORT_ONLY: MODE_GENERATED와 동일하지만 트레이스가 플러시될 때마다가 아니라 버그 신고가 접수될 때만 레이어 스냅샷 생성을 트리거합니다.

트레이스 플래그 (trace_flags):

TRACE_FLAG_INPUT: 노출 영역에 입력 데이터가 포함된 경우 입력 창의 세부정보를 추적합니다.
TRACE_FLAG_COMPOSITION: 컴포지션 유형과 표시 영역을 추적합니다.
TRACE_FLAG_EXTRA: 오프스크린 레이어를 비롯한 추가 노출 영역 메타데이터를 추적합니다.

경고: 이 필드는 매우 상세하며 대용량 메모리가 필요합니다.
TRACE_FLAG_HWC: 추가 비정형 하드웨어 컴포저 메타데이터를 추적합니다.

경고: 이 필드는 매우 상세하며 대용량 메모리가 필요합니다.
TRACE_FLAG_BUFFERS: 노출 영역의 모든 버퍼 변경사항을 추적하도록 SurfaceFlinger를 구성합니다. 기본적으로 SurfaceFlinger는 도형 변경이 발생할 때만 새 상태를 추적합니다.
TRACE_FLAG_VIRTUAL_DISPLAYS: 트레이스에 가상 디스플레이 레이어를 포함합니다.

예

다음은 adb의 SurfaceFlinger 트레이스 유형의 예입니다.

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "android.surfaceflinger.layers"
           surfaceflinger_layers_config: {
              mode: MODE_ACTIVE
              trace_flags: TRACE_FLAG_INPUT
              trace_flags: TRACE_FLAG_COMPOSITION
              trace_flags: TRACE_FLAG_HWC
              trace_flags: TRACE_FLAG_BUFFERS
              trace_flags: TRACE_FLAG_VIRTUAL_DISPLAYS
           }
       }
   }
EOF

다양한 구성 값의 의미에 관한 자세한 내용은 SurfaceFlinger를 참고하세요.

셸 전환

이 트레이스 유형에는 데이터 소스 이름 com.android.wm.shell.transition를 사용합니다.

구성 옵션

이 트레이스 유형에는 구성 옵션이 없습니다.

예

다음은 adb의 셸 전환 트레이스 유형의 예입니다.

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "com.android.wm.shell.transition"
       }
   }
EOF

SurfaceFlinger (거래)

이 트레이스 유형에는 데이터 소스 이름 android.surfaceflinger.transactions를 사용합니다.

구성 옵션

추적 모드 (mode): 항목이 로깅되는 빈도를 정의합니다.

MODE_CONTINUOUS: SurfaceFlinger는 데이터 소스가 플러시될 때마다 트랜잭션의 내부 링 버퍼를 씁니다. 링 버퍼에는 SurfaceFlinger의 초기 상태와 최신 트랜잭션이 포함됩니다.
MODE_ACTIVE: SurfaceFlinger는 초기 상태를 작성한 다음 데이터 소스가 중지될 때까지 들어오는 각 트랜잭션을 작성합니다.

예

다음은 adb의 SurfaceFlinger 트랜잭션 트레이스 유형의 예입니다.

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "android.surfaceflinger.transactions"
           surfaceflinger_transactions_config: {
              mode: MODE_ACTIVE
           }
       }
   }
EOF

IME

이 트레이스 유형에는 데이터 소스 이름 android.inputmethod을 사용합니다.

구성 옵션

이 트레이스 유형에는 구성 옵션이 없습니다.

예

다음은 adb의 IME 추적 유형의 예입니다.

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "android.inputmethod"
       }
   }
EOF

ViewCapture

이 트레이스 유형에는 데이터 소스 이름 android.viewcapture를 사용합니다.

구성 옵션

이 트레이스 유형에는 구성 옵션이 없습니다.

예

다음은 adb의 ViewCapture 추적 유형의 예입니다.

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "android.viewcapture"
       }
   }
EOF

전체 예

Perfetto를 사용하면 단일 구성에서 여러 소스의 데이터를 수집할 수 있습니다. 단일 명령어로 모든 Winscope 트레이스를 수집할 수 있습니다.

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "android.windowmanager"
           windowmanager_config: {
              log_level: LOG_LEVEL_VERBOSE
              log_frequency: LOG_FREQUENCY_TRANSACTION
           }
       }
   }
   data_sources: {
       config {
           name: "android.protolog"
           protolog_config: {
              tracing_mode: ENABLE_ALL
           }
       }
   }
   data_sources: {
       config {
           name: "android.input.inputevent"
           android_input_event_config: {
              mode: TRACE_MODE_TRACE_ALL
           }
       }
   }
   data_sources: {
       config {
           name: "android.surfaceflinger.layers"
           surfaceflinger_layers_config: {
              mode: MODE_ACTIVE
              trace_flags: TRACE_FLAG_INPUT
              trace_flags: TRACE_FLAG_COMPOSITION
              trace_flags: TRACE_FLAG_HWC
              trace_flags: TRACE_FLAG_BUFFERS
              trace_flags: TRACE_FLAG_VIRTUAL_DISPLAYS
           }
       }
   }
   data_sources: {
       config {
           name: "com.android.wm.shell.transition"
       }
   }
   data_sources: {
       config {
           name: "android.surfaceflinger.transactions"
           surfaceflinger_transactions_config: {
              mode: MODE_ACTIVE
           }
       }
   }
   data_sources: {
       config {
           name: "android.inputmethod"
       }
   }
   data_sources: {
       config {
           name: "android.viewcapture"
       }
   }
EOF

Android 14 이하에서 트레이스 캡처

다음 트레이스 각각에 대해 adb shell 명령어를 실행하기 전에 adb root를 실행합니다. 추적이 끝나면 /data/misc/wmtrace에서 추적 파일을 사용할 수 있습니다. 기기에서 파일이나 디렉터리 및 하위 디렉터리를 복사하려면 기기와 파일 간에 복사를 참고하세요.

WindowManager 트레이스

WindowManager 트레이스를 캡처하려면 다음 단계를 따르세요.

트레이스 사용 설정:
```
adb shell wm tracing start
```
트레이스 사용 중지:
```
adb shell wm tracing stop
```
트레이스 캡처를 실행하는 동안 로깅 데이터를 파일에 저장합니다.
```
adb shell wm tracing save-for-bugreport
```
프레임당 한 번 트레이스를 로깅합니다.
```
adb shell wm tracing frame
```
각 거래를 기록합니다.
```
adb shell wm tracing transaction
```
최대 로그 크기를 KB 단위로 설정합니다.
```
adb shell wm tracing size
```
트레이스 상태를 인쇄합니다.
```
adb shell wm tracing status
```
로그 수준을 critical (표시되는 창만 정보가 축소됨), trim (모든 창에서 정보가 축소됨) 또는 all (모든 창 및 정보)로 설정합니다.
```
adb shell wm tracing level
```

WindowManager 덤프

WindowManager 덤프를 캡처하려면 다음 단계를 따르세요.

adb exec-out dumpsys window --proto > window_dump.winscope

ProtoLog

다음 명령어는 ProtoLog 시스템에 사용됩니다.

system_server 프로세스에서 다음을 실행합니다.

ProtoLog 시작:
```
adb shell cmd window logging start
```
ProtoLog를 중지합니다.
```
adb shell cmd window logging stop
```
지정된 로그 그룹에 ProtoLog를 사용 설정합니다.
```
adb shell cmd window logging enable [group...]
```
지정된 로그 그룹에 대해 ProtoLog를 사용 중지합니다.
```
adb shell cmd window logging disable [group...]
```
지정된 로그 그룹에 Logcat 로깅을 사용 설정합니다.
```
adb shell cmd window logging enable-text [group...]
```
지정된 로그 그룹의 Logcat 로깅을 사용 중지합니다.
```
adb shell cmd window logging disable-text [group...]
```

WMShell:

ProtoLog 시작:

adb shell dumpsys activity service SystemUIService WMShell

SurfaceFlinger 트레이스 (레이어)

SurfaceFlinger 레이어 추적은 캡처에 Perfetto 트레이스를 사용합니다. 구성 정보는 트레이스 구성을 참고하세요.

SurfaceFlinger 레이어 추적 구성의 다음 예를 참고하세요.

unique_session_name: "surfaceflinger_layers_active"
buffers: {
    size_kb: 63488
    fill_policy: RING_BUFFER
}
data_sources: {
    config {
        name: "android.surfaceflinger.layers"
        surfaceflinger_layers_config: {
            mode: MODE_ACTIVE
            trace_flags: TRACE_FLAG_INPUT
            trace_flags: TRACE_FLAG_COMPOSITION
            trace_flags: TRACE_FLAG_HWC
            trace_flags: TRACE_FLAG_BUFFERS
            trace_flags: TRACE_FLAG_VIRTUAL_DISPLAYS
        }
    }
}

SurfaceFlinger 레이어의 추적을 생성하려면 다음 명령어 예시를 참고하세요.

adb shell -t perfetto \
    -c - --txt \
    -o /data/misc/perfetto-traces/trace \

SurfaceFlinger 덤프 (레이어)

SurfaceFlinger 덤프를 캡처하려면 다음 단계를 따르세요.

adb exec-out dumpsys SurfaceFlinger --proto > sf_dump.winscope

셸 전환

다음 명령어는 전환 추적에 사용됩니다.

system_server 프로세스에서 다음을 실행합니다.

트레이스를 시작합니다.

adb shell cmd window shell tracing start

트레이스를 중지하려면 다음 단계를 따르세요.
```
adb shell cmd window shell tracing stop
```

WMShell에서 트레이스를 시작합니다.

adb shell dumpsys activity service SystemUIService WMShell transitions tracing start

WMShell에서 트레이스를 중지합니다.

adb shell dumpsys activity service SystemUIService WMShell transitions tracing stop

IME

다음 명령어는 입력 방식 편집기 (IME) 추적에 사용됩니다.

입력 방식 (IM) 클라이언트, 입력 방식 서비스 (IMS), 입력 방식 관리 서비스 (IMMS)의 IME 추적을 시작합니다.
```
adb shell ime tracing start
```
IME 클라이언트, IMS, IMMS 추적을 시작합니다.
```
adb shell ime tracing stop
```

SurfaceFlinger (거래)

SurfaceFlinger 트랜잭션 추적은 캡처에 Perfetto 트레이스를 사용합니다. 구성 정보는 트레이스 구성을 참고하세요.

SurfaceFlinger 활성 추적을 위한 Perfetto 구성의 다음 예를 참고하세요.

unique_session_name: "surfaceflinger_transactions_active"
buffers: {
    size_kb: 1024
    fill_policy: RING_BUFFER
}
data_sources: {
    config {
        name: "android.surfaceflinger.transactions"
        surfaceflinger_transactions_config: {
            mode: MODE_ACTIVE
        }
    }
}
write_into_file: true
file_write_period_ms: 100

SurfaceFlinger 연속 추적을 위한 Perfetto 구성의 다음 예를 참고하세요.

unique_session_name: "surfaceflinger_transactions_continuous"
buffers: {
    size_kb: 1024
    fill_policy: RING_BUFFER
}
data_sources: {
    config {
        name: "android.surfaceflinger.transactions"
        surfaceflinger_transactions_config: {
            mode: MODE_CONTINUOUS
        }
    }
}

SurfaceFlinger 트랜잭션의 추적을 생성하려면 다음 명령어 예시를 참고하세요.

    adb shell perfetto \
    -c - --txt \
    -o /data/misc/perfetto-traces/trace \