תיעוד נתוני מעקב באמצעות פקודות 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: מעקב אחרי קובצי snapshot של מצב כשמתבצעת הקצאה של פריים.
  • ‫LOG_FREQUENCY_TRANSACTION: עוקב אחרי קובצי snapshot של מצב בכל פעם שמתבצעת פעולת אישור (commit) של טרנזקציה.
  • ‫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: Traces מתעד רק קבוצות ורמות של יומנים שצוינו ב-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 (layers)

משתמשים בשם מקור הנתונים android.surfaceflinger.layers לסוג העקבות הזה.

אפשרויות הגדרה

מצב מעקב (mode): מגדיר את התדירות שבה הפריטים נרשמים ביומן:

• ‫MODE_ACTIVE: תמונות מצב של שכבות של עקבות. תמונת מצב מצולמת בכל פעם שמתרחש שינוי בשכבות.
• ‫MODE_GENERATED: יוצר תמונות מצב של שכבות מהעסקאות שנשמרו במאגר הזמני הפנימי של SurfaceFlinger. יצירת התמונות של השכבה מתרחשת כשמקור הנתונים הזה מתרוקן.
• ‫MODE_DUMP: מעקב אחר קובץ snapshot של שכבה אחת.
• ‫MODE_GENERATED_BUGREPORT_ONLY: כמו MODE_GENERATED, אבל מפעיל את יצירת התמונות של השכבות רק כשמפיקים דוח באגים, ולא בכל פעם שמתבצעת שטיפה של נתוני מעקב.

דגלים של Trace ‏ (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 מוסבר מה המשמעות של ערכי הגדרה שונים.

מעברים בין Shell

צריך להשתמש בשם מקור הנתונים 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 (transactions)

משתמשים בשם מקור הנתונים 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
  

• הגדרת הגודל המקסימלי של היומן (ב-KB):

  adb shell wm tracing size
  

• הדפסת סטטוס המעקב:

  adb shell wm tracing status
  

• מגדירים את רמת היומן ל-critical (חלונות גלויים בלבד עם מידע מצומצם), ל-trim (כל החלונות עם מידע מצומצם) או ל-all (כל החלונות והמידע):

  adb shell wm tracing level
  

‫WindowManager dumps

כדי לצלם קובצי dump של 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 dumps (layers)

כדי לצלם קובצי dump של SurfaceFlinger:

adb exec-out dumpsys SurfaceFlinger --proto > sf_dump.winscope

מעברים בין Shell

הפקודות הבאות משמשות למעקב אחר מעברים.

במהלך התהליך 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 (transactions)

במעקב אחר עסקאות של 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 \