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

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

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

همانطور که در بخش «معیار در ادغام مداوم » توضیح داده شده است، از کتابخانه Macrobenchmark در یک محیط ادغام مداوم (CI) استفاده کنید.

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

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

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

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

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

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

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

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

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

3. روی پایان کلیک کنید.

شکل ۱. الگوی ماژول بنچمارک.

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

برای ارزیابی یک برنامه - که به عنوان هدف Macrobenchmark شناخته می‌شود - برنامه باید profileable باشد، که امکان خواندن اطلاعات ردیابی دقیق را بدون تأثیر بر عملکرد فراهم می‌کند. ویزارد ماژول، برچسب <profileable> را به طور خودکار به فایل AndroidManifest.xml برنامه اضافه می‌کند.

مطمئن شوید که برنامه‌ی هدف شامل ProfilerInstaller 1.3 یا بالاتر است، که کتابخانه‌ی Macrobenchmark برای فعال کردن ضبط و تنظیم مجدد پروفایل و پاکسازی حافظه‌ی نهانگاه سایه‌زن به آن نیاز دارد.

برنامه‌ی بنچمارک‌شده را تا حد امکان نزدیک به نسخه‌ی انتشار یا تولید پیکربندی کنید. آن را طوری تنظیم کنید که اشکال‌زدایی (debugging) آن امکان‌پذیر نباشد و ترجیحاً قابلیت کوچک‌سازی (minification) آن فعال باشد که عملکرد را بهبود می‌بخشد. شما معمولاً این کار را با ایجاد یک کپی از نسخه‌ی انتشار انجام می‌دهید که عملکرد مشابهی دارد، اما به صورت محلی با کلیدهای اشکال‌زدایی امضا شده است. به عنوان یک روش جایگزین، می‌توانید 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 را انتخاب کنید.

شکل ۲. نوع معیار را انتخاب کنید.

(اختیاری) راه‌اندازی برنامه چند ماژوله

اگر برنامه شما بیش از یک ماژول 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.
      ...

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

شکل ۳. انواع معیار برای پروژه چند ماژولی با انواع نسخه و ساخت معیار انتخاب شده.

برای اطلاعات بیشتر، به «استفاده از مدیریت وابستگی آگاه از نوع» مراجعه کنید.

(اختیاری) تنظیمات طعم‌های محصول

اگر چندین طعم محصول در برنامه خود تنظیم کرده‌اید، ماژول :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 به سیستم ساخت می‌گوید که به بعد flavor بازگردد. اگر ابعادی را در ماژول پیدا نکردید، مشخص کنید که از کدام ابعاد استفاده شود. در مثال زیر، از flavor 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'
    }
}

پس از تعریف و همگام‌سازی پروژه، نوع ساخت مربوطه را از پنجره Build Variants انتخاب کنید، همانطور که در شکل 4 نشان داده شده است:

شکل ۴. انواع بنچمارک برای پروژه با انواع محصول که "productionBenchmark" و "release" انتخاب شده را نشان می‌دهند.

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

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

تست بنچمارک از طریق API قاعده MacrobenchmarkRule JUnit4 در کتابخانه Macrobenchmark ارائه می‌شود. این API شامل یک متد 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;
            }
        );
    }
}

برای مشاهده‌ی تمام گزینه‌های مربوط به سفارشی‌سازی بنچمارک، به بخش «سفارشی‌سازی بنچمارک‌ها» مراجعه کنید.

اجرای بنچمارک

تست را از داخل اندروید استودیو اجرا کنید تا عملکرد برنامه خود را روی دستگاهتان بسنجید. می‌توانید بنچمارک‌ها را مانند هر @Test دیگری با استفاده از اکشن حاشیه‌ای کنار کلاس یا متد تست خود اجرا کنید، همانطور که در شکل 5 نشان داده شده است.

شکل ۵. اجرای Macrobenchmark با عملکرد حاشیه‌ای (gutter) در کنار کلاس تست.

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

./gradlew :macrobenchmark:connectedCheck

شما می‌توانید با اجرای دستور زیر، یک تست واحد را اجرا کنید:

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

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

نتایج بنچمارک

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

شکل ۶. نتایج راه‌اندازی Macrobenchmark.

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

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

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

شکل ۸. رد استودیو.

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

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

دسترسی به فایل‌های ردیابی به صورت دستی

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

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

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

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

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

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

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

سفارشی‌سازی بنچمارک‌ها

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

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

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

• StartupTimingMetric
• FrameTimingMetric
• TraceSectionMetric

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

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

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

حالت کامپایل

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

به طور پیش‌فرض، Macrobenchmarks با CompilationMode.DEFAULT اجرا می‌شوند، که یک Baseline Profile - در صورت وجود - را روی اندروید ۷ (سطح API 24) و بالاتر نصب می‌کند. اگر از اندروید ۶ (سطح API 23) یا قبل از آن استفاده می‌کنید، حالت کامپایل، APK را به طور کامل به عنوان رفتار پیش‌فرض سیستم کامپایل می‌کند.

اگر برنامه‌ی هدف شامل هر دو کتابخانه‌ی Baseline Profile و ProfileInstaller باشد، می‌توانید Baseline Profile را نصب کنید.

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

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

حالت راه‌اندازی

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

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

نمونه‌ها

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

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

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