تسجيل عمليات التتبُّع باستخدام أوامر adb

يمكن جمع عمليات تتبُّع Winscope باستخدام سطر الأوامر adb في إصدارات تصحيح الأخطاء (أي إصدارات userdebug وeng). قبل جمع مسارات Winscope باستخدام adb، شغِّل adb root.

بدءًا من Android 15، تم دمج عمليات تتبُّع Winscope في Perfetto ويتم جمعها باستخدام سطر معالجة Perfetto. كلّ عملية تتبُّع في Winscope هي مصدر بيانات Perfetto مع إعداداته الخاصة. يمكنك تفعيل الإعدادات بشكل فردي أو في جلسة traceding واحدة.

في الإصدار 14 من Android والإصدارات الأقدم، يحتوي كلّ تتبُّع 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: تتتبّع لقطات حالة فردية عند بدء مصدر data.

اطّلِع على 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 لهذا نوع التتبّع.

خيارات الضبط

لا يتضمّن نوع التتبّع هذا خيارات ضبط.

مثال

في ما يلي مثال على نوع تتبُّع انتقال 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

تسجيل عمليات التتبّع في الإصدار 14 من نظام التشغيل Android والإصدارات الأقدم

شغِّل الأمر 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
  

• تتبُّع السجلّ مرة واحدة لكل إطار:

  adb shell wm tracing frame
  

• تسجيل كل معاملة:

  adb shell wm tracing transaction
  

• اضبط الحد الأقصى لحجم السجلّ (بالكيلوبايت):

  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):

• ابدأ تتبُّع أسلوب الإدخال لعملاء أسلوب الإدخال وخدمة أسلوب الإدخال وخدمة إدارة أسلوب الإدخال:

  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 \