Ghi lại dấu vết bằng lệnh adb

Bạn có thể thu thập dấu vết Winscope bằng dòng lệnh adb trên các bản gỡ lỗi (tức là bản dựng userdebug và eng). Trước khi thu thập dấu vết Winscope bằng adb, hãy chạy adb root.

Kể từ Android 15, các dấu vết Winscope được tích hợp vào Perfetto và được thu thập bằng dòng lệnh Perfetto. Mỗi dấu vết Winscope là một nguồn dữ liệu Perfetto có cấu hình riêng. Bạn có thể bật từng cấu hình hoặc trong một phiên theo dõi.

Trong Android 14 trở xuống, mỗi dấu vết Winscope có một lệnh riêng và bạn có thể thu thập từng dấu vết một cách độc lập. Hãy xem phần Ghi lại dấu vết trong Android 14 trở xuống để biết thêm thông tin.

WindowManager

Sử dụng tên nguồn dữ liệu android.windowmanager cho loại dấu vết này.

Các lựa chọn về cấu hình

  • Cấp độ nhật ký (log_level): Chỉ định độ chi tiết của nhật ký. Các giá trị được hỗ trợ:

    • LOG_LEVEL_VERBOSE: Ghi nhật ký tất cả các phần tử có lượng thông tin tối đa.
    • LOG_LEVEL_DEBUG: Ghi nhật ký tất cả các phần tử nhưng không ghi tất cả dữ liệu cấu hình.
    • LOG_LEVEL_CRITICAL: Chỉ ghi lại các phần tử hiển thị, với mức hao tổn hiệu suất tối thiểu.

  • Tần suất ghi nhật ký (log_frequency): Xác định tần suất ghi nhật ký các mục:

    • LOG_FREQUENCY_FRAME: Theo dõi ảnh chụp nhanh trạng thái khi một khung hình được xác nhận.
    • LOG_FREQUENCY_TRANSACTION: Theo dõi ảnh chụp nhanh trạng thái mỗi khi một giao dịch được xác nhận.
    • LOG_FREQUENCY_SINGLE_DUMP: Theo dõi ảnh chụp nhanh trạng thái đơn khi nguồn dữ liệu được khởi động.

Hãy xem WindowManager để biết thông tin chi tiết về các giá trị cấu hình.

Ví dụ

Sau đây là ví dụ về loại dấu vết WindowManager cho 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.windowmanager"
           windowmanager_config: {
              log_level: LOG_LEVEL_VERBOSE
              log_frequency: LOG_FREQUENCY_TRANSACTION
           }
       }
   }
EOF

ProtoLog

Sử dụng tên nguồn dữ liệu android.protolog cho loại dấu vết này.

Các lựa chọn về cấu hình

Chế độ theo dõi (tracing_mode): Xác định cấu hình nhật ký cần sử dụng:

  • DEFAULT: Chỉ theo dõi các nhóm và cấp độ nhật ký được chỉ định trong group_overrides.
  • ENABLE_ALL: Theo dõi tất cả các nhóm và cấp độ nhật ký, trừ khi được chỉ định trong group_overrides.

Cấp độ nhật ký tối thiểu (default_log_from_level): Nếu được đặt, mọi thông báo có cấp độ nhật ký cao hơn và bao gồm cấp độ này sẽ được theo dõi, trừ phi bạn chỉ định một nhóm ghi đè. Ví dụ: thuộc tính này được dùng để bật tính năng ghi nhật ký tất cả cảnh báo và lỗi mà không cần bật tất cả nhật ký. Sau đây là các giá trị được hỗ trợ:

  • PROTOLOG_LEVEL_DEBUG
  • PROTOLOG_LEVEL_VERBOSE
  • PROTOLOG_LEVEL_INFO
  • PROTOLOG_LEVEL_WARN
  • PROTOLOG_LEVEL_ERROR
  • PROTOLOG_LEVEL_WTF

Ghi đè nhóm (group_overrides): Cho phép định cấu hình cấp độ nhật ký theo cách thủ công cho từng nhóm ProtoLog. Mỗi nhóm chứa:

  • name: Tên nhóm ProtoLog, được dùng trong mã nguồn Android.
  • log_from: Tương tự như default_log_from_level nhưng chỉ được chỉ định cho nhóm hiện tại.

  • collect_stacktrace: Khi được đặt thành true, sẽ thu thập dấu vết ngăn xếp cho mỗi thông điệp ProtoLog trong nhóm đang được theo dõi.

Ví dụ

Sau đây là ví dụ về loại dấu vết ProtoLog cho 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.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

Đầu vào

Sử dụng tên nguồn dữ liệu android.input.inputevent cho loại dấu vết này.

Các lựa chọn về cấu hình

