التسجيل

عند تطوير أي نوع من التطبيقات، يتم تسجيل المعلومات للمساعدة في تشخيص الأخطاء أثناء عملية التطوير، ولتحديد مشاكل العملاء وتشخيصها، ولأغراض أخرى.

توفّر برمجة تطبيقات Google ثلاث آليات مختلفة لتسجيل البيانات:

  • سجلّ تنفيذ "برمجة تطبيقات Google" المضمّن هذا السجلّ صغير الحجم ويتم بثّه في الوقت الفعلي، ولكنّه لا يبقى متاحًا إلا لفترة قصيرة.

  • واجهة Cloud Logging في Play Console، والتي توفّر سجلات تظل متاحة لعدة أيام بعد إنشائها

  • واجهة Error Reporting في "وحدة تحكّم المطوّر"، التي تجمع الأخطاء التي تحدث أثناء تشغيل البرنامج النصي وتسجّلها.

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

استخدام سجلّ تنفيذ برمجة تطبيقات

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

استخدِم إما خدمة تسجيل الدخول Logger أو console في سجلّ التنفيذ المضمّن.

هذه السجلات مخصّصة لعمليات التحقّق أثناء التطوير وتصحيح الأخطاء، ولا يتم الاحتفاظ بها لفترة طويلة.

على سبيل المثال، ضع في اعتبارك الدالة التالية:

utils/logging.gs
/**
 * Logs Google Sheet information.
 * @param {number} rowNumber The spreadsheet row number.
 * @param {string} email The email to send with the row data.
 */
function emailDataRow(rowNumber, email) {
  console.log(`Emailing data row ${rowNumber} to ${email}`);
  const sheet = SpreadsheetApp.getActiveSheet();
  const data = sheet.getDataRange().getValues();
  const rowData = data[rowNumber - 1].join(" ");
  console.log(`Row ${rowNumber} data: ${rowData}`);
  MailApp.sendEmail(email, `Data in row ${rowNumber}`, rowData);
}

عند تشغيل هذا النص البرمجي مع الإدخالين "2" و "john@example.com"، يتم تسجيل البيانات التالية:

> [16-09-12 13:50:42:193 PDT] Emailing data row 2 to john@example.com
> [16-09-12 13:50:42:271 PDT] Row 2 data: Cost 103.24

Cloud Logging

توفّر "برمجة التطبيقات" أيضًا إمكانية الوصول الجزئي إلى خدمة Cloud Logging من Google Cloud. عندما تحتاج إلى تسجيل بيانات يستمر لعدة أيام، أو تحتاج إلى حلّ أكثر تعقيدًا لتسجيل البيانات في بيئة إنتاج متعددة المستخدمين، يكون Cloud Logging هو الخيار المفضّل. راجِع حصص Cloud Logging وحدودها للاطّلاع على تفاصيل حول الاحتفاظ بالبيانات والحصص الأخرى.

لطلب المزيد من حصة التسجيل، أرسِل طلب حصة في Google Cloud. ويتطلّب ذلك أن يكون لديك إذن الوصول إلى مشروع Cloud Platform الذي يستخدمه النص البرمجي.

توفّر Cloud Logging عددًا من الخدمات بالإضافة إلى تخزين السجلّات، مثل التنبيهات والمقاييس. لا تتوفّر هذه الخدمات من خلال برمجة تطبيقات.

استخدام Cloud Logging

يتم إرفاق سجلّات Cloud بمشروع Google Cloud المرتبط ببرمجة تطبيقات. يمكنك الاطّلاع على نسخة مبسطة من هذه السجلات في لوحة بيانات "برمجة تطبيقات Google".

للاستفادة بشكل كامل من Cloud Logging وإمكاناتها، استخدِم مشروعًا عاديًا على Google Cloud مع مشروع النص البرمجي. يتيح لك ذلك الوصول إلى سجلّات Cloud مباشرةً في Google Cloud Console، كما يوفّر لك المزيد من خيارات العرض والفلترة.

إذا كنت تستخدم وقت تشغيل Rhino، لا تتيح خدمة Cloud Logging استخدام خدمة Logger في "برمجة التطبيقات". يمكنك بدلاً من ذلك استخدام خدمة console.

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

يمكنك تسجيل سلاسل السجلّ وسلاسل التنسيق وحتى عناصر JSON باستخدام الدوال التي توفّرها خدمة console في "برمجة تطبيقات Google".

يوضّح المثال التالي كيفية استخدام خدمة console لتسجيل المعلومات في Cloud Operations.

utils/logging.gs
/**
 * A placeholder function to be timed.
 * @param {Object} parameters
 */
function myFunction(parameters) {
  // Placeholder for the function being timed.
}

/**
 * Logs the time taken to execute 'myFunction'.
 */
