ثبت ردپاها با فرمان‌های 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 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

برای ضبط کردن تخلیه‌های 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) استفاده می‌شود:

  1. شروع ردیابی 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 \