كتابة معيار ماكرو

استخدِم مكتبة Macrobenchmark لاختبار حالات الاستخدام الأكبر لتطبيقك، بما في ذلك بدء تشغيل التطبيق وعمليات معالجة واجهة المستخدم المعقّدة، مثل التمرير السريع في RecyclerView أو تشغيل الرسوم المتحركة. إذا كنت تريد اختبار أجزاء أصغر من الرمز، يمكنك الرجوع إلى مكتبة Microbenchmark. توضّح هذه الصفحة كيفية إعداد مكتبة Macrobenchmark.

تعرض المكتبة نتائج قياس الأداء في كلّ من وحدة تحكّم "استوديو Android" وملف JSON يتضمّن تفاصيل أكثر. ويوفّر أيضًا ملفات تتبُّع يمكنك تحميلها وتحليلها في Android Studio.

استخدِم مكتبة Macrobenchmark في بيئة دمج مستمر (CI)، كما هو موضّح في مقالة قياس الأداء في عملية الدمج المستمر.

يمكنك استخدام Macrobenchmark لإنشاء "ملفات تعريف خط الأساس". عليك أولاً إعداد مكتبة Macrobenchmark، وبعد ذلك يمكنك إنشاء ملف Baseline Profile.

إعداد المشروع

ننصحك باستخدام Macrobenchmark مع أحدث إصدار من Android Studio للاستفادة من ميزات بيئة التطوير المتكاملة التي تتوافق مع Macrobenchmark.

إعداد وحدة Macrobenchmark

تتطلّب اختبارات Macrobenchmark توفُّر وحدة com.android.test نموذجية منفصلة عن رمز تطبيقك، وهي المسؤولة عن تنفيذ الاختبارات التي تقيس أداء تطبيقك.

في "استوديو Android"، يتوفّر نموذج لتبسيط عملية إعداد وحدة Macrobenchmark. ينشئ نموذج وحدة قياس الأداء تلقائيًا وحدة في مشروعك لقياس أداء التطبيق الذي تم إنشاؤه بواسطة وحدة تطبيق، بما في ذلك نموذج لقياس أداء بدء التشغيل.

لاستخدام نموذج الوحدة لإنشاء وحدة جديدة، اتّبِع الخطوات التالية:

  1. انقر بزر الماوس الأيمن على مشروعك أو وحدتك في لوحة المشروع في "استوديو Android"، ثم اختَر جديد > وحدة.

  2. انقر على مقياس الأداء من لوحة النماذج. يمكنك تخصيص التطبيق المستهدَف، أي التطبيق الذي سيتم قياس أدائه، بالإضافة إلى اسم الحزمة والوحدة النمطية لوحدة Macrobenchmark الجديدة.

  3. انقر على إنهاء.

نموذج وحدة مقياس الأداء

الشكل 1. نموذج وحدة مقياس الأداء

إعداد التطبيق

لتقييم أداء تطبيق، يُعرف باسم التطبيق المستهدَف في Macrobenchmark، يجب أن يكون التطبيق profileable، ما يتيح قراءة معلومات التتبُّع التفصيلية بدون التأثير في الأداء. يضيف معالج الوحدات العلامة <profileable> تلقائيًا إلى ملف AndroidManifest.xml الخاص بالتطبيق.

تأكَّد من أنّ التطبيق المستهدَف يتضمّن الإصدار ProfilerInstaller 1.3 أو الإصدارات الأحدث، وهو الإصدار الذي تحتاج إليه مكتبة Macrobenchmark لتفعيل عملية تسجيل الملفات الشخصية وإعادة الضبط ومحو ذاكرة التخزين المؤقت للتظليل.

اضبط إعدادات التطبيق الذي يتم قياس أدائه على أن تكون مشابهة قدر الإمكان لإعدادات الإصدار العلني أو الإصدار المتاح على المتجر. اضبطه على أنّه غير قابل للتصحيح، ومن الأفضل تفعيل تصغير الحجم، ما يؤدي إلى تحسين الأداء. ويتم ذلك عادةً من خلال إنشاء نسخة من صيغة الإصدار، التي تنفّذ الإجراءات نفسها، ولكن يتم توقيعها محليًا باستخدام مفاتيح تصحيح الأخطاء. بدلاً من ذلك، يمكنك استخدام initWith لتوجيه Gradle بتنفيذ ذلك نيابةً عنك:

