บันทึกร่องรอยด้วยคำสั่ง ADB

คุณสามารถรวบรวมการติดตาม Winscope ได้โดยใช้บรรทัดคำสั่ง adb ในบิลด์ดีบัก (นั่นคือ บิลด์ userdebug และ eng) ก่อนที่จะรวบรวมการติดตาม Winscope ด้วย adb ให้เรียกใช้ 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

ตัวอย่าง

ตัวอย่างต่อไปนี้แสดงประเภทการติดตาม WindowManager สำหรับ 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

ใช้ชื่อแหล่งข้อมูล 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: ชื่อกลุ่ม ProtoLog ที่ใช้ในซอร์สโค้ด Android
• log_from: เหมือนกับ default_log_from_level แต่ระบุไว้สำหรับ กลุ่มปัจจุบันเท่านั้น

• collect_stacktrace: เมื่อตั้งค่าเป็น true ระบบจะรวบรวมสแต็กเทรซสำหรับข้อความ ProtoLog แต่ละรายการในกลุ่มที่กำลังติดตาม

ตัวอย่าง

ตัวอย่างต่อไปนี้แสดงประเภทการติดตาม ProtoLog สำหรับ 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

อินพุต

ใช้ชื่อแหล่งข้อมูล 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: รวมเลเยอร์การแสดงผลเสมือนในการติดตาม

ตัวอย่าง

ตัวอย่างต่อไปนี้แสดงประเภทการติดตาม SurfaceFlinger สำหรับ 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

ดูรายละเอียดเกี่ยวกับความหมายของค่าการกำหนดค่าต่างๆ ได้ที่ 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 จะเขียนสถานะเริ่มต้นและธุรกรรมขาเข้าแต่ละรายการจนกว่าจะหยุดแหล่งข้อมูล

ตัวอย่าง

ตัวอย่างต่อไปนี้แสดงประเภทการติดตามธุรกรรม SurfaceFlinger สำหรับ 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

ใช้ชื่อแหล่งข้อมูล android.inputmethod สำหรับการติดตามประเภทนี้

ตัวเลือกการกำหนดค่า

การติดตามประเภทนี้ไม่มีตัวเลือกการกำหนดค่า

ตัวอย่าง

ตัวอย่างต่อไปนี้แสดงประเภทการติดตาม IME สำหรับ 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

ใช้ชื่อแหล่งข้อมูล android.viewcapture สำหรับการติดตามประเภทนี้

ตัวเลือกการกำหนดค่า

การติดตามประเภทนี้ไม่มีตัวเลือกการกำหนดค่า

ตัวอย่าง

ตัวอย่างต่อไปนี้แสดงประเภทการติดตาม ViewCapture สำหรับ 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

ตัวอย่างที่สมบูรณ์

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 root ก่อนที่จะเรียกใช้คำสั่ง adb shell สำหรับการติดตามแต่ละรายการต่อไปนี้ เมื่อสิ้นสุดการติดตาม ไฟล์การติดตามจะอยู่ใน /data/misc/wmtrace หากต้องการคัดลอกไฟล์หรือไดเรกทอรีและไดเรกทอรีย่อยจาก อุปกรณ์ โปรดดู หัวข้อคัดลอกไฟล์ไปยังและจากอุปกรณ์

การติดตาม WindowManager

วิธีบันทึกการติดตาม WindowManager

• เปิดใช้การติดตาม

  adb shell wm tracing start
  

• ปิดใช้การติดตาม

  adb shell wm tracing stop
  

• บันทึกข้อมูลการบันทึกลงในไฟล์ขณะเรียกใช้การบันทึกการติดตาม

  adb shell wm tracing save-for-bugreport
  

• บันทึกการติดตาม 1 ครั้งต่อเฟรม

  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. เริ่มการติดตาม IME สำหรับไคลเอ็นต์วิธีการป้อนข้อมูล (IM), บริการวิธีการป้อนข้อมูล (IMS) และบริการการจัดการวิธีการป้อนข้อมูล (IMMS): adb shell ime tracing start

• เริ่มการติดตามไคลเอ็นต์ IME, IMS และ IMMS

  adb shell ime tracing stop
  

SurfaceFlinger (ธุรกรรม)

การติดตามธุรกรรม SurfaceFlinger ใช้การติดตาม Perfetto สำหรับการบันทึก ดูข้อมูลการกำหนดค่าได้ที่ การกำหนดค่าการติดตาม

ตัวอย่างต่อไปนี้แสดงการกำหนดค่า Perfetto สำหรับ 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

ตัวอย่างต่อไปนี้แสดงการกำหนดค่า Perfetto สำหรับ 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
        }
    }
}

คำสั่งตัวอย่างต่อไปนี้จะสร้างการติดตามสำหรับธุรกรรม SurfaceFlinger

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