מעבר בין חלונות מעקב באמצעות Winscope

Winscope הוא כלי אינטרנט שמאפשר למשתמשים להקליט, להפעיל מחדש ולנתח את המצבים של כמה שירותי מערכת במהלך אנימציות ומעברים ואחריהן. Winscope מתעד את כל המצבים הרלוונטיים של שירות המערכת בקובץ מעקב. באמצעות ממשק המשתמש של Winscope עם קובץ המעקב, אפשר לבדוק את מצב השירותים האלה בכל פריים אנימציה, עם או בלי הקלטת מסך, על ידי הפעלה מחדש, ביצוע שלבים וניפוי באגים במעברים.

שירותי המערכת שיוצרים עקבות שאפשר לטעון ל-Winscope הם:

  • SurfaceFlinger
  • WindowManager
  • WMShell
  • IME
  • מרכז האפליקציות

הפעלת מציג המעקב של Winscope

מעקב Winscope הוא חלק מהשירותים בפלטפורמה. בקטע הזה מפורטים השלבים להורדה, ליצירת גרסה build ולהפעלה של כלי הצפייה ב-Winscope.

כדי להגדיר את המחשב להרצת ה-tracer של Winscope:

  1. מורידים את המקור של Android.

  2. עוברים לתיקייה Winscope:

    cd development/tools/winscope

  3. מתקינים את יחסי התלות באמצעות:

    npm install

    כדי להציג את הרשימה של הפקודות הזמינות, מריצים את הפקודה: npm run

  4. יוצרים את כל יעדי המוצר ובודקים את היעדים באמצעות:

    npm run build:prod

  5. מריצים את Winscope באמצעות:

    npm run start

תיעוד מעקבים

אפשר לתעד עקבות במכשיר באמצעות Winscope או באמצעות פקודות של Android Debug Bridge‏ (adb).

תיעוד עקבות במכשיר

תיעוד מעקבים במכשיר לצורך איסוף נתונים בזמן שליחת באגים במקרים של בעיות באנימציה. כל הטרייסים של ממשק המשתמש מתועדים בשיטה הזו, כי אי אפשר להתאים אישית את ההגדרות.

במכשיר Android:

  1. מפעילים את האפשרויות למפתחים.
  2. בוחרים באפשרות מעקב מערכת בקטע 'אפשרויות למפתחים'.
  3. מפעילים את האפשרות איסוף עקבות Winscope.
  4. בקטע שונות:
    1. מפעילים את האפשרות צירוף הקלטות לדוחות על באגים.
    2. מפעילים את האפשרות הצגת לחצן בהגדרות המהירות.
  5. עוברים למקום שבו רוצים לשכפל את הבאג.

  6. כדי להתחיל בצילום, פותחים את ההגדרות המהירות ובוחרים באפשרות הקלטת מעקב:

    Quick_setting_winscope

    איור 1. תפריט הגדרות מהירות עם Record Trace.

  7. מבצעים רק את השלבים שדרושים כדי לשחזר את הבאג.

  8. כדי להפסיק את הצילום, פותחים את ההגדרות המהירות ובוחרים באפשרות הפסקת המעקב.

  9. משתפים את היומן שתועד באמצעות אחת מהאפשרויות המפורטות, כמו Gmail, Drive או BetterBug.

תיעוד עקבות באמצעות Winscope

אפשר לתעד מעקבים באמצעות Winscope לצורך פיתוח וניפוי באגים מקומיים. Winscope משתמש ב-adb, שתומך בחיבור המכשיר באמצעות USB או Wi-Fi.

