بدء استخدام ميزة "مراقبة الأداء" على Android

قبل البدء

أضِف Firebase إلى مشروع Android إذا لم يسبق لك إجراء ذلك.

الخطوة 1: إضافة حزمة SDK لمراقبة الأداء إلى تطبيقك

بعد إضافة حزمة SDK لمراقبة الأداء، يبدأ Firebase تلقائيًا في جمع بيانات عرض الشاشة في تطبيقك والبيانات المتعلقة بمراحل نشاط التطبيق (مثل وقت بدء التطبيق). لتفعيل Firebase من مراقبة طلبات الشبكة، عليك أيضًا إضافة مكوّن Gradle الإضافي لمراقبة الأداء (الخطوة التالية).

  1. في ملف Gradle للوحدة (على مستوى التطبيق) (عادةً <project>/<app-module>/build.gradle.kts أو <project>/<app-module>/build.gradle)، أضِف الاعتمادية لمكتبة "مراقبة الأداء" لنظام التشغيل Android. ننصح باستخدام بنود سياسة Android في Firebase للتحكّم في نُسَخ المكتبة. 

    dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:33.0.0"))

    // Add the dependency for the Performance Monitoring library
    // When using the BoM, you don't specify versions in Firebase library dependencies
    implementation("com.google.firebase:firebase-perf")
}

    باستخدام أداة إدارة قوائم التشغيل Android في Firebase، سيستخدم تطبيقك دائمًا الإصدارات المتوافقة من مكتبات Android في Firebase.

    (بديل) إضافة ملحقات مكتبة Firebase بدون استخدام BoM

    إذا اخترت عدم استخدام قائمة العناصر في Firebase، يجب تحديد كل إصدار من مكتبة Firebase في سطر الاعتمادية الخاص به.

    يُرجى العِلم أنّه إذا كنت تستخدم مكتبات متعددة لمنصة Firebase في تطبيقك، ننصحك بشدّة باستخدام BoM لإدارة إصدارات المكتبة، ما يضمن توافق جميع الإصدارات. 

    dependencies {
    // Add the dependency for the Performance Monitoring library
    // When NOT using the BoM, you must specify versions in Firebase library dependencies
    implementation("com.google.firebase:firebase-perf:21.0.0")
}
    هل تبحث عن وحدة مكتبة خاصة بلغة Kotlin؟ اعتبارًا من تشرين الأول (أكتوبر) 2023 (الإصدار 32.5.0 من Firebase)، أصبح بإمكان مطوّري لغة Kotlin وJava الاعتماد على وحدة المكتبة الرئيسية (لمعرفة التفاصيل، يُرجى الاطّلاع على الأسئلة الشائعة حول هذه المبادرة).

  2. أعِد تجميع تطبيقك.

الخطوة 2: إضافة المكوّن الإضافي لنظام Gradle لتتبُّع الأداء إلى تطبيقك

بعد إضافة المكوّن الإضافي Performance Monitoring Gradle، يبدأ Firebase تلقائيًا في جمع البيانات حول طلبات الشبكة المستندة إلى بروتوكول HTTP/S. ويتيح لك المكوّن الإضافي أيضًا قياس عمليات تتبّع الرموز المخصّصة باستخدام التعليق التوضيحي@AddTrace.

  1. في ملف Gradle على مستوى الجذر (على مستوى المشروع) (<project>/build.gradle.kts أو <project>/build.gradle)، أضِف المكوّن الإضافي لمراقبة الأداء Gradle:

    Kotlin 

    plugins {
    // To benefit from the latest Performance Monitoring plugin features,
    // update your Android Gradle plugin dependency to at least v3.4.0
    id("com.android.application") version "7.3.0" apply false

    // Make sure that you have the Google services Gradle plugin dependency
    id("com.google.gms.google-services") version "4.4.1" apply false

    // Add the dependency for the Performance Monitoring Gradle plugin
    id("com.google.firebase.firebase-perf") version "1.4.2" apply false
}

    Groovy 

    plugins {
    // To benefit from the latest Performance Monitoring plugin features,
    // update your Android Gradle plugin dependency to at least v3.4.0
    id 'com.android.application' version '7.3.0' apply false

    // Make sure that you have the Google services Gradle plugin dependency
    id 'com.google.gms.google-services' version '4.4.1' apply false

    // Add the dependency for the Performance Monitoring Gradle plugin
    id 'com.google.firebase.firebase-perf' version '1.4.2' apply false
}

  2. في ملف Gradle للوحدة (على مستوى التطبيق) (عادةً <project>/<app-module>/build.gradle.kts أو <project>/<app-module>/build.gradle)، أضِف المكوّن الإضافي لمراقبة الأداء Gradle:

    Kotlin 

    plugins {
    id("com.android.application")

    // Make sure that you have the Google services Gradle plugin
    id("com.google.gms.google-services")

    // Add the Performance Monitoring Gradle plugin
    id("com.google.firebase.firebase-perf")
    ...
}

    Groovy 

    plugins {
    id 'com.android.application'

    // Make sure that you have the Google services Gradle plugin
    id 'com.google.gms.google-services'

    // Add the Performance Monitoring Gradle plugin
    id 'com.google.firebase.firebase-perf'
    ...
}

  3. أعِد تجميع تطبيقك.

الخطوة 3: إنشاء أحداث الأداء للعرض الأولي للبيانات

