רישום ביומן

כשמפתחים אפליקציה מכל סוג, כדאי לרשום מידע ביומן כדי לאבחן תקלות במהלך הפיתוח, לזהות ולאבחן בעיות של לקוחות ולמטרות אחרות.

יש שלושה מנגנונים שונים לרישום ביומן ב-Google Apps Script:

  • יומן הביצוע של Apps Script המובנה. היומן הזה קל משקל ומוזרם בזמן אמת, אבל הוא נשמר רק לזמן קצר.

  • ממשק Cloud Logging ב-Developer Console, שבו אפשר לראות יומנים שנשמרים למשך ימים רבים אחרי שהם נוצרו.

  • ממשק Error Reporting ב-Play Console, שמיועד לאיסוף ולתיעוד של שגיאות שמתרחשות בזמן שהסקריפט פועל.

הם מתוארים בקטעים הבאים. בנוסף למנגנונים האלה, אפשר ליצור קוד לרישום ביומן שכותב מידע לגיליון אלקטרוני או למסד נתונים של JDBC.

שימוש ביומן הביצוע של Apps Script

גישה בסיסית לרישום ביומן ב-Apps Script היא שימוש ביומן הביצוע המובנה. כדי לראות את היומנים האלה, לוחצים על יומן הביצוע בחלק העליון של העורך. כשמריצים פונקציה או משתמשים בכלי לניפוי באגים, היומנים מוצגים בזמן אמת.

אפשר להשתמש בשירותי הרישום ביומן 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

בנוסף, Apps Script מספק גישה חלקית לשירות Cloud Logging של Google Cloud. אם אתם צריכים רישום ביומן שנשמר למשך כמה ימים, או פתרון רישום ביומן מורכב יותר לסביבת ייצור מרובת משתמשים, כדאי להשתמש ב-Cloud Logging. פרטים נוספים על שמירת נתונים ומכסות אחרות זמינים במאמר מכסות ומגבלות של Cloud Logging.

כדי לבקש הגדלה של מכסת היומנים, שולחים בקשה להגדלת מכסה ב-Google Cloud. כדי לעשות זאת, צריך שתהיה לכם גישה לפרויקט Cloud Platform שבו נעשה שימוש בסקריפט.

שירות Cloud Logging מספק מספר שירותים מעבר לאחסון יומנים, כמו התראות ומדדים. השירותים האלה לא זמינים מ-Apps Script.

שימוש ב-Cloud Logging

יומני Cloud מצורפים לפרויקט Google Cloud שמשויך ל-Apps Script. אפשר לראות גרסה פשוטה של היומנים האלה בלוח הבקרה של Apps Script.

כדי להשתמש בכל האפשרויות של Cloud Logging, מומלץ להשתמש בפרויקט בענן רגיל ב-Google Cloud עם פרויקט הסקריפט. כך תוכלו לגשת ליומני Cloud ישירות ב-מסוף Google Cloud ולקבל יותר אפשרויות צפייה וסינון.

אם אתם משתמשים בזמן הריצה של Rhino, ‏ Cloud Logging לא תומך בשירות Logger של Apps Script. במקום זאת, צריך להשתמש בשירות console.

כשמתבצעת כניסה לחשבון, מומלץ להימנע מרישום פרטים אישיים של המשתמש, כמו כתובות אימייל, כדי לשמור על הפרטיות. יומני Cloud מסומנים באופן אוטומטי במפתחות של משתמשים פעילים כדי לאתר הודעות יומן של משתמש ספציפי כשצריך.

מחרוזות יומן, מחרוזות מעוצבות ואפילו אובייקטים של JSON באמצעות הפונקציות שסופקו על ידי שירות console של Apps Script.

בדוגמה הבאה מוצג אופן השימוש בשירות 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. צריך לעשות את זה רק אם פרויקט הסקריפט משתמש בפרויקט בענן רגיל ב-Google Cloud שיש לכם גישה אליו. אחרי שפותחים את פרויקט Google Cloud במסוף, בוחרים רשומה ביומן שמעניינת אתכם ומרחיבים אותה כדי לראות את metadata > labels > script.googleapis.com/user_key.

כדי לקבל את המפתח הזמני של המשתמש הפעיל, קוראים לפונקציה Session.getTemporaryActiveUserKey בסקריפט. אחת הדרכים להשתמש בשיטה הזו היא להציג את המפתח למשתמש בזמן שהוא מריץ את הסקריפט. לאחר מכן, המשתמשים יכולים לבחור לכלול את המפתחות שלהם כשמדווחים על בעיות, כדי לעזור לכם לזהות את היומנים הרלוונטיים.

רישום חריגים ביומן

רישום חריגים שולח חריגים שלא טופלו בקוד של פרויקט התסריט אל Cloud Logging, יחד עם דוח קריסות.

כדי לראות את יומני החריגים, מבצעים את השלבים הבאים:

  1. פותחים את פרויקט Apps Script.
  2. בצד ימין, לוחצים על הפעלות .
  3. למעלה, לוחצים על הוספת מסנן > סטטוס.
  4. מסמנים את תיבות הסימון נכשל ופסק זמן.

אם פרויקט התסריט שלכם משתמש בפרויקט רגיל ב-Google Cloud שיש לכם גישה אליו, תוכלו לראות את החריגים שנרשמו ביומן במסוף Google Cloud.

הפעלת רישום חריגים ביומן

רישום ביומן של חריגים מופעל כברירת מחדל בפרויקטים חדשים. כדי להפעיל רישום ביומן של חריגים בפרויקטים ישנים יותר, פועלים לפי השלבים הבאים:

  1. פותחים את פרויקט הסקריפט.
  2. בצד ימין, לוחצים על הגדרות הפרויקט .
  3. מסמנים את תיבת הסימון Log uncaught exceptions to Cloud Operations.

Error Reporting

רישום חריגים ביומן משתלב אוטומטית עם Cloud Error Reporting, שירות שמצטבר ומציג שגיאות שנוצרו בסקריפט. אפשר לראות את דוחות השגיאות ב-Cloud במסוף Google Cloud. אין צורך להגדיר ידנית את דיווח השגיאות או ליצור רשומות מעקב. ‫Apps Script מאכלס באופן אוטומטי את השדות הנדרשים כשמופעלת חריגה או כשמשתמשים ב-console.error עם אובייקט Error. אם מוצגת ההודעה "צריך להגדיר דיווח על שגיאות", המשמעות היא שעדיין לא נרשמו חריגים בסקריפט. לא נדרש שום הגדרה מעבר להפעלת רישום חריגים.

דרישות לגבי רישום ביומן

אין דרישות לשימוש ביומן הביצוע המובנה.

אפשר לראות גרסה פשוטה של יומני Cloud במרכז הבקרה של Apps Script. עם זאת, כדי להפיק את המרב מ-Cloud Logging ומדיווח השגיאות, צריך גישה לפרויקט בענן של הסקריפט ב-Google Cloud. אפשר לעשות את זה רק אם בפרויקט של הסקריפט נעשה שימוש בפרויקט בענן רגיל ב-Google.