Chế độ theo dõi (trace_mode): Xác định xem có nên bắt đầu dấu vết đầu vào bằng cách sử dụng các quy tắc bảo vệ quyền riêng tư hay ghi lại tất cả các sự kiện đầu vào:

  • TRACE_MODE_TRACE_ALL: Ghi lại tất cả sự kiện đầu vào do hệ thống xử lý, bất kể ngữ cảnh xử lý sự kiện đó.
  • TRACE_MODE_USE_RULES: Sử dụng các quy tắc theo dõi được xác định trong cấu hình này để chỉ định sự kiện cần theo dõi. Hãy xem android_input_event_config.proto để biết thêm thông tin về cách chỉ định các quy tắc cho dấu vết.

Ví dụ

Sau đây là ví dụ về loại dấu vết đầu vào cho 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 (lớp)

Sử dụng tên nguồn dữ liệu android.surfaceflinger.layers cho loại dấu vết này.

Các lựa chọn về cấu hình

Chế độ theo dõi (mode): Xác định tần suất ghi lại các mục:

  • MODE_ACTIVE: Theo dõi ảnh chụp nhanh của các lớp. Ảnh chụp nhanh được chụp mỗi khi có thay đổi về lớp.
  • MODE_GENERATED: Tạo ảnh chụp nhanh lớp từ các giao dịch được lưu giữ trong vùng đệm vòng nội bộ của SurfaceFlinger. Quá trình tạo ảnh chụp nhanh của lớp xảy ra khi nguồn dữ liệu này được xả.
  • MODE_DUMP: Theo dõi một ảnh chụp nhanh của một lớp.
  • MODE_GENERATED_BUGREPORT_ONLY: Giống như MODE_GENERATED, nhưng chỉ kích hoạt quá trình tạo ảnh chụp nhanh của lớp khi lấy báo cáo lỗi, chứ không phải bất cứ khi nào một dấu vết được xả.

Cờ theo dõi (trace_flags):

  • TRACE_FLAG_INPUT: Nếu nền tảng chứa dữ liệu đầu vào, hãy theo dõi thông tin cụ thể của cửa sổ đầu vào.
  • TRACE_FLAG_COMPOSITION: Theo dõi loại thành phần và vùng hiển thị.

  • TRACE_FLAG_EXTRA: Theo dõi siêu dữ liệu bổ sung của nền tảng, bao gồm cả các lớp ngoài màn hình.

  • TRACE_FLAG_HWC: Theo dõi siêu dữ liệu trình tổng hợp phần cứng không có cấu trúc bổ sung.

  • TRACE_FLAG_BUFFERS: Định cấu hình SurfaceFlinger để theo dõi tất cả thay đổi về vùng đệm trên bề mặt. Theo mặc định, SurfaceFlinger chỉ theo dõi trạng thái mới khi xảy ra thay đổi về hình học.

  • TRACE_FLAG_VIRTUAL_DISPLAYS: Bao gồm các lớp hiển thị ảo trong dấu vết.

Ví dụ

Sau đây là ví dụ về loại dấu vết SurfaceFlinger cho 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.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

Hãy xem SurfaceFlinger để biết thông tin chi tiết về ý nghĩa của các giá trị cấu hình khác nhau.

Hiệu ứng chuyển đổi shell

Sử dụng tên nguồn dữ liệu com.android.wm.shell.transition cho loại dấu vết này.

Các lựa chọn về cấu hình

Loại dấu vết này không có tuỳ chọn cấu hình.

Ví dụ

Sau đây là ví dụ về loại dấu vết chuyển đổi shell cho 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 (giao dịch)

Sử dụng tên nguồn dữ liệu android.surfaceflinger.transactions cho loại dấu vết này.

Các lựa chọn về cấu hình

Chế độ theo dõi (mode): Xác định tần suất ghi lại các mục:

  • MODE_CONTINUOUS: SurfaceFlinger ghi vùng đệm vòng nội bộ của các giao dịch mỗi khi nguồn dữ liệu được xả. Vùng đệm vòng chứa trạng thái ban đầu của SurfaceFlinger và các giao dịch mới nhất.

  • MODE_ACTIVE: SurfaceFlinger ghi trạng thái ban đầu, sau đó ghi từng giao dịch đến cho đến khi nguồn dữ liệu bị dừng.

Ví dụ

Sau đây là ví dụ về loại theo dõi giao dịch SurfaceFlinger choadb.

$ 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

Sử dụng tên nguồn dữ liệu: android.inputmethod cho loại dấu vết này.

Các lựa chọn về cấu hình

Loại dấu vết này không có tuỳ chọn cấu hình.

Ví dụ

Sau đây là ví dụ về loại dấu vết IME cho 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.inputmethod"
       }
   }
EOF

ViewCapture

Sử dụng tên nguồn dữ liệu android.viewcapture cho loại dấu vết này.

Các lựa chọn về cấu hình

Loại dấu vết này không có tuỳ chọn cấu hình.

Ví dụ

Sau đây là ví dụ về loại dấu vết ViewCapture cho 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.viewcapture"
       }
   }
EOF

Ví dụ đầy đủ

