نوشتن و مشاهده گزارش‌ها

گزارش‌گیری ابزار مهمی برای اشکال‌زدایی و نظارت بر کد است. Cloud Functions به شما این امکان را می‌دهد که از کیت توسعه نرم‌افزار ثبت‌کننده برای Node.js یا Python، یا استاندارد شیء console برای توسعه وب استفاده کنید.

Cloud Logging سرویسی هزینه‌دار است؛ اگر از سهمیه رایگان فراتر بروید، ممکن است برایتان صورت‌حساب صادر شود. برای اطلاعات بیشتر، به قیمت‌گذاری Cloud Logging مراجعه کنید.

درحال نوشتن گزارش‌ها

استفاده از کیت توسعه نرم‌افزار ثبت‌کننده Cloud Functions

کیت توسعه نرم‌افزار ثبت‌کننده Cloud Functions میانای استانداردی برای گزارش وضعیت از توابع به Cloud Logging ارائه می‌دهد. می‌توانید از این کیت توسعه نرم‌افزار برای ثبت رویدادها با داده‌های ساختاریافته استفاده کنید، که تجزیه‌وتحلیل و پایش را آسان‌تر می‌کند.

وارد کردن از زیربسته logger:

Node.js

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

پایتون

from firebase_functions import logger

  • فرمان‌های logger.log() دارای سطح گزارش INFO هستند.

  • logger.info() فرمان دارای سطح گزارش INFO است.

  • logger.warn() فرمان دارای سطح گزارش هشدار است.

  • ‫logger.error() فرمان دارای سطح گزارش ERROR است.

  • logger.debug() فرمان دارای سطح گزارش اشکال‌زدایی است.

  • پیام‌های سیستم داخلی دارای سطح گزارش اشکال‌زدایی هستند.

این مثال تابعی را نشان می‌دهد که یک گزارش ساده می‌نویسد:

Node.js

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

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

پایتون

@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!")

از سطوح گزارش متفاوت برای انواع مختلف گزارش در کد تابع خود استفاده کنید. داده‌های ساختاریافته را می‌توان به‌عنوان آخرین آرگومان به گزارش پیوست کرد. در اینجا نمونه‌ای از نحوه استفاده تابع از هر نوع گزارش آورده شده است:

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});
});

پایتون

@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!")

با 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,
  });
});

پایتون

@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)

استفاده از console.log

راه‌حل توصیه‌شده برای ثبت گزارش از تابع، استفاده از کیت توسعه نرم‌افزار ثبت‌کننده گزارش برای پلاتفرم شما است. با Node.js، می‌توانید به‌جای آن از فراخوانی‌های استاندارد ثبت گزارش جاوا اسکریپت مثل 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...');
});
  • فرمان‌های console.log() دارای سطح گزارش INFO هستند.
  • فرمان‌های console.info() دارای سطح گزارش INFO هستند.
  • ‫console.warn() فرمان دارای سطح گزارش ERROR است.
  • ‫console.error() فرمان دارای سطح گزارش خطا است.
  • پیام‌های سیستم داخلی دارای سطح گزارش اشکال‌زدایی هستند.

مشاهده گزارش‌ها

گزارش‌های Cloud Functions در کنسول Google Cloud، رابط کاربری Cloud Logging، یا ازطریق ابزار خط فرمان firebase قابل‌مشاهده است.

استفاده از واسط خط فرمان Firebase

برای مشاهده گزارش‌ها با ابزار 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 (نسل دوم) از اجرای هم‌زمان چند درخواست در یک نمونه تابع پشتیبانی می‌کند. این یعنی گزارش‌های درخواست‌های مختلف می‌توانند درهم‌تنیده شوند و دنبال کردن جریان یک اجرای واحد را دشوارتر کنند.

برای کمک به این موضوع، توابع مستقرشده بااستفاده از «واسط خط فرمان Firebase» نسخه ۱۳.۳۳.۰ و جدیدتر به‌طور خودکار با گزینه‌ای برای مرتبط کردن شناسه اجرا با هر ورودی گزارش منتشرشده درطول رسیدگی به آن اجرا مستقر می‌شوند.

شناسه اجرا به‌طور منحصربه‌فرد همه گزارش‌های مرتبط با یک درخواست را که توسط تابع شما مدیریت می‌شود شناسایی می‌کند. نیازی به تغییر کد نیست؛ شناسه اجرا به‌طور خودکار به گزارش‌هایتان اضافه خواهد شد.

برای غیرفعال کردن ثبت شناسه اجرا در ورودی‌های گزارش، متغیر محیطی LOG_EXECUTION_ID را در فایل dotenv خود روی false تنظیم کنید.

پیدا کردن و همبسته کردن گزارش‌ها براساس شناسه اجرا

می‌توانید گزارش‌ها را براساس شناسه اجرا در Cloud Logs Explorer بازرسی و همبسته کنید.

  1. ورودی گزارش را از تابع خود ازهم باز کنید. شناسه اجرا در داده‌های گزارش ساختاریافته قرار دارد و در برچسب‌ها به‌عنوان labels.execution_id قرار گرفته است.

  2. روی مقدار execution_id کلیک کنید و «نمایش ورودی‌های منطبق» را از منوِ کرکره‌ای انتخاب کنید تا همه گزارش‌های دیگر مرتبط با همان اجرای تابع را ببینید.

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

بهبود نمایان بودن گزارش با فیلدهای خلاصه سفارشی

برای اینکه شناسه اجرا در «کاوشگر گزارش‌ها» راحت‌تر دیده شود، می‌توانید آن را به‌عنوان [فیلد خلاصه سفارشی][cloud-logging-preference] اضافه کنید. پس‌از اینکه شناسه اجرا را به‌عنوان فیلد خلاصه اضافه کردید، هر ورودی گزارش، شناسه اجرا را به‌عنوان تراشه‌ای در ابتدای خط گزارش نشان می‌دهد، مشابه روشی که توابع نسل اول شناسه اجرا را برای همه ورودی‌های گزارش نشان می‌دادند.

برای افزودن شناسه اجرا به فیلد خلاصه:

  1. روی مقدار شناسه اجرا در ورودی گزارش ساختاریافته در زیر labels.execution_id کلیک کنید.

  2. «افزودن فیلد به خط خلاصه» را از منوِ کرکره‌ای انتخاب کنید.

اکنون هر ورودی گزارش executionId را به‌طور برجسته در فیلد خلاصه نمایش می‌دهد، که شناسایی و گروه‌بندی گزارش‌های مرتبط با شناسه اجرای خاص را آسان‌تر می‌کند.