Kotlin

buildTypes {
    getByName("release") {
        isMinifyEnabled = true
        isShrinkResources = true
        proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"))
    }

    create("benchmark") {
        initWith(getByName("release"))
        signingConfig = signingConfigs.getByName("debug")
    }
}

Groovy

buildTypes {
    getByName("release") {
        isMinifyEnabled = true
        isShrinkResources = true
        proguardFiles(
            getDefaultProguardFile("proguard-android-optimize.txt"),
            "proguard-rules.pro"
        )
        // In real app, this would use its own release keystore
        signingConfig = signingConfigs.getByName("debug")
    }
}
build.gradle.kts

للمساعدة في ضمان أنّ تشغيل مقياس الأداء يؤدي إلى إنشاء واختبار الإصدار الصحيح من تطبيقك، كما هو موضّح في الشكل 2، اتّبِع الخطوات التالية:

  1. نفِّذ عملية مزامنة Gradle.
  2. افتح لوحة إنشاء صيغ.
  3. اختَر صيغة مقياس الأداء لكلّ من التطبيق ووحدة Macrobenchmark.

اختيار صيغة مقياس الأداء

الشكل 2. اختَر صيغة مقياس الأداء.

(اختياري) إعداد تطبيق متعدد الوحدات

إذا كان تطبيقك يتضمّن أكثر من وحدة Gradle، تأكَّد من أنّ نصوص البرامج الإنشائية تعرف نوع الإصدار الذي يجب تجميعه. أضِف السمةmatchingFallbacks إلى نوع الإصدار benchmark في الوحدتَين :macrobenchmark و:app. يمكن أن تتضمّن بقية وحدات Gradle الإعدادات نفسها كما كان من قبل.

Kotlin

create("benchmark") {
    initWith(getByName("release"))
    signingConfig = signingConfigs.getByName("debug")

    matchingFallbacks += listOf("release")
 }

Groovy

benchmark {
    initWith buildTypes.release
    signingConfig signingConfigs.debug

    matchingFallbacks = ['release']
 }

بدون ذلك، سيؤدي نوع الإصدار benchmark الذي تمت إضافته حديثًا إلى تعذُّر إنشاء الإصدار وستظهر رسالة الخطأ التالية:

> Could not resolve project :shared.
     Required by:
         project :app
      > No matching variant of project :shared was found.
      ...

عند اختيار صيغ الإنشاء في مشروعك، اختَر benchmark للوحدتَين :app و:macrobenchmark، وrelease لأي وحدات أخرى في تطبيقك، كما هو موضّح في الشكل 3:

المتغيرات المرجعية لمشروع متعدد الوحدات مع تحديد أنواع الإصدارات والمقاييس المرجعية

الشكل 3. متغيرات قياس الأداء لمشروع متعدد الوحدات مع تحديد نوعَي الإصدار والبنية الخاصة بقياس الأداء

لمزيد من المعلومات، راجِع مقالة استخدام إدارة التبعيات المتوافقة مع الأنواع.

(اختياري) إعداد نُسخ المنتج

إذا كان لديك عدة إصدارات من المنتج في تطبيقك، عليك ضبط :macrobenchmarkالوحدة النمطية لكي تعرف إصدار المنتج الذي يجب إنشاؤه وقياس أدائه.

تستخدِم الأمثلة الواردة في هذه الصفحة نوعَي المنتج في الوحدة :app: demo وproduction، كما هو موضّح في المقتطف التالي:

Kotlin

flavorDimensions += "environment"
productFlavors {
    create("demo") {
        dimension = "environment"
        // ...
    }
    create("production") {
        dimension = "environment"
        // ...
    }
}

Groovy

flavorDimensions 'environment'
productFlavors {
    demo {
        dimension 'environment'
        // ...
    }

    production {
        dimension 'environment'
        // ...
    }
}

بدون عملية الضبط هذه، قد يظهر لك خطأ في الإنشاء مشابه لما يحدث عند استخدام وحدات Gradle متعددة:

