أوامر تصحيح الأخطاء لإنشاء الملفات الشخصية المحلية

When testing your ProfilingManager integration locally, requests might be throttled by rate limiting or background traces might not be active when testing triggers. استخدِم أوامر adb في هذه الصفحة لإيقاف التقييد، وسحب الملفات الشخصية، والاحتفاظ بالتتبعات غير المنقحة، وتشغيل عمليات الالتقاط، وفحص حالة الخدمة على جهاز اختبار.

إيقاف محدِّد المعدّل

لإيقاف محدّدات معدّل طلبات requestProfiling على مستوى النظام وعمليات التطبيق أثناء الاختبار المحلي، شغِّل أمر device_config التالي:

adb shell device_config put profiling_testing rate_limiter.disabled true

عند الانتهاء من الاختبار، أعِد ضبط العلامة:

adb shell device_config delete profiling_testing rate_limiter.disabled

ملاحظة: لا ينطبق rate_limiter.disabled إلا على المكالمات التي يتم إجراؤها من خلال requestProfiling. عند اختبار المشغّلات محليًا، اضبط system_triggered_profiling.testing_package_name لفرض تتبُّع مستمر في الخلفية وتجاوز محدّد المعدّل على مستوى النظام، كما هو موضّح في فرض تفعيل عمليات التتبُّع في الخلفية لاختبار المشغّلات.

سحب الملفات الشخصية باستخدام ADB

لفحص ملف شخصي تم تنقيحه محليًا على جهاز يتيح الوصول إلى الجذر، شغِّل adb pull مع المسار الذي يعرضه getResultFilePath:

# Pull a profile
adb pull /data/user/0/<com.example.myapp>/files/profiling/<profile-file-name>

ملاحظة: إذا لم يكن لديك إذن الوصول إلى الجذر، يمكنك ضبط ProfilingManager للاحتفاظ بالملفات الشخصية في /data/misc/perfetto-traces/profiling/، والتي يمكن الوصول إليها باستخدام adb pull في جميع أنواع الإصدارات على Android 16 (مستوى واجهة برمجة التطبيقات 36) والإصدارات الأحدث. يُرجى الاطّلاع على الاحتفاظ بالنتائج المؤقتة وغير المنقّحة.

الاحتفاظ بالنتائج المؤقتة وغير المنقحة

عند اختبار عملية تحليل الأداء على الجهاز، يمكنك الاحتفاظ بالنتائج في الدليل المؤقت على /data/misc/perfetto-traces/profiling/. تساعدك مقارنة سجلّ تتبّع النظام غير المنقّح بنظيره المنقّح في فهم البيانات التي يتم حذفها أثناء التنقيح.

تعتمد كيفية الاحتفاظ بالنتائج المؤقتة وغير المنقّحة على إصدار Android الذي يعمل به جهازك:

• الإصدار 16 من نظام التشغيل Android (مستوى واجهة برمجة التطبيقات 36) والإصدارات الأحدث: يمكنك الاحتفاظ بالنتائج غير المنقّحة (حيثما ينطبق ذلك) والنتائج المنقّحة في الدليل المؤقت، والذي تم توسيعه في الإصدار 16 من نظام التشغيل Android ليكون من الممكن الوصول إليه باستخدام adb pull على جميع أنواع التصميم بدون الوصول إلى الجذر (بينما يتطلب الإصدار 15 من نظام التشغيل Android الوصول إلى الجذر لقراءة /data/misc/perfetto-traces/profiling/). لمنع النظام من حذف النتائج المؤقتة، شغِّل الأمر التالي:

  adb shell device_config put profiling_testing delete_temporary_results.disabled true
  

• ‫Android 15 (مستوى واجهة برمجة التطبيقات 35): في الدليل المؤقت، يمكنك الاحتفاظ بالنتيجة غير المنقّحة فقط، والتي يمكن الوصول إليها من خلال adb فقط في الإصدارات التي تتيح الوصول إلى الجذر. (يستمر تطبيقك في تلقّي الملف الشخصي الذي تم تنقيحه في دليل /data/user/0/<app>/files/profiling/ الخاص به، والذي يمكن لرمز تطبيقك قراءته أو نسخه في أي إصدار، على الرغم من أنّ السحب مباشرةً من /data/user/0/... باستخدام adb pull يتطلب الوصول إلى الجذر أو adb shell run-as <app> في إصدار قابل للتصحيح). لمنع النظام من حذف عمليات التتبُّع التي لم يتم تنقيحها، نفِّذ الأمر التالي:

  adb shell device_config put profiling_testing delete_unredacted_trace.disabled true
  

بعد تسجيل ملف شخصي، اسحب الملف المحفوظ من الدليل المؤقت:

# Pull a retained redacted profile (Android 16 and higher)
adb pull /data/misc/perfetto-traces/profiling/<trace-name>.<profile-type-ext>

# Pull an unredacted system trace
adb pull /data/misc/perfetto-traces/profiling/<trace-name>.perfetto-trace-unredacted

في هذه الأوامر، يمثّل <trace-name> اسم الملف الأساسي (بدون امتداد) من المسار الذي يعرضه ProfilingResult.getResultFilePath، وتُلحق نسخة سجلّ تتبّع النظام غير المنقّحة -unredacted بالامتداد .perfetto-trace. للحصول على تفاصيل حول بنية اسم الملف وقيم <profile-type-ext>، يُرجى الاطّلاع على مواقع الملفات وتنسيقات التسمية.

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

