تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
المقاييس هي النوع الرئيسي من المعلومات المستخرَجة من مقاييس الأداء. يتم تمريرها إلى الدالة measureRepeated كـ List، ما يتيح لك تحديد مقاييس متعدّدة في الوقت نفسه. يجب توفير نوع واحد على الأقل من المقاييس لكي يتم تشغيل مقياس الأداء.
يلتقط مقتطف الرمز التالي مقاييس توقيت اللقطات وقسم التتبُّع المخصّص:
يتم إخراج نتائج قياس الأداء إلى "استوديو Android"، كما هو موضّح في الشكل 1.
في حال تحديد مقاييس متعدّدة، يتم دمجها جميعًا في الناتج.
الشكل 1. نتائج TraceSectionMetric وFrameTimingMetric
StartupTimingMetric
تعمل السمة StartupTimingMetric
على تسجيل مقاييس توقيت بدء تشغيل التطبيق بالقيم التالية:
timeToInitialDisplayMs: مقدار الوقت الذي يستغرقه النظام منذ تلقّي طلب تشغيل التطبيق إلى أن يعرض اللقطة الأولى من Activity.
timeToFullDisplayMs: مقدار الوقت المستغرَق منذ أن يتلقّى النظام
نية التشغيل إلى أن يُبلغ التطبيق عن اكتمال عملية الرسم باستخدام
الطريقة reportFullyDrawn(). يتوقف القياس عند اكتمال عرض الإطار الأول بعد طلب reportFullyDrawn() أو الذي يتضمّن هذا الطلب. قد لا يتوفّر هذا المقياس على الإصدار Android 10 (المستوى 29 من واجهة برمجة التطبيقات) والإصدارات الأقدم.
تعرض StartupTimingMetric الحد الأدنى والمتوسط والأقصى للقيم من عمليات التكرار عند بدء التشغيل. لتقييم تحسّن أداء التطبيق عند بدء تشغيله، عليك التركيز على قيم الوسيط، لأنّها تقدّم أفضل تقدير لمتوسط وقت بدء التشغيل. لمزيد من المعلومات حول العوامل التي تؤثر في وقت بدء تشغيل التطبيق، يمكنك الاطّلاع على مقالة وقت بدء تشغيل التطبيق.
الشكل 2.StartupTimingMetric نتيجة
FrameTimingMetric
FrameTimingMetric
تسجّل معلومات التوقيت من اللقطات التي ينتجها مقياس أداء، مثل
التمرير أو الرسوم المتحركة، وتعرض القيم التالية:
frameOverrunMs: مقدار الوقت الذي يتأخر فيه عرض لقطة معيّنة عن الموعد النهائي.
تشير الأرقام الموجبة إلى حدوث انخفاض في عدد اللقطات وحدوث تشوّش أو تقطّع مرئي.
تشير الأرقام السالبة إلى مدى سرعة عرض اللقطة مقارنةً بالموعد النهائي.
ملاحظة: تتوفّر هذه الميزة فقط على الإصدار 12 من نظام التشغيل Android (المستوى 31 من واجهة برمجة التطبيقات) والإصدارات الأحدث.
frameDurationCpuMs: مقدار الوقت الذي يستغرقه إنشاء اللقطة على وحدة المعالجة المركزية (CPU) في كل من سلسلة واجهة المستخدم وRenderThread
يتم جمع هذه القياسات في توزيع للشريحة المئوية الـ 50 والـ 90 والـ 95 والـ 99.
لمزيد من المعلومات حول كيفية تحديد اللقطات البطيئة وتحسينها، يُرجى الاطّلاع على عرض بطيء.
الشكل 3.FrameTimingMetric نتيجة
TraceSectionMetric
TraceSectionMetric
تسجّل عدد المرات التي يظهر فيها قسم تتبُّع مطابق sectionName
للمعلومات المقدَّمة والوقت المستغرَق. بالنسبة إلى الوقت، تعرض هذه السمة الحد الأدنى والوسيط والحد الأقصى للأوقات بالمللي ثانية. يتم تحديد قسم التتبُّع إما من خلال استدعاء الدالة trace(sectionName) أو الرمز بين Trace.beginSection(sectionName) وTrace.endSection() أو صيغها غير المتزامنة. يختار هذا الحقل دائمًا أول مثيل لقسم التتبُّع
الذي تم تسجيله أثناء عملية القياس. لا يعرض هذا الأمر تلقائيًا سوى أقسام التتبُّع من حزمتك، ولتضمين العمليات خارج حزمتك، اضبط targetPackageOnly = false.
تعرض PowerMetric التغيّر في الطاقة أو استهلاك الطاقة خلال مدة الاختبار لفئات الطاقة المحدّدة.
يتم تقسيم كل فئة محدّدة إلى مكوّناتها الفرعية القابلة للقياس، وتتم إضافة الفئات غير المحدّدة إلى مقياس "غير محدّدة".
تقيس هذه المقاييس الاستهلاك على مستوى النظام، وليس الاستهلاك على أساس كل تطبيق على حدة، وهي تقتصر على هواتف Pixel 6 وPixel 6 Pro والإصدارات الأحدث:
power<category>Uw: مقدار الطاقة المستهلكة خلال مدة الاختبار في هذه الفئة
energy<category>Uws: كمية الطاقة المنقولة لكل وحدة زمنية خلال مدة الاختبار في هذه الفئة
تشمل الفئات ما يلي:
CPU
DISPLAY
GPU
GPS
MEMORY
MACHINE_LEARNING
NETWORK
UNCATEGORIZED
في بعض الفئات، مثل CPU، قد يكون من الصعب فصل العمليات التي تنفّذها تطبيقات أخرى عن العمليات التي ينفّذها تطبيقك. ولتقليل التداخل، عليك إزالة التطبيقات والحسابات غير الضرورية أو حظرها.
الشكل 5.PowerMetric نتيجة
أفلام مُقترَحة لك
ملاحظة: يتم عرض نص الرابط عندما تكون JavaScript غير مفعّلة
يخضع كل من المحتوى وعيّنات التعليمات البرمجية في هذه الصفحة للتراخيص الموضحّة في ترخيص استخدام المحتوى. إنّ Java وOpenJDK هما علامتان تجاريتان مسجَّلتان لشركة Oracle و/أو الشركات التابعة لها.
تاريخ التعديل الأخير: 2025-08-21 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2025-08-21 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["# Capture Macrobenchmark metrics\n\nMetrics are the main type of information extracted from your benchmarks. They\nare passed to the [`measureRepeated`](/reference/kotlin/androidx/benchmark/macro/junit4/MacrobenchmarkRule#measureRepeated(kotlin.String,kotlin.collections.List,androidx.benchmark.macro.CompilationMode,androidx.benchmark.macro.StartupMode,kotlin.Int,kotlin.Function1,kotlin.Function1))\nfunction as a `List`, which lets you specify\nmultiple measured metrics at once. At least one type of metric is required for\nthe benchmark to run.\n\nThe following code snippet captures frame timing and custom trace section\nmetrics: \n\n### Kotlin\n\n```kotlin\nbenchmarkRule.measureRepeated(\n packageName = TARGET_PACKAGE,\n metrics = listOf(\n FrameTimingMetric(),\n TraceSectionMetric(\"RV CreateView\"),\n TraceSectionMetric(\"RV OnBindView\"),\n ),\n iterations = 5,\n // ...\n)\n```\n\n### Java\n\n```java\nbenchmarkRule.measureRepeated(\n TARGET_PACKAGE, // packageName\n Arrays.asList( // metrics\n new StartupTimingMetric(),\n new TraceSectionMetric(\"RV CreateView\"),\n new TraceSectionMetric(\"RV OnBindView\"),\n ),\n 5, // Iterations\n // ...\n);\n```\n\nIn this example, [`RV CreateView`](https://cs.android.com/search?q=TRACE_CREATE_VIEW_TAG&sq=&ss=androidx%2Fplatform%2Fframeworks%2Fsupport)\nand [`RV OnBindView`](https://cs.android.com/search?q=TRACE_BIND_VIEW_TAG)\nare the IDs of traceable blocks that are defined in\n[`RecyclerView`](/reference/androidx/recyclerview/widget/RecyclerView). The\n[source code for the `createViewHolder()`](https://cs.android.com/androidx/platform/frameworks/support/+/androidx-main:recyclerview/recyclerview/src/main/java/androidx/recyclerview/widget/RecyclerView.java;l=7950-7964)\nmethod is an example of how you can define traceable blocks within your own\ncode.\n\n[`StartupTimingMetric`](#startup-timing), [`TraceSectionMetric`](#trace-section), [`FrameTimingMetric`](#frame-timing),\nand [`PowerMetric`](#power), are covered in detail later in this document.\nFor a full list of metrics, check out subclasses of [`Metric`](/reference/kotlin/androidx/benchmark/macro/Metric).\n\nBenchmark results are output to Android Studio, as shown in figure 1.\nIf multiple metrics are defined, all of them are combined in the output.\n**Figure 1.** Results of `TraceSectionMetric` and `FrameTimingMetric`.\n\nStartupTimingMetric\n-------------------\n\n[`StartupTimingMetric`](/reference/kotlin/androidx/benchmark/macro/StartupTimingMetric)\ncaptures app startup timing metrics with the following values:\n\n- `timeToInitialDisplayMs`: The amount of time from when the system receives a launch intent to when it renders the first frame of the destination [`Activity`](/reference/android/app/Activity).\n- `timeToFullDisplayMs`: The amount of time from when the system receives a launch intent to when the app reports fully drawn using the [`reportFullyDrawn()`](/reference/android/app/Activity#reportFullyDrawn()) method. The measurement stops at the completion of rendering the first frame after---or containing---the `reportFullyDrawn()` call. This measurement might not be available on Android 10 (API level 29) and earlier.\n\n`StartupTimingMetric` outputs the min, median, and max values from the startup\niterations. To assess startup improvement you should focus on median values,\nsince they provide the best estimate of the typical startup time. For more\ninformation about what contributes to app startup time, see [App startup\ntime](/topic/performance/vitals/launch-time).\n**Figure 2.** `StartupTimingMetric` results.\n\nFrameTimingMetric\n-----------------\n\n[`FrameTimingMetric`](/reference/kotlin/androidx/benchmark/macro/FrameTimingMetric)\ncaptures timing information from frames produced by a benchmark, such as a\nscrolling or animation, and outputs the following values:\n\n- `frameOverrunMs`: the amount of time a given frame misses its deadline by. Positive numbers indicate a dropped frame and visible jank or stutter. Negative numbers indicate how much faster a frame is than the deadline. Note: This is available only on Android 12 (API level 31) and higher.\n- `frameDurationCpuMs`: the amount of time the frame takes to be produced on the CPU on both the UI thread and the `RenderThread`.\n\nThese measurements are collected in a distribution of 50th, 90th, 95th, and 99th\npercentile.\n\nFor more information on how to identify and improve slow frames, see\n[Slow rendering](/topic/performance/vitals/render).\n**Figure 3.** `FrameTimingMetric` results.\n\nTraceSectionMetric\n------------------\n\n| **Experimental:** This class is experimental.\n\n[`TraceSectionMetric`](/reference/kotlin/androidx/benchmark/macro/TraceSectionMetric)\ncaptures the number of times a trace section matching the provided `sectionName`\noccurs and the amount of time it takes. For the time, it outputs the minimum,\nmedian, and maximum times in milliseconds. The trace section is defined either\nby the function call\n[`trace(sectionName)`](/reference/kotlin/androidx/tracing/package-summary#trace(kotlin.String,kotlin.Function0))\nor the code between\n[`Trace.beginSection(sectionName)`](/reference/kotlin/androidx/tracing/Trace#beginSection(java.lang.String))\nand\n[`Trace.endSection()`](/reference/kotlin/androidx/tracing/Trace#endSection()) or\ntheir async variants. It always selects the first instance of a trace section\ncaptured during a measurement. It only outputs trace sections from your package\nby default; to include processes outside your package, set\n`targetPackageOnly = false`.\n\nFor more information about tracing, see [Overview of system\ntracing](/topic/performance/tracing) and [Define custom\nevents](/topic/performance/tracing/custom-events).\n**Figure 4.** `TraceSectionMetric` results.\n\nPowerMetric\n-----------\n\n| **Experimental:** This class is experimental.\n\n[`PowerMetric`](/reference/kotlin/androidx/benchmark/macro/PowerMetric) captures\nthe change in power or energy over the duration of your test for the provided\n[power categories](/reference/kotlin/androidx/benchmark/macro/PowerCategory).\nEach selected category is broken down into its measurable subcomponents, and\nunselected categories are added to the \"unselected\" metric.\n\nThese metrics measure\nsystem-wide consumption, not the consumption on a per-app basis, and are limited\nto Pixel 6, Pixel 6 Pro, and later devices:\n\n- `power\u003ccategory\u003eUw`: the amount of power consumed over the duration of your test in this category.\n- `energy\u003ccategory\u003eUws`: the amount of energy transferred per unit of time for the duration of your test in this category.\n\nCategories include the following:\n\n- `CPU`\n- `DISPLAY`\n- `GPU`\n- `GPS`\n- `MEMORY`\n- `MACHINE_LEARNING`\n- `NETWORK`\n- `UNCATEGORIZED`\n\nWith some categories, like `CPU`, it might be difficult to separate work done by\nother processes from work done by your own app. To minimize the interference,\nremove or restrict unnecessary apps and accounts.\n**Figure 5.** `PowerMetric` results.\n\nRecommended for you\n-------------------\n\n- Note: link text is displayed when JavaScript is off\n- [Create Baseline Profiles {:#creating-profile-rules}](/topic/performance/baselineprofiles/create-baselineprofile)\n- [Writing a Macrobenchmark](/topic/performance/benchmarking/macrobenchmark-overview)\n- [App startup analysis and optimization {:#app-startup-analysis-optimization}](/topic/performance/appstartup/analysis-optimization)"]]
