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

מגדירים את ההתנהגות של הספרייה באמצעות ארגומנטים של מכשור (instrumentation) מהסוגים הבאים. אפשר להוסיף אותם להגדרות של 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
  • BaselineProfile
• ברירת מחדל: לא צוין

androidx.benchmark.fullTracing.enable

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

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

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

androidx.benchmark.killExistingPerfettoRecordings

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

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

androidx.benchmark.profiling.mode

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

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

androidx.benchmark.startupProfiles.enable

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

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

androidx.benchmark.suppressErrors

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

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

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

  • DEBUGGABLE

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

  • LOW-BATTERY

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

  • EMULATOR

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

  • NOT-PROFILEABLE

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

  • METHOD-TRACING-ENABLED

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

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

additionalTestOutputDir

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

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

listener

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

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

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