บันทึกร่องรอยด้วยคำสั่ง 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 จะรวบรวม Stack Trace สำหรับ ข้อความ 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: ติดตามข้อมูลเมตาของ Surface เพิ่มเติม รวมถึงเลเยอร์นอกหน้าจอ

• TRACE_FLAG_HWC: ติดตามข้อมูลเมตาของคอมโพสเซอร์ฮาร์ดแวร์ที่ไม่มีโครงสร้างเพิ่มเติม

• TRACE_FLAG_BUFFERS: กำหนดค่า SurfaceFlinger ให้ติดตามการเปลี่ยนแปลงบัฟเฟอร์ทั้งหมด ใน Surface โดยค่าเริ่มต้น 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)

• เริ่มการติดตาม IME สำหรับไคลเอ็นต์ Input Method (IM), Input Method Service (IMS) และ Input Method Management Service (IMMS) โดยทำดังนี้

  adb shell ime tracing start
  

• เริ่มติดตามไคลเอ็นต์ IME, IMS และ IMMS โดยทำดังนี้

  adb shell ime tracing stop
  

SurfaceFlinger (ธุรกรรม)

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

ดูตัวอย่างการกำหนดค่า Perfetto สำหรับ SurfaceFlinger active tracing ต่อไปนี้

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 \