יצירת פרופילים מבוססת-טריגר

ב-Android 16 (רמת API‏ 36) ומעלה, ProfilingManager מאפשר לתעד פרופילים באופן אוטומטי בתגובה לטריגרים של המערכת, כמו שגיאות מסוג האפליקציה לא מגיבה (ANR), קריסות בגלל אין זיכרון פנוי (OutOfMemoryError) או אירועים של הפעלת האפליקציה. בגלל שאי אפשר לחזות מתי יתרחשו הרבה מהאירועים האלה בשטח, לא מעשי להתחיל הקלטה באופן ידני מראש. כשמשתמשים בפרופיילינג מבוסס-טריגרים, המערכת מנהלת את תיעוד הנתונים ומעבירה את הפרופיל שנוצר לאפליקציה, כדי שתוכלו:

  • ניפוי באגים בבעיות שקשורות ליציבות: אבחון של מקרי ANR בלתי צפויים ודליפות זיכרון.
  • אופטימיזציה של חוויות שימוש הכרחיות (CUJ): ניתוח תהליכים כמו הפעלת האפליקציה (TRIGGER_TYPE_COLD_START ו-TRIGGER_TYPE_APP_FULLY_DRAWN).
  • להבין את התנהגות המשתמשים: לבדוק אירועים כמו יציאה מהאפליקציה ביוזמת המשתמש.

הרשימה המלאה של הטריגרים הזמינים מופיעה במאמר ProfilingTrigger.

סוגי טריגרים

הטריגרים שונים באופן שבו המערכת מתעדת את הפרופיל כשהאירוע מתרחש.

טריגרים שמשתמשים במעקב ברקע

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

טריגרים שמתחילים צילום חדש

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

טריגרים שבהם התנהגות הצילום משתנה בהתאם לאנומליה

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

הגדרת טריגר

הקוד הבא מדגים איך להירשם לטריגר TRIGGER_TYPE_APP_FULLY_DRAWN ולהגדיר לו תקופת צינון.

Kotlin

@RequiresApi(Build.VERSION_CODES.BAKLAVA)
fun recordWithTrigger() {
    val profilingManager =
        applicationContext.getSystemService(ProfilingManager::class.java) ?: return

    val triggers = ArrayList<ProfilingTrigger>()

    val triggerBuilder = ProfilingTrigger.Builder(ProfilingTrigger.TRIGGER_TYPE_APP_FULLY_DRAWN)
        .setRateLimitingPeriodHours(1)

    triggers.add(triggerBuilder.build())

    val callbackExecutor: Executor = Executors.newSingleThreadExecutor()

    val resultCallback = Consumer<ProfilingResult> { profilingResult ->
        if (profilingResult.errorCode == ProfilingResult.ERROR_NONE) {
            Log.d(
                "ProfileTest",
                "Received profiling result file=" + profilingResult.resultFilePath
            )
            setupProfileUploadWorker(profilingResult.resultFilePath)
        } else {
            Log.e(
                "ProfileTest",
                "Profiling failed errorcode=" + profilingResult.errorCode + " errormsg=" + profilingResult.errorMessage
            )
        }
    }

    profilingManager.registerForAllProfilingResults(callbackExecutor, resultCallback)
    profilingManager.addProfilingTriggers(triggers)

    Choreographer.getInstance().postFrameCallback { frameTimeNanos ->
        // This will cause the TRIGGER_TYPE_APP_FULLY_DRAWN to be emitted.
        reportFullyDrawn()
    }
}

Java

public void recordWithTrigger() {
  ProfilingManager profilingManager = getApplicationContext().getSystemService(
      ProfilingManager.class);
  List<ProfilingTrigger> triggers = new ArrayList<>();
  ProfilingTrigger.Builder triggerBuilder = new ProfilingTrigger.Builder(
      ProfilingTrigger.TRIGGER_TYPE_APP_FULLY_DRAWN);
  triggerBuilder.setRateLimitingPeriodHours(1);
  triggers.add(triggerBuilder.build());

  Executor callbackExecutor = Executors.newSingleThreadExecutor();
  Consumer<ProfilingResult> resultCallback =
      new Consumer<ProfilingResult>() {
        @Override
        public void accept(ProfilingResult profilingResult) {
          if (profilingResult.getErrorCode() == ProfilingResult.ERROR_NONE) {
            Log.d(
                "ProfileTest",
                "Received profiling result file=" + profilingResult.getResultFilePath());
            setupProfileUploadWorker(profilingResult.getResultFilePath());
          } else {
            Log.e(
                "ProfileTest",
                "Profiling failed errorcode="
                    + profilingResult.getErrorCode()
                    + " errormsg="
                    + profilingResult.getErrorMessage());
          }
        }
      };
  profilingManager.registerForAllProfilingResults(callbackExecutor, resultCallback);
  profilingManager.addProfilingTriggers(triggers);

  Choreographer.getInstance().postFrameCallback((f) -> {
    // This will cause the TRIGGER_TYPE_APP_FULLY_DRAWN to be emitted.
    reportFullyDrawn();
  });
}

