یک ماکرو بنچمارک بنویسید

از کتابخانه Macrobenchmark برای آزمایش موارد استفاده بزرگتر از برنامه خود، از جمله راه اندازی برنامه و دستکاری های پیچیده رابط کاربری، مانند پیمایش RecyclerView یا اجرای انیمیشن ها استفاده کنید. اگر می‌خواهید قسمت‌های کوچک‌تری از کد خود را آزمایش کنید، به کتابخانه Microbenchmark مراجعه کنید. این صفحه نحوه راه اندازی کتابخانه Macrobenchmark را نشان می دهد.

این کتابخانه نتایج محک زدن را هم برای کنسول Android Studio و هم یک فایل JSON با جزئیات بیشتر ارائه می دهد. همچنین فایل های ردیابی را ارائه می دهد که می توانید آن ها را در Android Studio بارگذاری و تجزیه و تحلیل کنید.

از کتابخانه Macrobenchmark در محیط یکپارچه سازی پیوسته (CI) استفاده کنید، همانطور که در Benchmark in Continuous Integration توضیح داده شده است.

شما می توانید از Macrobenchmark برای ایجاد نمایه های پایه استفاده کنید. ابتدا کتابخانه Macrobenchmark را راه اندازی کنید، سپس می توانید یک نمایه پایه ایجاد کنید .

راه اندازی پروژه

توصیه می کنیم از Macrobenchmark با آخرین نسخه Android Studio برای ویژگی های IDE که با Macrobenchmark ادغام می شوند استفاده کنید.

ماژول Macrobenchmark را راه اندازی کنید

ماکرو بنچمارک‌ها به یک ماژول com.android.test نیاز دارند - جدا از کد برنامه شما - که مسئول اجرای آزمایش‌هایی است که برنامه شما را اندازه‌گیری می‌کند.

در اندروید استودیو، یک الگو برای ساده‌سازی ماژول Macrobenchmark در دسترس است. الگوی ماژول محک به طور خودکار یک ماژول در پروژه شما برای اندازه گیری برنامه ساخته شده توسط یک ماژول برنامه ایجاد می کند، از جمله یک نمونه معیار راه اندازی.

برای استفاده از قالب ماژول برای ایجاد یک ماژول جدید، موارد زیر را انجام دهید:

1. روی پروژه یا ماژول خود در پنل Project در Android Studio کلیک راست کرده و New > Module را انتخاب کنید.

2. Benchmark را از قسمت Templates انتخاب کنید. می‌توانید برنامه مورد نظر را سفارشی کنید - به این معنی که برنامه مورد سنجش قرار می‌گیرد - و همچنین نام بسته و ماژول را برای ماژول جدید Macrobenchmark سفارشی کنید.

3. روی Finish کلیک کنید.

شکل 1. الگوی ماژول معیار.

برنامه را تنظیم کنید

برای محک زدن یک برنامه – که به عنوان هدف ماکرو بنچمارک شناخته می‌شود – برنامه باید 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 {
    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. پانل Build Variants را باز کنید.
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.
      ...

همانطور که در شکل 3 نشان داده شده است، هنگام انتخاب انواع ساخت در پروژه خود، benchmark برای ماژول های :app و :macrobenchmark انتخاب کنید و برای هر ماژول دیگری که در برنامه خود دارید release :

شکل 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، نوع ساخت مربوطه را از پنجره Build Variants انتخاب کنید:

شکل 4. انواع معیار برای پروژه با طعم های محصول که "محک تولید" و "انتشار" انتخاب شده را نشان می دهد.

برای اطلاعات بیشتر، به رفع خطاهای ساخت مربوط به تطبیق انواع مراجعه کنید.

یک کلاس macrobenchmark ایجاد کنید

تست معیار از طریق API قانون MacrobenchmarkRule JUnit4 در کتابخانه 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,
        setupBlock = {
            // Press home button before each run to ensure the starting activity isn't visible.
            pressHome()
        }
    ) {
        // starts default launch activity
        startActivityAndWait()
    }
}
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 Studio اجرا کنید تا عملکرد برنامه خود را در دستگاه خود اندازه گیری کنید. همانطور که در شکل 5 نشان داده شده است، می توانید بنچمارک ها را به همان روشی که هر @Test دیگر را با استفاده از عمل ناودان در کنار کلاس یا روش آزمایشی خود اجرا می کنید، اجرا کنید.

شکل 5. Macrobenchmark را با عمل ناودان در کنار کلاس تست اجرا کنید.

همچنین می‌توانید با اجرای دستور connectedCheck ، تمام بنچمارک‌ها را در ماژول Gradle از خط فرمان اجرا کنید:

./gradlew :macrobenchmark:connectedCheck

با اجرای موارد زیر می توانید یک تست را اجرا کنید:

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

برای اطلاعات در مورد نحوه اجرا و نظارت بر معیارها در یکپارچگی مداوم، به معیار در یکپارچگی مداوم مراجعه کنید.

نتایج محک

پس از اجرای موفقیت‌آمیز معیار، معیارها مستقیماً در Android Studio نمایش داده می‌شوند و برای استفاده از CI در یک فایل JSON خروجی می‌شوند. هر تکرار اندازه گیری شده یک ردیابی سیستم جداگانه را ثبت می کند. همانطور که در شکل 6 نشان داده شده است، می توانید این نتایج ردیابی را با کلیک بر روی پیوندهای موجود در صفحه نتایج تست باز کنید:

شکل 6. نتایج راه اندازی ماکرو بنچمارک.

هنگامی که ردیابی بارگذاری می شود، Android Studio از شما می خواهد که فرآیند تجزیه و تحلیل را انتخاب کنید. همانطور که در شکل 7 نشان داده شده است، انتخاب با فرآیند برنامه هدف از قبل پر شده است:

