บันทึกร่องรอยด้วยคำสั่ง 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 แต่ทริกเกอร์การสร้างสแนปชอตเลเยอร์เฉพาะเมื่อมีการส่งรายงานข้อบกพร่องเท่านั้น ไม่ใช่ทุกครั้งที่มีการล้างการติดตาม

Flag การติดตาม (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

การเปลี่ยน Shell

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

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

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

ตัวอย่าง

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

การเปลี่ยน Shell

คําสั่งต่อไปนี้ใช้สําหรับการติดตามการเปลี่ยน

ในกระบวนการ 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)

• เริ่มการติดตาม 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 \