function measuringExecutionTime() {
  // A simple INFO log message, using sprintf() formatting.
  console.info("Timing the %s function (%d arguments)", "myFunction", 1);

  // Log a JSON object at a DEBUG level. The log is labeled
  // with the message string in the log viewer, and the JSON content
  // is displayed in the expanded log structure under "jsonPayload".
  const parameters = {
    isValid: true,
    content: "some string",
    timestamp: new Date(),
  };
  console.log({ message: "Function Input", initialData: parameters });
  const label = "myFunction() time"; // Labels the timing log entry.
  console.time(label); // Starts the timer.
  try {
    myFunction(parameters); // Function to time.
  } catch (e) {
    // Logs an ERROR message.
    console.error(`myFunction() yielded an error: ${e}`);
  }
  console.timeEnd(label); // Stops the timer, logs execution duration.
}

مفاتيح المستخدمين النشطين

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

تتفوق مفاتيح المستخدمين النشطين المؤقتة على معرّفات التسجيل، مثل عناوين البريد الإلكتروني، للأسباب التالية:

  • ليس عليك إضافة أي شيء إلى سجلّاتك، فهي متوفّرة فيها.
  • ولا تتطلّب تفويض المستخدم.
  • أن تحمي خصوصية المستخدمين

للعثور على مفاتيح المستخدمين النشطين المؤقتة في إدخالات سجلّات Cloud، يمكنك عرض سجلّات Cloud في Google Cloud Console. يجب إجراء ذلك فقط إذا كان مشروع النص البرمجي يستخدم مشروعًا عاديًا على Google Cloud يمكنك الوصول إليه. بعد فتح مشروع على السحابة الإلكترونية في Google Cloud في وحدة التحكّم، اختَر إدخال في السجلّ يهمّك ووسِّعه لعرض البيانات الوصفية > التصنيفات > script.googleapis.com/user_key.

للحصول على مفتاح المستخدم النشط المؤقت، استدعِ الدالة Session.getTemporaryActiveUserKey في النص البرمجي. إحدى طرق استخدام هذه الطريقة هي عرض المفتاح للمستخدم أثناء تشغيل النص البرمجي. بعد ذلك، يمكن للمستخدمين اختيار تضمين مفاتيحهم عند الإبلاغ عن المشاكل لمساعدتك في تحديد السجلات ذات الصلة.

تسجيل الاستثناءات

تسجّل ميزة تسجيل الاستثناءات الاستثناءات غير المعالَجة في رمز مشروع النص البرمجي في Cloud Logging، بالإضافة إلى تتبُّع تسلسل استدعاء الدوال البرمجية.

لعرض سجلّات الأخطاء، اتّبِع الخطوات التالية:

  1. افتح مشروع برمجة تطبيقات.
  2. على يمين الصفحة، انقر على عمليات التنفيذ .
  3. في أعلى الصفحة، انقر على إضافة فلتر > الحالة.
  4. ضَع علامة في مربّعَي الاختيار تعذّر وانتهت المهلة.

يمكنك عرض الاستثناءات المسجّلة في وحدة تحكّم Google Cloud إذا كان مشروع البرنامج النصي يستخدم مشروع على السحابة الإلكترونية عاديًا يمكنك الوصول إليه.

تفعيل تسجيل الاستثناءات

يتم تفعيل تسجيل الأخطاء تلقائيًا للمشاريع الجديدة. لتفعيل تسجيل الأخطاء في المشاريع القديمة، اتّبِع الخطوات التالية:

  1. افتح مشروع النص البرمجي.
  2. على يمين الصفحة، انقر على إعدادات المشروع .
  3. ضَع علامة في مربّع الاختيار تسجيل الاستثناءات غير المرصودة في Cloud Operations.

Error Reporting

يتم دمج تسجيل الأخطاء تلقائيًا مع Cloud Error Reporting، وهي خدمة تجمع الأخطاء التي تم إنتاجها في النص البرمجي وتعرضها. يمكنك عرض تقارير أخطاء Cloud في Google Cloud Console. لست بحاجة إلى إعداد ميزة "إعداد تقارير الأخطاء" يدويًا أو إنشاء إدخالات تتبُّع. تعبئ برمجة تطبيقات تلقائيًا الحقول المطلوبة عند طرح استثناء أو عند استخدام console.error مع عنصر Error. إذا طُلب منك "إعداد ميزة إعداد التقارير عن الأخطاء"، يعني ذلك أنّ البرنامج النصي لم يسجّل أي استثناءات بعد. لا يلزم إجراء أي عملية إعداد بخلاف تفعيل تسجيل الاستثناءات.

متطلبات التسجيل

لا توجد متطلبات لاستخدام سجلّ التنفيذ المضمّن.

عرض نسخة مبسطة من سجلات Cloud في لوحة بيانات "برمجة تطبيقات Google" ومع ذلك، للاستفادة إلى أقصى حد من Cloud Logging وError Reporting، يجب أن يكون لديك إذن الوصول إلى مشروع Google Cloud الخاص بالنص البرمجي. لا يمكن إجراء ذلك إلا إذا كان مشروع النص البرمجي يستخدم مشروعًا عاديًا على Google Cloud.