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

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

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

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

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

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

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

إعداد وحدة Macrobenchmark

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    matchingFallbacks += listOf("release")
 }

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، كما هو موضّح في المقتطف التالي:

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

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 كالسِمة التلقائية:

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

defaultConfig {
    missingDimensionStrategy "environment", "production"
}

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

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

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

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

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

    production {
        dimension 'environment'
    }
}

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

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

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

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

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

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

@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,
    ) {
        // starts default launch activity
        uiAutomator { startApp(TARGET_PACKAGE) }
    }
}
SampleStartupBenchmark.kt

@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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• StartupTimingMetric
• FrameTimingMetric
• TraceSectionMetric

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

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

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

CompilationMode

يمكن أن تحدّد اختبارات Macrobenchmark 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، يُرجى الاطّلاع على أداة تتبُّع المشاكل العامة.