adb 명령어로 트레이스 캡처

디버그 빌드(userdebug 및 eng 빌드)에서 adb 명령줄을 사용하여 Winscope 트레이스를 수집할 수 있습니다. 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) 트레이싱에 사용됩니다.

  1. 입력 방식 (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 \