Perfetto cho phép bạn thu thập dữ liệu từ nhiều nguồn trong một cấu hình. Bạn có thể thu thập tất cả dấu vết Winscope bằng một lệnh duy nhất:

$ 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

Ghi lại dấu vết trong Android 14 trở xuống

Chạy adb root trước khi chạy các lệnh adb shell cho từng dấu vết sau. Khi quá trình theo dõi kết thúc, các tệp theo dõi sẽ có trong /data/misc/wmtrace. Để sao chép một tệp hoặc thư mục và thư mục con của tệp đó từ một thiết bị, hãy xem phần Sao chép tệp vào và từ thiết bị.

Dấu vết WindowManager

Cách ghi lại dấu vết WindowManager:

  • Bật tính năng theo dõi:

    adb shell wm tracing start

  • Tắt tính năng theo dõi:

    adb shell wm tracing stop

  • Lưu dữ liệu ghi nhật ký vào tệp trong khi chạy tính năng ghi lại dấu vết:

    adb shell wm tracing save-for-bugreport

  • Ghi lại dấu vết một lần trên mỗi khung:

    adb shell wm tracing frame

  • Ghi lại từng giao dịch:

    adb shell wm tracing transaction

  • Đặt kích thước nhật ký tối đa (tính bằng KB):

    adb shell wm tracing size

  • In trạng thái theo dõi:

    adb shell wm tracing status

  • Đặt cấp độ nhật ký thành critical (chỉ các cửa sổ hiển thị có thông tin giảm thiểu), trim (tất cả các cửa sổ có thông tin giảm thiểu) hoặc all (tất cả các cửa sổ và thông tin):

    adb shell wm tracing level

Tệp báo lỗi WindowManager

Cách ghi tệp báo lỗi WindowManager:

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

ProtoLog

Các lệnh sau đây được dùng cho hệ thống ProtoLog.

Trong quy trình system_server:

  • Bắt đầu ProtoLog:

    adb shell cmd window logging start

  • Dừng ProtoLog:

    adb shell cmd window logging stop

  • Bật ProtoLog cho các nhóm nhật ký nhất định:

    adb shell cmd window logging enable [group...]

  • Tắt ProtoLog cho các nhóm nhật ký nhất định:

    adb shell cmd window logging disable [group...]

  • Bật tính năng ghi nhật ký Logcat cho các nhóm nhật ký nhất định:

    adb shell cmd window logging enable-text [group...]

  • Tắt tính năng ghi nhật ký Logcat cho các nhóm nhật ký nhất định:

    adb shell cmd window logging disable-text [group...]

Trong WMShell:

  • Bắt đầu ProtoLog:

    adb shell dumpsys activity service SystemUIService WMShell

Dấu vết SurfaceFlinger (lớp)

Tính năng theo dõi lớp SurfaceFlinger sử dụng dấu vết Perfetto để ghi lại. Hãy xem phần Định cấu hình theo dõi để biết thông tin về cấu hình.

Hãy xem ví dụ sau về cấu hình để theo dõi lớp 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
        }
    }
}

Hãy xem lệnh mẫu sau đây để tạo dấu vết cho các lớp SurfaceFlinger:

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

Tệp báo lỗi SurfaceFlinger (các lớp)

Cách ghi lại tệp báo lỗi SurfaceFlinger:

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

Hiệu ứng chuyển đổi shell

Các lệnh sau đây được dùng để theo dõi quá trình chuyển đổi.

Trong quy trình system_server:

  • Bắt đầu theo dõi:

    adb shell cmd window shell tracing start

  • Dừng theo dõi:

    adb shell cmd window shell tracing stop

  • Bắt đầu ghi lại dấu vết trong WMShell:

    adb shell dumpsys activity service SystemUIService WMShell transitions tracing start

  • Dừng theo dõi trong WMShell:

    adb shell dumpsys activity service SystemUIService WMShell transitions tracing stop

IME

Các lệnh sau đây được dùng để theo dõi Trình chỉnh sửa phương thức nhập (IME):

  • Bắt đầu theo dõi IME cho ứng dụng Phương thức nhập (IM), Dịch vụ phương thức nhập (IMS) và Dịch vụ quản lý phương thức nhập (IMMS):

    adb shell ime tracing start

  • Bắt đầu theo dõi ứng dụng IME, IMS và IMMS:

    adb shell ime tracing stop

SurfaceFlinger (giao dịch)

Tính năng theo dõi giao dịch SurfaceFlinger sử dụng dấu vết Perfetto để ghi lại. Hãy xem phần Định cấu hình theo dõi để biết thông tin về cấu hình.

Hãy xem ví dụ sau về cấu hình Perfetto cho tính năng theo dõi đang hoạt động của SurfaceFlinger:

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

Hãy xem ví dụ sau về cấu hình Perfetto cho SurfaceFlinger theo dõi liên tục:

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
        }
    }
}

Hãy xem lệnh mẫu sau đây để tạo dấu vết cho các giao dịch SurfaceFlinger:

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