يبدأ Firebase في معالجة الأحداث عند إضافة حزمة تطوير البرامج (SDK) بنجاح إلى تطبيقك. وإذا كنت لا تزال تطوِّر برامج على المستوى المحلي، يمكنك التفاعل مع تطبيقك لإنشاء أحداث من أجل جمع البيانات ومعالجتها بشكلٍ مبدئي.

  1. يمكنك إنشاء أحداث بتبديل حالة تطبيقك بين الخلفية والمقدمة عدة مرات، أو التفاعل مع التطبيق من خلال التنقُّل بين الشاشات، و/أو إرسال طلبات عبر الشبكة.

  2. انتقِل إلى لوحة بيانات الأداء في وحدة تحكُّم Firebase. من المفترض أن تظهر بياناتك الأولية في غضون بضع دقائق.

    إذا لم يتم عرض بياناتك الأولية، راجِع نصائح تحديد المشاكل وحلّها.

الخطوة 4: (اختياري) عرض رسائل السجلّ لأحداث الأداء

  1. يمكنك تفعيل تسجيل تصحيح الأخطاء لميزة "مراقبة الأداء" في وقت الإصدار من خلال إضافة عنصر <meta-data> إلى ملف AndroidManifest.xml في تطبيقك، كما يلي:

    <application>
    <meta-data
      android:name="firebase_performance_logcat_enabled"
      android:value="true" />
</application>

  2. تحقَّق من رسائل السجلّ بحثًا عن أي رسائل خطأ.

  3. تضيف "مراقبة الأداء" علامة FirebasePerformance على رسائل السجلّ الخاصة بها. باستخدام فلترة السجلّات، يمكنك على وجه التحديد عرض تتبُّع المدة وتسجيل طلب شبكة HTTP/S من خلال تشغيل الأمر التالي:

    adb logcat -s FirebasePerformance

  4. تحقَّق من الأنواع التالية من السجلّات التي تشير إلى أنّ ميزة "مراقبة الأداء" تسجِّل أحداث الأداء:

    • Logging trace metric: TRACE_NAME, FIREBASE_PERFORMANCE_CONSOLE_URL
    • Logging network request trace: URL

  5. انقر على عنوان URL للاطّلاع على بياناتك في "وحدة تحكُّم Firebase". قد يستغرق الأمر بضع دقائق حتى يتم تحديث البيانات في لوحة المعلومات.

إذا كان تطبيقك لا يسجّل أحداث الأداء، راجِع نصائح تحديد المشاكل وحلّها.

الخطوة 5: (اختيارية) إضافة تتبُّع مخصّص لرمز معيّن

لمراقبة بيانات الأداء المرتبطة برمز معيّن في تطبيقك، يمكنك استخدام عمليات تتبُّع الرموز المخصّصة.

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

في الرمز البرمجي، يمكنك تحديد بداية ونهاية عملية تتبُّع الرموز المخصّصة (وإضافة أي مقاييس مخصّصة مطلوبة) باستخدام واجهة برمجة التطبيقات التي توفِّرها حزمة تطوير البرامج (SDK) لمراقبة الأداء. بالنسبة إلى تطبيقات Android، يمكنك أيضًا مراقبة مدة طرق معيّنة باستخدام التعليقات التوضيحية@AddTrace.

انتقِل إلى مقالة إضافة ميزة تتبُّع رمز محدّد للمزيد من المعلومات عن هذه الميزات وكيفية إضافتها إلى تطبيقك.

الخطوة 6: نشر تطبيقك ثم مراجعة النتائج

بعد التحقّق من ميزة "مراقبة الأداء" باستخدام جهاز اختبار واحد أو أكثر، يمكنك نشر الإصدار المحدَّث من تطبيقك للمستخدمين.

يمكنك تتبُّع بيانات الأداء من خلال لوحة بيانات الأداء ضمن وحدة تحكُّم Firebase.

المشكلات المعروفة

  • قد يتسبب الإصدار 1.1.0 في المكوّن الإضافي "مراقبة الأداء Gradle" في عدم تطابق العناصر التابعة لأداة Grava، ما يؤدي إلى حدوث الخطأ التالي:

    Error:Execution failed for task ':app:packageInstantRunResourcesDebug'.
> com.google.common.util.concurrent.MoreExecutors.directExecutor()Ljava/util/concurrent/Executor;

    إذا ظهر لك هذا الخطأ، يمكنك إجراء أي مما يلي:

    • ترقية المكوّن الإضافي "مراقبة الأداء" إلى الإصدار 1.1.1 أو إصدار أحدث (الإصدار الأحدث هو الإصدار 1.4.2).

    • استبدِل سطر تبعية المكوّن الإضافي "تتبُّع الأداء" في ملف Gradle على مستوى الجذر (على مستوى المشروع) (<project>/build.gradle.kts أو <project>/build.gradle)، على النحو التالي:

      Kotlin 

      buildscript {
  // ...

  dependencies {
    // ...

    // Replace the standard Performance Monitoring plugin dependency line, as follows:
    classpath("com.google.firebase:perf-plugin:1.1.0") {
        exclude(group = "com.google.guava", module = "guava-jdk5")
    }
  }
}

      Groovy 

      buildscript {
  // ...

  dependencies {
    // ...

    // Replace the standard Performance Monitoring plugin dependency line, as follows:
    classpath('com.google.firebase:perf-plugin:1.1.0') {
        exclude group: 'com.google.guava', module: 'guava-jdk5'
    }
  }
}

  • تعرض "مراقبة الأداء" إجمالي حجم حمولة طلبات شبكة HTTP استنادًا إلى القيمة المحدّدة في عنوان طول محتوى HTTP. قد لا تكون هذه القيمة دقيقة دائمًا.

  • لا تتيح ميزة "مراقبة الأداء" تنفيذ العملية الرئيسية إلا في تطبيقات Android المتعدّدة العمليات.

الخطوات اللاحقة