日志记录

在开发任何类型的应用时，您通常需要记录信息，以便在开发过程中诊断故障、识别和诊断客户问题，以及用于其他用途。

Apps 脚本提供了三种不同的日志记录机制：

  • 内置的 Apps 脚本执行日志。此日志轻量且实时流式传输，但只会保留一小段时间。

  • 开发者控制台中的 Cloud Logging 界面，该界面提供的日志会在创建后保留数天。

  • 开发者控制台中的 Error Reporting 界面，用于收集和记录脚本运行期间发生的错误。

以下部分介绍了这些方法。除了这些机制之外，您还可以构建自己的日志记录器代码，例如将信息写入日志记录电子表格或 JDBC 数据库。

使用 Apps 脚本执行日志

在 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 还提供对 Google Cloud Platform (GCP) Cloud Logging 服务的部分访问权限。如果您需要持续数天的日志记录，或者需要为多用户生产环境提供更复杂的日志记录解决方案，Cloud Logging 是首选。如需了解数据保留和其他配额详情，请参阅 Cloud Logging 配额和限制。

如果您需要更多日志记录配额，可以提交 Google Cloud Platform 配额请求。这需要您有权访问脚本使用的 Cloud Platform 项目。

使用 Cloud Logging

Cloud 日志会附加到与您的 Apps 脚本关联的 Google Cloud 项目。您可以在 Apps Script 信息中心中查看这些日志的简化版本。

如需充分利用 Cloud Logging 及其功能，请将标准 Google Cloud 项目与脚本项目搭配使用。这样，您就可以直接在 GCP 控制台中访问 Cloud 日志，并获得更多查看和过滤选项。

在记录日志时，为了保护用户隐私，请避免记录用户的任何个人信息，例如电子邮件地址。Cloud 日志会自动标记为活跃用户键，您可在必要时使用这些键来查找特定用户的日志消息。

您可以使用 Apps Script console 服务提供的函数记录字符串、格式化字符串，甚至 JSON 对象。

以下示例展示了如何使用 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 日志条目中发现唯一用户，而无需泄露这些用户的身份。密钥是按脚本分配的，大约每月更改一次，以便在用户向开发者（例如在报告问题时）透露其身份时提供额外的安全保护。

临时活跃用户键优于电子邮件地址等日志记录标识符，因为：

  • 您无需向日志记录添加任何内容，因为这些信息已经存在！
  • 无需用户授权。
  • 它们可保护用户隐私。

如需在 Cloud Logging 条目中查找有效的临时用户密钥，请在 Google Cloud 控制台中查看 Cloud 日志。只有当您的脚本项目使用您有权访问的标准 Google Cloud 项目时，您才能执行此操作。在控制台中打开 Google Cloud 项目后，选择感兴趣的日志条目并将其展开，以查看元数据 > 标签 > script.googleapis.com/user_key。

您还可以在脚本中调用 Session.getTemporaryActiveUserKey() 来获取临时有效用户键。使用此方法的一种方法是在用户运行脚本时向其显示密钥。然后，用户在报告问题时可以选择添加其密钥，以便您识别相关日志。

异常日志记录

异常日志记录会将脚本项目代码中的未处理异常以及堆栈轨迹发送到 Cloud Logging。

如需查看异常日志，请按以下步骤操作：

  1. 打开 Apps 脚本项目。
  2. 点击左侧的执行 。
  3. 依次点击顶部的添加过滤条件 > 状态。
  4. 选中失败和超时复选框。

如果您的脚本项目使用的是您有权访问的标准 Google Cloud 项目，您还可以在 GCP 控制台中查看已记录的异常。

启用异常日志记录

默认情况下，新项目会启用异常日志记录功能。如需为旧版项目启用异常日志记录，请按以下步骤操作：

  1. 打开脚本项目。
  2. 点击左侧的项目设置图标 。
  3. 选中将未捕获到的异常记录到 Cloud Operations 复选框。

Error Reporting

异常日志记录功能会自动与 Cloud Error Reporting 集成，该服务可汇总并显示脚本中产生的错误。您可以在 Google Cloud 控制台中查看 Cloud 错误报告。如果系统提示您“设置错误报告”，则表示您的脚本尚未记录任何异常。除了启用异常日志记录之外，您无需执行任何设置。

日志记录要求

使用内置执行日志没有任何要求。

您可以在 Apps Script 信息中心查看简化版 Cloud 日志。不过，若要充分利用 Cloud Logging 和错误报告功能，您必须有权访问脚本的 GCP 项目。只有当您的脚本项目使用标准 Google Cloud 项目时，才能实现此目的。