ב-Winscope:

  1. במסך איסוף עקבות, לוחצים על שרת proxy ל-ADB:

    capture_traces_winscope

    איור 2. תיעוד עקבות ב-Winscope.

  2. מריצים את שרת ה-proxy של Winscope ADB Connect כדי לתעד עקבות ישירות מהדפדפן.

  3. מריצים את הפקודה:

    python3 $ANDROID_BUILD_TOP/development/tools/winscope/src/adb/winscope_proxy.py

  4. כדי להתחיל בצילום, במסך איסוף נתוני מעקב בוחרים את היעדים ואת ההגדרות האישיות ולוחצים על התחלת מעקב:

    collect_traces_winscope

    איור 3. איסוף עקבות ב-Winscope.

  5. כדי להפסיק את הצילום, לוחצים על סיום המעקב:

    end_trace_winscope

    איור 4. סיום המעקב ב-Winscope.

בזמן שהכלי מעלה את הטרייסים לממשק המשתמש של Winscope, ההודעות אחזור וניתוח קובצי Proto מופיעות במסך.

יצירת גרסת dump של המצב באמצעות Winscope

כדי ליצור תמונת מצב באמצעות Winscope, בוחרים בכרטיסייה Dump במסך Collect Traces ולוחצים על Dump state:

דאמפ-וויסקופ

איור 5. מצב ריקון ב-Winscope.

תיעוד נתוני מעקב באמצעות פקודות adb

מריצים את הפקודה adb root לפני שמריצים את הפקודות adb shell לכל אחד ממעקבי המעקב הבאים. בסוף המעקב, קובצי המעקב זמינים ב-/data/misc/wmtrace. במאמר העתקת קבצים למכשיר וממנו מוסבר איך מעתיקים קובץ או ספרייה ואת תיקיות המשנה שלהם ממכשיר. למידע נוסף, ראו adb.

נתוני מעקב של 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

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

מעקב מעבר

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

בתהליך 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 לצורך תיעוד. מידע נוסף על ההגדרות זמין במאמר הגדרת מעקב.

דוגמה:

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, נעשה שימוש במעקב 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 \

יצירת תמונת מצב באמצעות adb

Winscope קורא תמונת מצב של מצבי windowManager ו-SurfaceFlinger מדוחות באגים. דוחות איתור הבאגים מאחסנים את המצבים כקובצי Proto נפרדים בתוך התיקייה proto. כדי ליצור את קובצי ה-Dump של המצב באמצעות adb, מריצים את הפקודות הבאות.

ל-WindowManager:

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

ל-SurfaceFlinger:

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

ניתוח עקבות

כדי לנפות באגים במצבים זמניים ולא חוקיים שגורמים לבעיות באנימציה, Winscope צובר קובצי מעקב שונים, מספק חיפוש והמחשה במסגרות ובצירי זמן ומציגים הודעות Protobuf באופן קוהרנטי. ניתוח המעקב ב-Winscope עוזר לזהות את השכבה, המסגרת והמצב המדויקים של מופע הבאג.

שימוש ב-Winscope