הקוד מבצע את השלבים הבאים:

  1. Get the manager: אחזור של השירות ProfilingManager.
  2. הגדרת טריגר: יצירת ProfilingTrigger ל-TRIGGER_TYPE_APP_FULLY_DRAWN. האירוע הזה מתרחש כשהאפליקציה קוראת ל-reportFullyDrawn() במהלך הפעלה קרה שמתחילה מפעילות, כדי לדווח שהיא סיימה את ההפעלה והיא אינטראקטיבית.
  3. הגדרת תקופת צינון לטריגר: הגדרת תקופת צינון של שעה לטריגר הספציפי הזה באמצעות setRateLimitingPeriodHours, בנוסף למגבלת הקצב של המערכת. תקופת הצינון הזו מונעת מהאפליקציה לתעד יותר מפרופיל הפעלה אחד בשעה.
  4. רישום מאזין: קריאה ל-registerForAllProfilingResults כדי להגדיר את הקריאה החוזרת (callback) שמטפלת בתוצאה. הקריאה החוזרת הזו מקבלת את הנתיב של הפרופיל השמור דרך getResultFilePath().
  5. ‫Add triggers: רישום רשימת הטריגרים ב-ProfilingManager באמצעות addProfilingTriggers.
  6. הפעלת אירוע: מפרסמת קריאה חוזרת (callback) של פריים ב-Choreographer שקוראת ל-reportFullyDrawn() אחרי שהפריים הבא משורטט, מה ששולח את האירוע TRIGGER_TYPE_APP_FULLY_DRAWN למערכת ומפעיל איסוף פרופילים, בהנחה שמעקב ברקע של המערכת פועל ויש מכסה זמינה להגבלת קצב של יצירת בקשות. כדי שהטריגר הזה יופעל, צריך לוודא שהאפליקציה קוראת ל-reportFullyDrawn().

מחזור החיים של הטריגר

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

מתי לבטל את הרישום של טריגרים

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

צריך לבטל את הרישום של טריגרים במצבים הבאים:

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

מחזור החיים של קריאה חוזרת (callback)

בניגוד לבקשות פרופיילינג ישירות, פרופילים שמבוססים על טריגרים מספקים תוצאות רק למאזין גלובלי שרשום ב-registerForAllProfilingResults. ב-callback, מפעילים את ProfilingResult.getTriggerType כדי לזהות איזה טריגר הפעיל את התיעוד, ומפעילים את ProfilingResult.getResultFilePath כדי לאתר את קובץ הפרופיל שנשמר. לפרטים על שמות הקבצים של פרופילי הטריגרים, שליפת קבצים באמצעות adb והעלאת התוצאות ברקע, קראו את המאמר אחזור והעלאה של פרופילים.

הטריגרים נשמרים גם אחרי הפעלה מחדש של האפליקציה או של המערכת, אבל הקריאה החוזרת (callback) של התוצאה לא נשמרת. כדי לקבל פרופילים בשני התרחישים הבאים, צריך לרשום את הקריאה החוזרת (callback) ב-Executor ברקע אחרי שהאפליקציה מסיימת את ההפעלה (כדי לא להאט את ההפעלה הקרה):

  • בזמן שהאפליקציה פועלת: אם הטריגרים לא עוצרים את האפליקציה או גורמים לה לקרוס, המערכת מפעילה את פונקציית ה-callback ב-Executor שצוין כשהטריגר מתרחש והפרופיל נשמר.
  • אחרי סגירת האפליקציה: אם הטריגרים קשורים לסגירת האפליקציה או קודמים לה (כמו TRIGGER_TYPE_ANR,‏ TRIGGER_TYPE_OOM או TRIGGER_TYPE_KILL_RECENTS), או אם האפליקציה נסגרת לפני שהתיעוד מסתיים, המערכת שומרת את הפרופיל ברקע ומעבירה את התוצאה לתור אחרי הפעלה מחדש של האפליקציה או של המערכת. המערכת שומרת תוצאות בתור שלא נמסרו עד 7 ימים, ומעבירה אותן בפעם הבאה שהאפליקציה פועלת וקוראת ל-registerForAllProfilingResults.

איך פועל מעקב ברקע

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

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

תרשים שמראה איך פועלים קובצי ה-snapshot של המעקב ברקע, עם מאגר נתונים זמני (ring buffer) שמתעד נתונים לפני אירוע טריגר.
איור 1. איך פועלים תמונות מצב של מעקב ברקע.

הגדרת תקופת צינון ספציפית לטריגר

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

ניפוי באגים של טריגרים באופן מקומי

מכיוון שמעקבי רקע פועלים במרווחי זמן אקראיים בסביבת הייצור, כדי לבדוק טריגרים באופן מקומי צריך לאלץ מעקב רקע רציף ולעקוף את מגבלת הקצב ברמת המערכת של החבילה (כל תקופת צינון לכל טריגר שמוגדרת באמצעות setRateLimitingPeriodHours עדיין חלה, ו-rate_limiter.disabled חל רק על קריאות requestProfiling שמופעלות על ידי האפליקציה).

כדי להפעיל את פקודות adb שמאלצות מעקב ברקע, מדמות טריגרים משורת הפקודה ובודקות את מצב השירות, קראו את הקטע אילוץ הפעלה של מעקב ברקע לבדיקת טריגרים במאמר פקודות ניפוי באגים לפרופיילינג מקומי.