شکل 7. انتخاب فرآیند ردیابی استودیویی.

پس از بارگیری فایل trace، Studio نتایج را در ابزار CPU profiler نشان می دهد:

شکل 8. ردیابی استودیو.

گزارش های JSON و هرگونه ردیابی پروفایل نیز به طور خودکار از دستگاه به میزبان کپی می شود. اینها روی ماشین میزبان در مکان زیر نوشته شده است:

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

دسترسی دستی به فایل های ردیابی

اگر می خواهید از ابزار Perfetto برای تجزیه و تحلیل یک فایل ردیابی استفاده کنید، مراحل اضافی در این زمینه وجود دارد. Perfetto به شما امکان می دهد تمام فرآیندهایی را که در سراسر دستگاه در طول ردیابی اتفاق می افتد بررسی کنید، در حالی که نمایه ساز CPU Android Studio بازرسی را به یک فرآیند محدود می کند.

اگر تست ها را از Android Studio یا از خط فرمان Gradle فراخوانی کنید، فایل های ردیابی به طور خودکار از دستگاه به هاست کپی می شوند. اینها روی ماشین میزبان در مکان زیر نوشته شده است:

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

هنگامی که فایل trace را در سیستم میزبان خود دارید، می توانید آن را در Android Studio با File > Open در منو باز کنید. این نمای ابزار پروفایلر را نشان می دهد که در بخش قبل نشان داده شده است.

خطاهای پیکربندی

اگر برنامه به اشتباه پیکربندی شده باشد – قابل اشکال‌زدایی یا غیرقابل نمایه‌سازی – Macrobenchmark به جای گزارش اندازه‌گیری نادرست یا ناقص، خطا را برمی‌گرداند. می توانید این خطاها را با آرگومان androidx.benchmark.suppressErrors سرکوب کنید.

Macrobenchmark همچنین هنگام تلاش برای اندازه‌گیری شبیه‌ساز یا دستگاهی با باتری کم، خطاهایی را برمی‌گرداند که ممکن است در دسترس بودن هسته و سرعت ساعت را به خطر بیندازد.

معیارها را سفارشی کنید

تابع measureRepeated پارامترهای مختلفی را می‌پذیرد که بر معیارهایی که کتابخانه جمع‌آوری می‌کند، نحوه راه‌اندازی و کامپایل برنامه شما یا تعداد تکرارهایی که بنچمارک اجرا می‌کند تأثیر می‌گذارد.

معیارها را ثبت کنید

معیارها نوع اصلی اطلاعات استخراج شده از معیارهای شما هستند. معیارهای زیر در دسترس هستند:

• StartupTimingMetric
• FrameTimingMetric
• TraceSectionMetric

برای اطلاعات بیشتر در مورد معیارها، به ضبط معیارهای سنجش ماکرو مراجعه کنید.

داده های ردیابی را با رویدادهای سفارشی بهبود دهید

این می تواند مفید باشد که برنامه خود را با رویدادهای ردیابی سفارشی، که با بقیه گزارش ردیابی مشاهده می شود، مفید باشد و می تواند به اشاره به مشکلات خاص برنامه شما کمک کند. برای کسب اطلاعات بیشتر درباره ایجاد رویدادهای ردیابی سفارشی، به تعریف رویدادهای سفارشی مراجعه کنید.

CompilationMode

ماکرو بنچمارک‌ها می‌توانند یک CompilationMode مشخص کنند که تعیین می‌کند چه مقدار از برنامه باید از بایت کد DEX (فرمت بایت کد در یک APK) به کد ماشین (شبیه به C++ از پیش کامپایل‌شده) از پیش کامپایل شود.

به‌طور پیش‌فرض، ماکرو بنچمارک‌ها با CompilationMode.DEFAULT اجرا می‌شوند که یک نمایه خط پایه (در صورت موجود بودن) را در Android 7 (سطح API 24) و جدیدتر نصب می‌کند. اگر از Android 6 (سطح API 23) یا نسخه قبلی استفاده می کنید، حالت کامپایل APK را به طور کامل به عنوان رفتار پیش فرض سیستم کامپایل می کند.

اگر برنامه مورد نظر حاوی یک نمایه پایه و کتابخانه ProfileInstaller باشد، می‌توانید یک نمایه خط پایه نصب کنید.

در اندروید 7 و جدیدتر، می‌توانید CompilationMode سفارشی کنید تا بر میزان پیش‌کامپایل روی دستگاه تأثیر بگذارد تا سطوح مختلف کامپایل پیش از زمان (AOT) یا ذخیره‌سازی JIT را تقلید کند. CompilationMode.Full ، CompilationMode.Partial ، CompilationMode.None و CompilationMode.Ignore را ببینید.

این ویژگی بر اساس دستورات کامپایل ART ساخته شده است. هر معیار قبل از شروع، داده های نمایه را پاک می کند تا از عدم تداخل بین معیارها اطمینان حاصل شود.

StartupMode

برای انجام یک شروع فعالیت، می‌توانید یک حالت راه‌اندازی از پیش تعریف‌شده را عبور دهید: COLD ، WARM یا HOT . این پارامتر نحوه راه اندازی اکتیویتی و وضعیت فرآیند را در شروع آزمایش تغییر می دهد.

برای اطلاعات بیشتر در مورد انواع راه اندازی، به زمان راه اندازی برنامه مراجعه کنید.

نمونه ها

یک پروژه نمونه در Macrobenchmark Sample مخزن در GitHub موجود است.

بازخورد ارائه دهید

برای گزارش مشکلات یا ارسال درخواست‌های ویژگی برای Jetpack Macrobenchmark، به ردیاب مسائل عمومی مراجعه کنید.