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à các 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, 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 bật trong một phiên theo dõi duy nhất.

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 bài viết 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ý. Giá trị được hỗ trợ:

    • LOG_LEVEL_VERBOSE: Ghi nhật ký tất cả các phần tử với 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 các bản tổng quan nhanh về 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 các bản tổng quan nhanh về trạng thái riêng lẻ 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ừ phi đượ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 đều được theo dõi, trừ phi bạn chỉ định một chế độ ghi đè nhóm. Ví dụ: bạn có thể dùng tuỳ chọn này để bật tính năng ghi nhật ký tất cả cá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 đè theo nhóm (group_overrides): Cho phép định cấu hình thủ công cấp độ nhật ký 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 từng thông báo 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ác quy tắc bảo đảm 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ả các sự kiện đầu vào do hệ thống xử lý, bất kể bối cảnh mà hệ thống xử lý các 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 những 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 nhật ký các mục:

  • MODE_ACTIVE: Theo dõi ảnh chụp nhanh của các lớp. Ảnh chụp nhanh được thực hiện 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 diễn ra khi nguồn dữ liệu này được xoá.
  • MODE_DUMP: Theo dõi một ảnh chụp nhanh của lớp.
  • MODE_GENERATED_BUGREPORT_ONLY: Tương tự như MODE_GENERATED, nhưng chỉ kích hoạt quá trình tạo ảnh chụp nhanh lớp khi có báo cáo lỗi, chứ không phải bất cứ khi nào dấu vết được xoá.

Cờ theo dõi (trace_flags):

  • TRACE_FLAG_INPUT: Nếu vùng hiển thị chứa dữ liệu đầu vào, hãy theo dõi thông tin cụ thể về 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 bổ sung của trình kết hợp phần cứng không có cấu trúc.

  • TRACE_FLAG_BUFFERS: Định cấu hình SurfaceFlinger để theo dõi mọi 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 có sự 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.

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ó lựa 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 nhật ký 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 xoá. Vùng đệm vòng chứa trạng thái ban đầu và các giao dịch mới nhất của SurfaceFlinger.

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

Ví dụ

Sau đây là ví dụ về loại dấu vết giao dịch 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.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ó lựa 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ó lựa 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 duy nhất. 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 đây. 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 quá trình ghi lại dấu vết:

    adb shell wm tracing save-for-bugreport

  • Ghi nhật ký dấu vết một lần trên mỗi khung hình:

    adb shell wm tracing frame

  • Ghi nhật ký 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

  • Trạng thái dấu vết in:

    adb shell wm tracing status

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

    adb shell wm tracing level

Dữ liệu kết xuất WindowManager

Cách ghi lại tệp kết xuất 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 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 ví dụ 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 \

Kết xuất SurfaceFlinger (các lớp)

Cách ghi lại tệp kết xuất SurfaceFlinger:

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

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 một dấu vết:

    adb shell cmd window shell tracing start

  • Dừng dấu vết:

    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 dấu vết 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 các ứ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 các ứ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 Cấu hình theo dõi để biết thông tin về cấu hình.

Hãy xem ví dụ sau đây về cấu hình Perfetto cho tính năng theo dõi đang hoạt động 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 hoạt động theo dõi liên tục SurfaceFlinger:

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 ví dụ 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 \