كتابة السجلّات وعرضها

التسجيل أداة مهمة لتصحيح الأخطاء في الرمز البرمجي ومراقبته. تمنحك السمة Cloud Functions خيار استخدام حزمة تطوير البرامج (SDK) الخاصة بمسجّل البيانات في Node.js أو Python، أو معيار العنصر console للتطوير على الويب.

‫Cloud Logging هي خدمة خاضعة للرسوم، وقد يتم تحصيل رسوم منك إذا تجاوزت الحصة المجانية. لمزيد من المعلومات، اطّلِع على أسعار Cloud Logging.

كتابة السجلات

استخدام حزمة تطوير البرامج (SDK) الخاصة بأداة تسجيل الأحداث Cloud Functions

توفّر حزمة تطوير البرامج (SDK) الخاصة بمسجّل Cloud Functions واجهة عادية للإبلاغ عن الحالة من الدوال إلى Cloud Logging. يمكنك استخدام حزمة تطوير البرامج (SDK) هذه لتسجيل الأحداث باستخدام بيانات منظَّمة، ما يتيح إجراء التحليل والمراقبة بسهولة أكبر.

استيراد من الحزمة الفرعية logger:

Node.js

// All available logging functions
const {
  log,
  info,
  debug,
  warn,
  error,
  write,
} = require("firebase-functions/logger");
index.js

Python

from firebase_functions import logger
main.py

  • تتضمّن أوامر logger.log() مستوى السجلّ INFO.

  • تتضمّن أوامر logger.info() مستوى السجلّ INFO.

  • تتضمّن أوامر logger.warn() مستوى السجلّ WARNING.

  • تحتوي أوامر logger.error() على مستوى التسجيل ERROR.

  • تتضمّن أوامر logger.debug() مستوى السجلّ DEBUG.

  • تكون رسائل النظام الداخلية بمستوى سجلّ تصحيح الأخطاء.

يوضّح هذا المثال دالة تكتب سجلًّا أساسيًا:

Node.js

exports.helloWorld = onRequest((request, response) => {
  // sends a log to Cloud Logging
  log("Hello logs!");

  response.send("Hello from Firebase!");
});
index.js

Python

@https_fn.on_request()
def hello_world(req: https_fn.Request) -> https_fn.Response:
    # sends a log to Cloud Logging
    logger.log("Hello logs!")

    return https_fn.Response("Hello from Firebase!")
main.py

استخدِم مستويات سجلّ مختلفة لأنواع مختلفة من السجلات في رمز الدالة. يمكن إرفاق البيانات المنظَّمة بسجلّ كآخر وسيطة. في ما يلي مثال على كيفية استخدام الدالة لكل نوع من أنواع السجلّات:

Node.js

exports.getInspirationalQuote = onRequest(async (request, response) => {
  const db = getFirestore();
  const today = new Date();
  const quoteOfTheMonthRef = db
      .collection("quotes")
      .doc(`${today.getFullYear()}`)
      .collection("months")
      .doc(`${today.getMonth()}`);

  const DEFAULT_QUOTE =
      "You miss 100% of the shots you don't take. -Wayne Gretzky";
  let quote;
  try {
    const quoteOfTheMonthDocSnap = await quoteOfTheMonthRef.get();

    // Attach relevant debugging information with debug()
    debug("Monthly quote fetch result", {
      docRef: quoteOfTheMonthRef.path,
      exists: quoteOfTheMonthDocSnap.exists,
      createTime: quoteOfTheMonthDocSnap.createTime,
    });

    if (quoteOfTheMonthDocSnap.exists) {
      quote = quoteOfTheMonthDocSnap.data().text;
    } else {
      // Use warn() for lower-severity issues than error()
      warn("Quote not found for month, sending default instead", {
        docRef: quoteOfTheMonthRef.path,
        dateRequested: today.toLocaleDateString("en-US"),
      });

      quote = DEFAULT_QUOTE;
    }
  } catch (err) {
    // Attach an error object as the second argument
    error("Unable to read quote from Firestore, sending default instead",
        err);

    quote = DEFAULT_QUOTE;
  }

  // Attach relevant structured data to any log
  info("Sending a quote!", {quote: quote});
  response.json({inspirationalQuote: quote});
});
index.js