adb shell device_config delete profiling_testing delete_temporary_results.disabled
adb shell device_config delete profiling_testing delete_unredacted_trace.disabled

فرض تفعيل عمليات التتبُّع في الخلفية لاختبار المشغّلات

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

adb shell device_config put profiling_testing system_triggered_profiling.testing_package_name <com.example.myapp>

سيظلّ ساريًا أيّ وقت انتظار لكلّ عامل تشغيل تم ضبطه باستخدام setRateLimitingPeriodHours. بما أنّ هذا الوضع يعمل بشكل مستمر إلى أن يتم إيقافه، يجب إزالة العلامة عند الانتهاء من الاختبار:

adb shell device_config delete profiling_testing system_triggered_profiling.testing_package_name

أوامر تصحيح الأخطاء المفيدة

على أجهزة Android 16 (مستوى واجهة برمجة التطبيقات 36) والإصدارات الأحدث التي تتضمّن إصدارًا حديثًا من وحدة Profiling، يمكنك استخدام أداة cmd profiling_service عبر adb لتفعيل التسجيل المطوّل وبدء عمليات جمع الملفات الشخصية عند الطلب واختبار المشغّلات مباشرةً من سطر الأوامر.

ملاحظة: قد تتوفّر خيارات إضافية أو تتم إضافتها بمرور الوقت. شغِّل adb shell cmd profiling_service help للاطّلاع على جميع أوامر تصحيح الأخطاء والعلامات وتفاصيل الاستخدام المتاحة.

تفعيل التسجيل المطوَّل لتصحيح الأخطاء

لتفعيل سجلّات ProfilingService التفصيلية في logcat وتشخيص معالجة الطلبات وتسليمها، نفِّذ الأمر التالي:

adb shell cmd profiling_service enable-logs true

طلب جمع ملفات شخصية عند الطلب

لبدء التقاط ملف شخصي فوري لحزمة معيّنة من سطر الأوامر، نفِّذ الأمر التالي:

adb shell cmd profiling_service request-profiling <profiling_type> <com.example.myapp> [--user <user_id>] [--duration <duration_ms>] [--sources <sources>]

في هذا الأمر، يمثّل <profiling_type> قيمة العدد الصحيح الثابتة من ProfilingManager (1 للقطة لأجزاء من الذاكرة في Java، أو 2 للقطة لعناصر متعدّدة، أو 3 لأخذ عيّنات من تسلسل استدعاء الدوال البرمجية، أو 4 لسجلّ تتبّع النظام). يجب أن تكون عملية التطبيق المستهدَف قيد التشغيل لملفات الذاكرة والملفات الشخصية المكدّسة، ويخضع الطلب لمحدِّد المعدّل ما لم يتم إيقافه، ولا يتم تسليم ProfilingResult المكتمل إلا للمستمعين العالميين المسجّلين في registerForAllProfilingResults.

تسجيل المشغّلات ومحاكاتها

لتسجيل مصدر تتبُّع أو بدء حدث مصدر تتبُّع تمّت محاكاته لحزمة معيّنة والتحقّق من طريقة معالجة عمليات معاودة الاتصال بمصدر التتبُّع، شغِّل الأوامر التالية:

adb shell cmd profiling_service add-trigger <trigger_type> <com.example.myapp> [--user <user_id>]
adb shell cmd profiling_service trigger <trigger_type> <com.example.myapp> [--user <user_id>]

في هذه الأوامر، يمثّل <trigger_type> قيمة الثابت الصحيح من ProfilingTrigger (على سبيل المثال، 1 لـ TRIGGER_TYPE_APP_FULLY_DRAWN، أو 2 لـ TRIGGER_TYPE_ANR، أو 7 لـ TRIGGER_TYPE_OOM). يؤدي تشغيل add-trigger إلى تسجيل عامل التفعيل مع فترة تهدئة مدتها 0 ساعة، ما يؤدي إلى إلغاء أي تسجيل حالي لنوع عامل التفعيل هذا. تتطلّب محاكاة المشغّلات التي تحفظ لقطة من تتبُّع الخلفية (مثل 1 أو 2) تتبُّعًا نشطًا للخلفية (يُرجى الاطّلاع على فرض تفعيل تتبُّعات الخلفية لاختبار المشغّلات).

جمع حالة ProfilingManager العامة

على Android 16 (المستوى 36 من واجهة برمجة التطبيقات) والإصدارات الأحدث التي تتضمّن إصدارًا حديثًا من وحدة Profiling، يمكنك تشغيل dumpsys على profiling_service لتشخيص المشاكل وفحص الحالة الحالية لـ ProfilingManager:

adb shell dumpsys profiling_service

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

• حالة عمليات التقييد النشطة ومحدِّد المعدّل
• إعدادات الأجهزة النشطة
• مشغّلات التطبيقات المسجّلة وفترات التهدئة الخاصة بها للحدّ من معدّل الاستخدام
• جلسات تحليل الملفات الشخصية النشطة والمُدرَجة في قائمة الانتظار
• طلبات إنشاء الملفات الشخصية الأخيرة، وأحداث تشغيلها، وأحداث تسليم النتائج

ملاحظة: للاحتفاظ بسجلّ أطول للأحداث الأخيرة في مخرجات dumpsys أثناء جلسات تصحيح الأخطاء الممتدة، يمكنك تشغيل adb shell cmd profiling_service enable-long-dumpsys true.