Could not determine the dependencies of task ':macrobenchmark:connectedBenchmarkAndroidTest'.
> Could not determine the dependencies of null.
   > Could not resolve all task dependencies for configuration ':macrobenchmark:benchmarkTestedApks'.
      > Could not resolve project :app.
        Required by:
            project :macrobenchmark
         > The consumer was configured to find a runtime of a component, as well as attribute 'com.android.build.api.attributes.BuildTypeAttr' with value 'benchmark', attribute 'com.android.build.api.attributes.AgpVersionAttr' with value '7.3.0'. However we cannot choose between the following variants of project :app:
             -   demoBenchmarkRuntimeElements
             -   productionBenchmarkRuntimeElements
           All of them match the consumer attributes:
           ...

يوضّح القسمان التاليان طريقتَين لإعداد قياس الأداء باستخدام عدة نكهات منتج.

استخدام missingDimensionStrategy

يؤدي تحديد missingDimensionStrategy في defaultConfig ضمن وحدة :macrobenchmark إلى توجيه نظام الإنشاء لاستخدام سمة نوع المنتج الاحتياطية. حدِّد السمات التي تريد استخدامها إذا لم تعثر عليها في الوحدة. في المثال التالي، يتم استخدام نكهة production كالسِمة التلقائية:

Kotlin

defaultConfig {
    missingDimensionStrategy("environment", "production")
}

Groovy

defaultConfig {
    missingDimensionStrategy "environment", "production"
}

بهذه الطريقة، يمكن لوحدة :macrobenchmark إنشاء مقياس أداء لنوع المنتج المحدّد فقط، وهو أمر مفيد إذا كنت تعلم أنّ نوع منتج واحد فقط يتضمّن الإعداد المناسب لقياس الأداء.

تحديد متغيرات المنتج في وحدة :macrobenchmark

إذا أردت إنشاء نُسخ أخرى من المنتج وقياس أدائها، عليك تحديدها في وحدة :macrobenchmark. حدِّدها بشكل مشابه لما هو وارد في الوحدة :app، ولكن لا تُسنِد سوى productFlavors إلى dimension. لا يلزم ضبط أي إعدادات أخرى:

Kotlin

flavorDimensions += "environment"
productFlavors {
    create("demo") {
        dimension = "environment"
    }
    create("production") {
        dimension = "environment"
    }
}

Groovy

flavorDimensions 'environment'
productFlavors {
    demo {
        dimension 'environment'
    }

    production {
        dimension 'environment'
    }
}

بعد تحديد المشروع ومزامنته، اختَر صيغة البناء المناسبة من لوحة صيغ البناء، كما هو موضّح في الشكل 4:

إعدادات المقارنة للمشروع الذي يتضمّن نكهات منتجات تعرض productionBenchmark وrelease المحدّدة

الشكل 4. إصدارات تجريبية للمشروع مع نُسخ من المنتج تعرض "productionBenchmark" و "release" المحدّدين

لمزيد من المعلومات، راجِع مقالة حلّ أخطاء الإنشاء المتعلّقة بمطابقة الصيغ.

إنشاء فئة اختبار قياس الأداء الشامل

يتم توفير اختبارات قياس الأداء من خلال واجهة برمجة التطبيقات MacrobenchmarkRule JUnit4 rule في مكتبة Macrobenchmark. يحتوي على طريقة measureRepeated تتيح لك تحديد شروط مختلفة حول كيفية تشغيل التطبيق المستهدَف وقياس أدائه.

يجب على الأقل تحديد packageName للتطبيق المستهدف، وmetrics التي تريد قياسها، وعدد iterations التي يجب أن يتم تشغيل مقياس الأداء.

Kotlin

@LargeTest
@RunWith(AndroidJUnit4::class)
class SampleStartupBenchmark {
    @get:Rule
    val benchmarkRule = MacrobenchmarkRule()

    @Test
    fun startup() = benchmarkRule.measureRepeated(
        packageName = TARGET_PACKAGE,
        metrics = listOf(StartupTimingMetric()),
        iterations = DEFAULT_ITERATIONS,
        setupBlock = {
            // Press home button before each run to ensure the starting activity isn't visible.
            pressHome()
        }
    ) {
        // starts default launch activity
        startActivityAndWait()
    }
}
SampleStartupBenchmark.kt

Java

@LargeTest
@RunWith(AndroidJUnit4.class)
public class SampleStartupBenchmark {
    @Rule
    public MacrobenchmarkRule benchmarkRule = new MacrobenchmarkRule();

    @Test
    public void startup() {
        benchmarkRule.measureRepeated(
            /* packageName */ TARGET_PACKAGE,
            /* metrics */ Arrays.asList(new StartupTimingMetric()),
            /* iterations */ 5,
            /* measureBlock */ scope -> {
                // starts default launch activity
                scope.startActivityAndWait();
                return Unit.INSTANCE;
            }
        );
    }
}