Python

@https_fn.on_request()
def get_inspirational_quote(req: https_fn.Request) -> https_fn.Response:
    firestore_client = firestore.client()
    today = datetime.date.today()
    quote_of_the_month_ref = (firestore_client.collection("quotes").doc(str(
        today.year)).collection("months").doc(str(today.month)))

    default_quote = "Python has been an important part of Google since the beginning, and remains so as the system grows and evolves."

    quote = None
    try:
        quote_of_the_month = quote_of_the_month_ref.get()

        # Attach relevant debugging information with debug()
        logger.debug(
            "Monthly quote fetch result",
            docRef=quote_of_the_month.path,
            exists=quote_of_the_month.exists,
            createTime=quote_of_the_month.createTime,
        )

        if quote_of_the_month.exists:
            quote = quote_of_the_month.to_dict()["text"]
        else:
            # Use warn() for lower-severity issues than error()
            logger.warn(
                "Quote not found for month, sending default instead",
                doc_reference=quote_of_the_month.path,
                date_requested=today.strftime("%Y-%m-%d"),
            )
            quote = default_quote
    except:
        e = sys.exc_info()[0]
        # Attach an error object as the second argument
        logger.error("Unable to read quote from Firestore, sending default instead", error=e)
        quote = default_quote

    # Attach relevant structured data to any log
    logger.info("Sending a quote!", quote=quote)
    return https_fn.Response("Hello from Firebase!")
main.py

باستخدام logger.write()، يمكنك كتابة إدخالات السجل بمستويات خطورة إضافية للسجل وهي CRITICAL وALERT وEMERGENCY. راجِع LogSeverity.

Node.js

exports.appHasARegression = onRegressionAlertPublished((event) => {
  write({
    // write() lets you set additional severity levels
    // beyond the built-in logger functions
    severity: "EMERGENCY",
    message: "Regression in production app",
    issue: event.data.payload.issue,
    lastOccurred: event.data.payload.resolveTime,
  });
});
index.js

Python

@crashlytics_fn.on_regression_alert_published()
def app_has_regression(alert: crashlytics_fn.CrashlyticsRegressionAlertEvent) -> None:
    logger.write(
        severity="EMERGENCY",
        message="Regression in production app",
        issue=alert.data.payload.issue,
        last_occurred=alert.data.payload.resolve_time,
    )
    print(alert)
main.py

جارٍ استخدام console.log

الحلّ المقترَح لتسجيل البيانات من دالة هو استخدام حزمة تطوير البرامج (SDK) الخاصة بتسجيل البيانات في منصتك. باستخدام Node.js، يمكنك بدلاً من ذلك استخدام طلبات تسجيل JavaScript العادية، مثل console.log وconsole.error، ولكن عليك أولاً طلب وحدة خاصة لتعديل الطرق العادية لتعمل بشكل صحيح:

require("firebase-functions/logger/compat");

بعد الحصول على وحدة توافق أداة تسجيل البيانات المطلوبة، يمكنك استخدام طرق console.log() كالمعتاد في الرمز البرمجي:

exports.helloError = functions.https.onRequest((request, response) => {
  console.log('I am a log entry!');
  response.send('Hello World...');
});
index.js
  • تتضمّن أوامر console.log() مستوى السجلّ INFO.
  • تتضمّن أوامر console.info() مستوى السجلّ INFO.
  • تحتوي أوامر console.warn() على مستوى التسجيل ERROR.
  • تحتوي أوامر console.error() على مستوى التسجيل ERROR.
  • تكون رسائل النظام الداخلية بمستوى سجلّ تصحيح الأخطاء.

عرض السجلّات

يمكن الاطّلاع على سجلّات Cloud Functions إما في وحدة تحكّم Google Cloud أو في واجهة مستخدم Cloud Logging أو من خلال أداة سطر الأوامر firebase.

