ארגומנטים של מכשירי המדידה של Macrobenchmark

מגדירים את התנהגות הספרייה באמצעות הארגומנטים הבאים של מכשירי המדידה. אפשר להוסיף אותם להגדרות של Gradle או להחיל אותם ישירות כשמריצים את המדידה בשורת הפקודה. כדי להגדיר את הארגומנטים האלה לכל הרצות הבדיקה ב-Android Studio ובשורת הפקודה, מוסיפים אותם לקובץ testInstrumentationRunnerArguments:

android {
    defaultConfig {
        // ...
        testInstrumentationRunnerArguments["androidx.benchmark.dryRunMode.enable"] = "true"
    }
}

אפשר גם להגדיר ארגומנטים של מכשירי מדידה כשמריצים את מדדי הביצועים מ-Android Studio. כדי לשנות את הארגומנטים:

אם מריצים את הבדיקה ברמת המאקרו משורת הפקודה, משתמשים ב--P android.testInstrumentationRunnerArguments.[name of the argument]:

./gradlew :benchmark:connectedAndroidTest -P android.testInstrumentationRunnerArguments.androidx.benchmark.enabledRules=BaselineProfile

אם מפעילים את הפקודה am instrument ישירות (כפי שעשוי לקרות בסביבות בדיקה של CI), מעבירים את הארגומנט ל-am instrument באמצעות -e:

adb shell am instrument -e androidx.benchmark.enabledRules BaselineProfile -w com.example.macrobenchmark/androidx.test.runner.AndroidJUnitRunner

מידע נוסף על הגדרת מדדי ביצועים ב-CI זמין במאמר השוואה לשוק ב-CI

androidx.benchmark.compilation.enabled

מאפשרת להשבית את הידור הקוד בין כל חזרה על מדד הביצועים. כברירת מחדל, האפליקציה היעד מותקנת מחדש ומקובלת מחדש בין כל בדיקת ביצועים, כדי לפעול בהתאם ל-CompilationMode שהועברה אל measureRepeated. השבתת האפשרות הזו מאפשרת לדלג על ההתקנה מחדש ועל הידור, אם, לדוגמה, רוצים להדר את אפליקציית היעד באופן מלא פעם אחת לפני שמריצים את חבילת הבדיקות, ולהריץ את כל מדדי הביצועים מול היעד המהודר במלואו.

• סוג הארגומנט: בוליאני
• ברירת המחדל היא: true

androidx.benchmark.dryRunMode.enable

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

• סוג הארגומנט: בוליאני
• ברירת המחדל היא: false

androidx.benchmark.enabledRules

מאפשר סינון של הפעלות לפי סוג בדיקה אחד בלבד: יצירת פרופיל בסיס או בדיקת Macrobenchmark. יש תמיכה גם ברשימות מופרדות בפסיקים.

• סוג הארגומנט: מחרוזת
• האפשרויות הזמינות:
  • Macrobenchmark
  • BaselineProfile
• ברירת המחדל: לא צוין

androidx.benchmark.junit4.SideEffectRunListener

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

כדי להשבית את העבודה ברקע במהלך בדיקת הביצועים, מגדירים את listener סוג הארגומנט של המדידה לandroidx.benchmark.junit4.SideEffectRunListener.

• סוג הארגומנט: מחרוזת
• האפשרויות הזמינות:
  • androidx.benchmark.junit4.SideEffectRunListener
• ברירת המחדל: לא צוין

androidx.benchmark.fullTracing.enable

הפעלת נקודות מעקב (tracepoints) של androidx.tracing.perfetto, כמו מעקב אחר קומפוזיציה ב-Jetpack Compose.

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

• סוג הארגומנט: boolean
• ברירת המחדל היא: false

androidx.benchmark.profiling.mode

מאפשרת לתעד קובצי מעקב בזמן הרצת מדדי הביצועים. האפשרויות הזמינות זהות לאלה של ספריית Microbenchmark. למידע נוסף, ראו את התיאורים במאמר יצירת פרופיל של Microbenchmark.

• סוג הארגומנט: מחרוזת
• האפשרויות הזמינות:
  • MethodTracing
  • StackSampling
  • None
• ברירת המחדל היא: None

androidx.benchmark.startupProfiles.enable

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

• סוג הארגומנט: boolean
• ברירת המחדל היא: true

androidx.benchmark.suppressErrors

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

• סוג הארגומנט: רשימה של מחרוזות

• האפשרויות הזמינות:

  • DEBUGGABLE

    השגיאה DEBUGGABLE מציינת שחבילת היעד פועלת עם debuggable=true במניפסט שלה, מה שמפחית באופן משמעותי את הביצועים בסביבת זמן הריצה כדי לתמוך בתכונות ניפוי הבאגים. כדי להימנע מהשגיאה הזו, צריך להריץ את מדדי הביצועים עם debuggable=false. הארגומנט לניתוח באגים משפיע על מהירות הביצועים, כך ששיפורים בביצועי הסימון עשויים לא לעבור לחוויית המשתמש בפועל, או לגרום לירידה בביצועי הגרסה המשוחררת.

  • LOW-BATTERY

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

  • EMULATOR

    השגיאה EMULATOR מציינת שהבדיקה מבוצעת במהדורת הדמיה (emulator), שלא מייצגת את המכשירים של המשתמשים האמיתיים. יכול להיות ששיפורים בביצועים של מעבדים להשוואה (benchmark) במהלך הדמיה לא יועברו לחוויית המשתמש האמיתית, או שהם עלולים לגרום לירידה בביצועים של המכשיר האמיתי. במקום זאת, כדאי להשתמש במכשיר פיזי לבדיקת הביצועים. יש להסתיר את השגיאה הזו בזהירות רבה.

  • NOT-PROFILEABLE

    חבילת היעד $packageName פועלת ללא <profileable shell=true>. כדי לאפשר ל-Macrobenchmark לתעד פרטי מעקב מפורטים מתהליך היעד, כמו קטעי מעקב מערכת שהוגדרו באפליקציה או בספריות, צריך להפעיל את האפשרות Profileable ב-Android 10 וב-Android 11. יש להשתמש באפשרות הזו בזהירות רבה.

  • METHOD-TRACING-ENABLED

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

• ברירת המחדל: רשימה ריקה

additionalTestOutputDir

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

• סוג הארגומנט: מחרוזת נתיב
• ברירת המחדל: הספרייה החיצונית של קובץ ה-APK לבדיקה