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

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

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

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

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

Macrobenchmark ابزار پیشنهادی برای آزمایش رابط‌های کاربری ایجاد شده با Jetpack Compose است. برای یادگیری نحوه نوشتن تست‌های UI Automator که با گره‌های Compose شما تعامل دارند، به Interoperability مراجعه کنید.

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

توصیه می‌کنیم از 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 {
    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. پنل 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 انتخاب کنید و برای هر ماژول دیگری که در برنامه خود دارید، 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 به سیستم ساخت می‌گوید که به بعد 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 نشان داده شده است:

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

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

تست بنچمارک از طریق 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,
    ) {
        // starts default launch activity
        uiAutomator { startApp(TARGET_PACKAGE) }
    }
}
SampleStartupBenchmark.kt

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

تعاملات رابط کاربری Compose را محک بزنید

در حالی که مثال قبلی شروع به کار برنامه را اندازه‌گیری می‌کند، شما اغلب می‌خواهید عملکرد رابط کاربری، مانند افت فریم ( jank ) هنگام پیمایش را اندازه‌گیری کنید.

برای سنجش یک برنامه Jetpack Compose، مانند اندازه‌گیری FrameTimingMetric هنگام پیمایش یک LazyColumn ، می‌توانید از UI Automator برای تعامل مستقیم با گره‌های Compose خود استفاده کنید، همانطور که در قطعه کد زیر نشان داده شده است.

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

    @Test
    fun scrollLazyColumn() = benchmarkRule.measureRepeated(
        packageName = "com.example.compose.app",
        metrics = listOf(FrameTimingMetric()),
        iterations = 5,
        startupMode = StartupMode.WARM,
        setupBlock = { pressHome() }
    ) {
        startActivityAndWait()

        // Find the Compose node using the testTag defined in your app
        val lazyColumn = device.findObject(By.res("my_lazy_column"))

        // Simulate a scroll gesture to measure FrameTimingMetric
        lazyColumn.setGestureMargin(device.displayWidth / 5)
        lazyColumn.fling(Direction.DOWN)
    }
}

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

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

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

./gradlew :macrobenchmark:connectedCheck

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

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

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

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

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

وقتی ردیابی بارگذاری شد، اندروید استودیو از شما می‌خواهد فرآیندی را که می‌خواهید تجزیه و تحلیل کنید انتخاب کنید. همانطور که در شکل 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، به ردیاب مشکلات عمومی مراجعه کنید.

{% کلمه به کلمه %} {% فعل کمکی %}

برای شما توصیه می‌شود

• توجه: متن لینک زمانی نمایش داده می‌شود که جاوا اسکریپت غیرفعال باشد.
• ثبت معیارهای Macrobenchmark
• ایجاد پروفایل‌های پایه {:#creating-profile-rules}
• اندازه‌گیری خودکار با کتابخانه Macrobenchmark {:#measuring-optimization}

{% کلمه به کلمه %} {% فعل کمکی %}