جارٍ التسجيل

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

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

  • سجل تنفيذ برمجة التطبيقات المضمن. هذا السجل خفيف ويتم بثه في الوقت الفعلي، ولكنه لا يستمر إلا لفترة قصيرة.

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

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

يتم توضيح ذلك في الأقسام التالية. بالإضافة إلى هذه الآليات، يمكنك أيضًا إنشاء رمز المسجل الخاص بك، والذي، على سبيل المثال، يكتب المعلومات إلى جدول بيانات تسجيل أو قاعدة بيانات 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);
  try {
    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);
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log('Failed with error %s', err.message);
  }
}

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

[16-09-12 13:50:42:193 PDT] إرسال بيانات الصف 2 بالبريد الإلكتروني إلى john@example.com
[16-09-12 13:50:42:271 PDT] بيانات الصف 2: التكلفة 103.24

Cloud Logging

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

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

استخدام تسجيل الدخول إلى السحابة الإلكترونية

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

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

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

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

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

utils/logging.gs
/**
 * 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 Log بدون الكشف عن هويات هؤلاء المستخدمين. ويتم تغيير المفاتيح لكل نص برمجي ويتم تغييرها مرة واحدة في الشهر تقريبًا لتوفير أمان إضافي في حال كشف المستخدم عن هويته لمطوّر البرامج، مثلاً أثناء الإبلاغ عن مشكلة.

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

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

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

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

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

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

اتبع الخطوات التالية لعرض سجلات الاستثناء:

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

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

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

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

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

Error Reporting

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

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

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

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