ردیابی با دستورات adb

شما می‌توانید با استفاده از خط فرمان adb در نسخه‌های debug (یعنی نسخه‌های userdebug و eng ) ردپاهای Winscope را جمع‌آوری کنید. قبل از جمع‌آوری ردپاهای Winscope با adb ، adb root اجرا کنید.

از اندروید ۱۵ به بعد، ردپاهای Winscope در Perfetto ادغام شده و با استفاده از خط فرمان Perfetto جمع‌آوری می‌شوند. هر ردپا در Winscope یک منبع داده Perfetto با پیکربندی خاص خود است. می‌توانید پیکربندی‌ها را به صورت جداگانه یا در یک جلسه ردیابی واحد فعال کنید.

در اندروید ۱۴ و پایین‌تر، هر رد Winscope دستور متفاوتی دارد و می‌توانید هر کدام را به‌طور مستقل جمع‌آوری کنید. برای اطلاعات بیشتر به بخش «ردیابی ردها در اندروید ۱۴ و پایین‌تر» مراجعه کنید.

مدیر پنجره

برای این نوع ردیابی از نام منبع داده 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

پروتو لاگ

برای این نوع ردیابی از نام منبع داده 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، که در کد منبع اندروید استفاده شده است.
• 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

سرفیس‌فلینگر (تراکنش‌ها)

برای این نوع ردیابی از نام منبع داده 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

آی ام ای

برای این نوع ردیابی از نام منبع داده 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

مشاهده ضبط

برای این نوع ردیابی از نام منبع داده 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

ضبط ردپاها در اندروید ۱۴ و پایین‌تر

قبل از اجرای دستورات adb shell برای هر یک از ردیابی‌های زیر، adb root اجرا کنید. در پایان ردیابی، فایل‌های ردیابی در مسیر /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

برای ضبط dump های WindowManager:

adb exec-out dumpsys window --proto > window_dump.winscope

پروتو لاگ

دستورات زیر برای سیستم ProtoLog استفاده می‌شوند.

در فرآیند system_server :

• شروع پروتو لاگ:

  adb shell cmd window logging start
  

• توقف پروتو لاگ:

  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...]
  

در WMShel:

• شروع پروتو لاگ:

  adb shell dumpsys activity service SystemUIService WMShell
  

ردپاهای SurfaceFlinger (لایه‌ها)

ردیابی لایه SurfaceFlinger از ردیابی Perfetto برای ضبط استفاده می‌کند. برای اطلاعات پیکربندی به پیکربندی Trace مراجعه کنید.

مثال زیر پیکربندی ردیابی لایه 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 (لایه‌ها)

برای گرفتن dump های 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
  

• شروع یک ردیابی در WMShel:

  adb shell dumpsys activity service SystemUIService WMShell transitions tracing start
  

• متوقف کردن یک ردیابی در WMShelle:

  adb shell dumpsys activity service SystemUIService WMShell transitions tracing stop
  

آی ام ای

دستورات زیر برای ردیابی ویرایشگر روش ورودی (IME) استفاده می‌شوند:

1. شروع ردیابی IME برای کلاینت‌های روش ورودی (IM)، سرویس روش ورودی (IMS) و سرویس مدیریت روش ورودی (IMMS): adb shell ime tracing start

• شروع به ردیابی کلاینت‌های IME، IMS و IMMS کنید:

  adb shell ime tracing stop
  

سرفیس‌فلینگر (تراکنش‌ها)

ردیابی تراکنش SurfaceFlinger از ردیابی Perfetto برای ثبت استفاده می‌کند. برای اطلاعات پیکربندی به پیکربندی Trace مراجعه کنید.

مثال زیر پیکربندی 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 \