للاطّلاع على جميع خيارات تخصيص مقياس الأداء، راجِع قسم تخصيص مقاييس الأداء.

تشغيل مقياس الأداء

.

يمكنك إجراء الاختبار من داخل "استوديو Android" لقياس أداء تطبيقك على جهازك. يمكنك تشغيل مقاييس الأداء بالطريقة نفسها التي تشغّل بها أي @Test أخرى باستخدام إجراء الهامش بجانب فئة الاختبار أو الطريقة، كما هو موضّح في الشكل 5.

تشغيل اختبار الأداء الشامل باستخدام إجراء في الهامش بجانب فئة الاختبار

الشكل 5. تشغيل Macrobenchmark باستخدام إجراء في الهامش بجانب فئة الاختبار

يمكنك أيضًا تشغيل جميع مقاييس الأداء في وحدة Gradle من سطر الأوامر من خلال تنفيذ الأمر connectedCheck:

./gradlew :macrobenchmark:connectedCheck

يمكنك إجراء اختبار واحد من خلال تنفيذ ما يلي:

./gradlew :macrobenchmark:connectedCheck -P android.testInstrumentationRunnerArguments.class=com.example.macrobenchmark.startup.SampleStartupBenchmark#startup

راجِع مقالة قياس الأداء في التكامل المستمر للحصول على معلومات حول كيفية تنفيذ مقاييس الأداء ومراقبتها في التكامل المستمر.

نتائج قياس الأداء

بعد إجراء اختبار الأداء بنجاح، يتم عرض المقاييس مباشرةً في &quot;استوديو Android&quot;، ويتم إخراجها لاستخدامها في الدمج المتواصل في ملف JSON. تسجّل كل تكرار تم قياسه عملية تتبُّع منفصلة للنظام. يمكنك فتح نتائج التتبُّع هذه من خلال النقر على الروابط في جزء نتائج الاختبار، كما هو موضّح في الشكل 6:

نتائج بدء تشغيل Macrobenchmark

الشكل 6. نتائج بدء تشغيل Macrobenchmark

عند تحميل التتبُّع، يطلب منك &quot;استوديو Android&quot; اختيار العملية التي تريد تحليلها. يتم ملء الاختيار مسبقًا بعملية التطبيق المستهدَف، كما هو موضّح في الشكل 7:

اختيار عملية تتبُّع الأخطاء في &quot;استوديو Android&quot;

الشكل 7. اختيار عملية تتبُّع في "استوديو YouTube"

بعد تحميل ملف التتبُّع، يعرض "استوديو Android" النتائج في أداة تحليل استخدام وحدة المعالجة المركزية:

Studio Trace

الشكل 8. تتبُّع الأخطاء في "استوديو YouTube"

يتم أيضًا نسخ تقارير JSON وأي آثار لتحديد المشاكل تلقائيًا من الجهاز إلى المضيف. تتم كتابة هذه السجلّات على الجهاز المضيف في الموقع التالي:

project_root/module/build/outputs/connected_android_test_additional_output/debugAndroidTest/connected/device_id/

الوصول إلى ملفات التتبُّع يدويًا

إذا أردت استخدام أداة Perfetto لتحليل ملف تتبُّع، عليك اتّباع خطوات إضافية. يتيح لك Perfetto فحص جميع العمليات التي تحدث على الجهاز أثناء عملية التتبُّع، بينما يقتصر فحص أداة تحليل استخدام وحدة المعالجة المركزية في Android Studio على عملية واحدة.

إذا استدعيت الاختبارات من &quot;استوديو Android&quot; أو من سطر أوامر Gradle، سيتم تلقائيًا نسخ ملفات التتبُّع من الجهاز إلى المضيف. يتم حفظها على الجهاز المضيف في الموقع التالي:

project_root/module/build/outputs/connected_android_test_additional_output/debugAndroidTest/connected/device_id/TrivialStartupBenchmark_startup[mode=COLD]_iter002.perfetto-trace

بعد الحصول على ملف التتبُّع في نظام التشغيل المضيف، يمكنك فتحه في &quot;استوديو Android&quot; من خلال النقر على ملف > فتح في القائمة. تعرض هذه السمة طريقة عرض أداة Profiler الموضّحة في القسم السابق.