استخدام Firebase CLI

لعرض السجلات باستخدام أداة firebase، استخدِم الأمر functions:log:

firebase functions:log

لعرض سجلّات دالة معيّنة، قدِّم اسم الدالة كوسيطة:

firebase functions:log --only <FUNCTION_NAME>

للاطّلاع على المجموعة الكاملة من خيارات عرض السجلّ، يُرجى الاطّلاع على المساعدة في functions:log:

firebase help functions:log

استخدام وحدة تحكّم Google Cloud

يمكنك عرض سجلّات الدوال في وحدة تحكّم Google Cloud.

استخدام واجهة مستخدم Cloud Logging

يمكنك الاطّلاع على سجلّات Cloud Functions في واجهة مستخدم Cloud Logging.

تحليل السجلات

توفّر Cloud Logging حزمة فعّالة من أدوات تحليل السجلات التي يمكنك استخدامها لمراقبة Cloud Functions.

الرسومات البيانية والتنبيهات

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

راجِع إنشاء رسوم بيانية وتنبيهات للحصول على معلومات مفصّلة حول كيفية استخدام المقاييس المستندة إلى السجلّات في الرسوم البيانية وسياسات التنبيه.

فهم معرّفات التنفيذ واستخدامها

تتيح "وظائف Cloud Run" (الجيل الثاني) تلقائيًا التنفيذ المتزامن لطلبات متعددة ضمن مثيل دالة واحد. وهذا يعني أنّه يمكن دمج السجلات من طلبات مختلفة، ما يصعّب تتبُّع تسلسل عملية تنفيذ واحدة.

للمساعدة في ذلك، يتم تلقائيًا نشر الدوال التي تم نشرها باستخدام الإصدار 13.33.0 من Firebase CLI والإصدارات الأحدث مع خيار ربط رقم تعريف التنفيذ بكل إدخال سجلّ تم إصداره أثناء معالجة هذا التنفيذ.

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

لإيقاف معرّف التنفيذ في إدخالات السجلّ، اضبط متغيّر البيئة LOG_EXECUTION_ID على false في ملف dotenv.

العثور على السجلات وربطها حسب معرّف التنفيذ

يمكنك فحص السجلات وربطها برقم تعريف التنفيذ في "مستكشف سجلات Cloud".

  1. وسِّع إدخال السجلّ من الدالة. يمكن العثور على معرّف التنفيذ ضمن بيانات السجلّ المنظَّمة، والمضمّنة تحت التصنيفات كـ labels.execution_id.

  2. انقر على قيمة execution_id واختَر "عرض الإدخالات المطابقة" من القائمة المنسدلة للاطّلاع على جميع السجلات الأخرى المرتبطة بتنفيذ الدالة نفسه.

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

تحسين إمكانية الاطّلاع على السجلّ باستخدام حقول الملخّص المخصّصة

لإتاحة عرض معرّف التنفيذ بشكل أسهل في "مستكشف السجلات"، يمكنك إضافته كـ [حقل ملخّص مخصّص][cloud-logging-preference]. بعد إضافة رقم تعريف التنفيذ كحقل ملخّص، سيعرض كل إدخال في السجلّ رقم تعريف التنفيذ كشريحة في بداية سطر السجلّ، على غرار الطريقة التي كانت تعرض بها وظائف الجيل الأول رقم تعريف التنفيذ لجميع إدخالات السجلّ.

لإضافة رقم تعريف التنفيذ إلى حقل الملخّص:

  1. انقر على قيمة رقم تعريف التنفيذ في إدخال السجل المنظَّم ضمن labels.execution_id.

  2. اختَر "إضافة حقل إلى سطر الملخّص" من القائمة المنسدلة.

يعرض كل إدخال في السجلّ الآن executionId بشكل بارز في حقل الملخّص، ما يسهّل تحديد السجلّات المرتبطة بمعرّف تنفيذ معيّن وتجميعها.