רישום

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

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

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

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

  • ממשק דיווח השגיאות ב-Developer 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);
  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

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

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

שימוש ב-Cloud Logging

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

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

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

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

בדוגמה הבאה מוצג אופן השימוש בשירות console כדי לרשום מידע ב-Cloud Operations.

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, צופים ביומני 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 רגיל שיש לכם גישה אליו, אתם יכולים גם לראות את החריגים שנרשמו במסוף GCP.

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

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

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

Error Reporting

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

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

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

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