אחרי שתיעדתם את המעקב, צריך לנתח את העקבות ב-Winscope:

  1. מעלים את נתוני המעקב השמורים באמצעות החלונית שמשמאל. תוכלו להסיר נתוני מעקב שהועלו או להעלות עוד נתוני מעקב.

    Upload_traces_winscope

    איור 6. העלאת עקבות ב-Winscope.

  2. לוחצים על הצגת נתוני המעקב כדי להציג באופן חזותי את נתוני המעקב שהועלו. הכרטיסיות של כל עקבות מופיעות בחלונית העליונה של החלון. אם הקובץ שהעליתם מכיל את הנתונים הרלוונטיים, תופיע במסך תצוגה צפה של הנתונים מההקלטה.

    view_traces_winscope

    איור 7. הצגת עקבות ב-Winscope.

    משתמשים בממשק המשתמש בחלונית העליונה של החלון כדי לשנות את השם של שם_עריכה ולהוריד את המעקב download_trace שהעליתם, או כדי להעלות מעקב חדש.

  3. כדי לנווט בנתוני המעקב לאורך זמן, משתמשים בכלי פס ההזזה של הזמן בחלונית התחתונה של החלון. כדי לנווט בזמן, אפשר להשתמש בתכונות הבאות, כפי שמוצג באיור 8:

    • כדי לנווט למועד או לאירוע מסוימים, משתמשים בסמן (פס ההזזה של הזמן), בחצים arrow_left_time שמאלה ו-חץ_ימינה_time ימינה בתיבה של תצוגת הזמן (בפינה השמאלית התחתונה) או בחצים ימינה ושמאלה במקלדת.
    • כדי להציג על ציר הזמן את הסימונים בצבע שנבחר, משתמשים בתפריט הנפתח (משמאל לפס ההזזה). כברירת מחדל, שלושת המעקבים האחרונים שנצפו באמצעות כרטיסיות המעקב מוצגים על ציר הזמן.
    • כדי לראות תצוגה מפורטת של כל הטרייסים שהועלו, משתמשים בכלי להגדלה Zoom_in_time או להקטנה Zoom_out_time (מתחת לפס ההזזה של הזמן), או גוללים במקלדת. השתמשו בלחצן האיפוס כדי לאפס את רמת הזום.
    • כדי להציג תצוגה מורחבת של חלוקת המעקב לאורך זמן, לוחצים על החץ למעלה arrow_up_time (בפינה השמאלית התחתונה).

    time_nav_winscope

    איור 8. ניווט בזמן ב-Winscope.

    בתצוגה המורחבת (איור 9), בוחרים מסגרות זמן מסוימות ומגדילים את התצוגה שלהן כדי לבדוק אותן טוב יותר:

    Extend_time_winscope

    איור 9. ציר הזמן מורחב ב-Winscope.

  4. כדי לבדוק את העקבות, אפשר לצפות במצב המכשיר באמצעות הקלטת המסך. כדי לבדוק מעקב מסוים, לוחצים על הכרטיסייה הרלוונטית של המעקב בחלונית העליונה של הכלי.

    • במעקב Surface Flinger, שלושה חלוניות מציגים תצוגות שונות של המעקב בתקופת זמן נתונה, כפי שמוצג באיור 10: sf_trace

      איור 10. משטח מעקב של Flinger ב-Winscope.

      • התצוגה שכבות: תצוגה תלת-ממדית של השכבות בשכבות-על מלבניות. רכיבי ממשק המשתמש הבאים משנים את המלבנים כדי להציג את הרכיבים הגרפיים לפי המיקום, הגודל, הטרנספורמציה והסדר ב-z:

        • פס ההזזה Rotation (בצד שמאל למעלה בתצוגת השכבות) מסובב את מלבנים השכבות כדי להציג אותם בזוויות שנבחרו.
        • פס ההזזה Spacing (בפינה הימנית העליונה של תצוגת השכבות) מכוונן את המרווח בין השכבות כדי ליצור את התצוגה המורכבת שנבחרה.
        • בעזרת כלי ההגדלה (בפינה השמאלית העליונה של תצוגת השכבות) אפשר להגדיל zoom_in_time ולהקטין zoom_out_time את התצוגה של השכבות כדי לבחון אותן טוב יותר.
        • לחצן האיפוס איפוס_sf (בפינה השמאלית העליונה של תצוגת השכבות) משחזר את הגדרות המצלמה לתצוגה המקורית.
        • כדי לשפר את מרחק התצוגה, גוררים את המלבנים.

      • תצוגה היררכית: היררכיה מלאה של השכבות.

        • רק גלויים (בפינה השמאלית העליונה של תצוגת ההיררכיה). כשהאפשרות הזו מסומנת, שכבות בלתי נראות מוסתרות מההיררכיה כדי לעזור לכם לראות את הרכיבים במסך.
        • אופקית (בפינה הימנית העליונה של התצוגה ההיררכית), אם בוחרים באפשרות הזו, מוצגת ההיררכיה כרשימה לא היררכית של שכבות.
        • האפשרות Show diff (בפינה השמאלית העליונה של התצוגה ההיררכית) מסומנת רק כשיש מעבר של מצב. כשבוחרים באפשרות הזו, הכלי משווה בין המצב הנוכחי למצב הקודם. רכיב חדש מודגש בירוק, רכיב שנמחק מודגש באדום ורכיב שהשתנה מודגש בכחול.

      • תצוגת Properties: המאפיינים של השכבה שנבחרה. בחלונית העליונה של התצוגה Properties מוצג מידע רק על מאפייני מפתח, כמו Visibility,‏ Geometry ו-Buffer. בחלונית התחתונה בתצוגה Properties (מאפיינים) מופיעה Proto Dump, בכל הנכסים.

        • תיבת הסימון Show Diff (בפינה השמאלית העליונה של התצוגה Properties) מוצגת כמו בתצוגה Hierarchy.
        • אם בוחרים באפשרות Show defaults (בפינה הימנית העליונה של תצוגת המאפיינים), ערכים ברירת המחדל של ה-proto יוצגו ב-Proto Dump. כברירת מחדל, הערכים האלה לא רשומים ב-Dump של Proto. ערכי ברירת המחדל של proto נלקחים מהגדרת השדה של proto. אם לא מוגדר בשדה proto ערך ברירת מחדל שאינו null, ערכי ברירת המחדל של ה-proto שמוצגים הם:
          • מחרוזות: Null
          • מספרים: 0
          • ערכים בוליאניים: False
          • אובייקטים: Null

      הבחירה בין שלוש התצוגות לבין הקלטת המסך מסונכרנת. כלומר, כל מעקבים מתעדכנים באופן סינכרוני כשמנווטים לנקודת זמן אחרת. כדי להציג את המאפיינים של שכבה, בוחרים את השכבה בלחיצה עליה בתצוגת ההיררכיה או בלחיצה על המלבן המתאים בתצוגת המאפיינים. מלבן סגול מציין שמעקב צפיות מצורף לשכבה הזו. לחיצה כפולה על שכבה סגולה תעביר את ממשק המשתמש לכרטיסייה הרלוונטית של מעקב אחר תצוגה.

    • בניתוח מנהל החלונות, שלושה לוחות מציגים תצוגות שונות של הניתוח בתקופה נתונה, כפי שמוצג באיור 11:

      • תצוגת Windows: תצוגה תלת-ממדית של השכבות.
      • תצוגה היררכית: היררכיה מלאה של השכבות.
      • התצוגה מאפיינים מכילה Dump של פרוטו מכל הנכסים.

      הבחירה בין שלוש התצוגות לבין הקלטת המסך מסונכרנת. כלומר, כל מעקבים מתעדכנים באופן סינכרוני כשמנווטים לנקודת זמן אחרת.

      wm_trace

      איור 11. מעקב אחר מנהל החלונות ב-Winscope.

    • במעקבים של Transactions, העסקאות בין Surface Flinger לבין Window Manager מוצגות בפורמט טבלה שניתן לחפש בו לפי המזהים, הסוג והטקסט שמוצגים, יחד עם תצוגת מאפיינים שמציגה את גרסת ה-proto dump. הבחירה בין שתי התצוגות והקלטת המסך מסונכרנות:

      transaction_trace

      איור 12. מעקב אחר עסקאות ב-Winscope.

    • במעקבי ProtoLog, המידע מוצג בפורמט של טבלה שאפשר לחפש לפי תגים, קובצי מקור וטקסט:

      מעקב_protolog

      איור 13. מעקב ProtoLog ב-Winscope.

    • במעקבים של Transitions מוצגת רשימה של מעברים עם המזהה, הסוג, מועד השליחה, משך הזמן והסטטוס, יחד עם המאפיינים של המעבר שנבחר:

      מעברים_מעקב

      איור 14. מעקב אחר מעברים ב-Winscope.