أخطاء في الإعدادات

في حال إعداد التطبيق بشكل غير صحيح، أي يمكن تصحيحه أو لا يمكن إنشاء ملف تعريف له، تعرض مكتبة Macrobenchmark رسالة خطأ بدلاً من عرض قياس غير صحيح أو غير مكتمل. يمكنك إخفاء هذه الأخطاء باستخدام الوسيطة androidx.benchmark.suppressErrors.

تعرض Macrobenchmark أيضًا أخطاء عند محاولة قياس أداء محاكي أو جهاز منخفض البطارية، ما قد يؤدي إلى التأثير في مدى توفّر النواة وسرعة الساعة.

تخصيص مقاييس الأداء

تقبل الدالة measureRepeated مَعلمات مختلفة تؤثّر في المقاييس التي تجمعها المكتبة، أو طريقة بدء تطبيقك وتجميعه، أو عدد التكرارات التي يتم تنفيذ قياس الأداء بها.

تسجيل المقاييس

المقاييس هي النوع الرئيسي من المعلومات المستخرَجة من مقاييس الأداء. تتوفّر المقاييس التالية:

لمزيد من المعلومات عن المقاييس، راجِع تسجيل مقاييس Macrobenchmark.

تحسين بيانات التتبُّع باستخدام الأحداث المخصّصة

قد يكون من المفيد تزويد تطبيقك بأحداث تتبُّع مخصّصة تظهر مع بقية تقرير التتبُّع ويمكن أن تساعد في تحديد المشاكل الخاصة بتطبيقك. لمزيد من المعلومات عن إنشاء أحداث تتبُّع مخصّصة، اطّلِع على تحديد الأحداث المخصّصة.

CompilationMode

يمكن أن تحدّد اختبارات الأداء الشامل CompilationMode، الذي يحدّد مقدار التطبيق الذي يجب تجميعه مسبقًا من رمز بايت DEX (تنسيق رمز البايت داخل حزمة APK) إلى رمز الآلة (مشابه للغة C++ المجمّعة مسبقًا).

يتم تشغيل Macrobenchmark تلقائيًا باستخدام CompilationMode.DEFAULT، ما يؤدي إلى تثبيت "الملف الأساسي"، إذا كان متاحًا، على الإصدار 7 من نظام التشغيل Android (المستوى 24 لواجهة برمجة التطبيقات) والإصدارات الأحدث. إذا كنت تستخدم الإصدار 6 من نظام التشغيل Android (المستوى 23 من واجهة برمجة التطبيقات) أو إصدارًا أقدم، سيتم تجميع حزمة APK بالكامل كإجراء تلقائي للنظام.

يمكنك تثبيت "ملف تعريف أساسي" إذا كان التطبيق المستهدَف يتضمّن كلاً من "ملف التعريف الأساسي" ومكتبة ProfileInstaller.

في نظام التشغيل Android 7 والإصدارات الأحدث، يمكنك تخصيص CompilationMode للتأثير في مقدار التجميع المُسبَق على الجهاز لمحاكاة مستويات مختلفة من التجميع المسبَق (AOT) أو التخزين المؤقت أثناء التشغيل (JIT). يمكنك الاطّلاع على CompilationMode.Full وCompilationMode.Partial وCompilationMode.None وCompilationMode.Ignore.

تستند هذه الميزة إلى أوامر تجميع ART. يمحو كل مقياس أداء بيانات الملف الشخصي قبل البدء، وذلك للمساعدة في ضمان عدم حدوث تداخل بين مقاييس الأداء.

StartupMode

لتنفيذ عملية بدء نشاط، يمكنك تمرير وضع بدء تشغيل محدّد مسبقًا: COLD أو WARM أو HOT. تغيّر هذه المَعلمة طريقة تشغيل النشاط وحالة العملية في بداية الاختبار.

لمزيد من المعلومات عن أنواع التشغيل، اطّلِع على وقت تشغيل التطبيق.

نماذج

يتوفّر مشروع نموذجي في نموذج Macrobenchmark الخاص بالمستودع على GitHub.

تقديم ملاحظات

للإبلاغ عن مشاكل أو إرسال طلبات ميزات في Jetpack Macrobenchmark، يُرجى الاطّلاع على أداة تتبُّع المشاكل العامة.

التالي
تسجيل المقاييس