تسجيل عمليات التتبُّع باستخدام أوامر 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
  

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

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

• ابدأ تتبُّع محرر أسلوب الإدخال (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 \