日志记录

在开发任何类型的应用时，记录信息有助于在开发期间诊断故障、识别和诊断客户问题，以及用于其他用途。

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

  • 内置的 Apps 脚本执行日志。 此日志轻量级且实时流式传输，但仅保留很短的时间。

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

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

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

使用 Apps 脚本执行日志

在 Apps 脚本中进行日志记录的基本方法是使用内置的执行日志。如需查看这些日志，请点击编辑器顶部的执行日志。当您运行函数或使用调试程序时，日志会实时显示。

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

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

除了存储日志之外，Cloud Logging 还提供许多其他服务，例如提醒和指标。这些服务无法通过 Apps 脚本使用。

使用 Cloud Logging

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

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

如果您使用 Rhino 运行时，Cloud Logging 不支持 Apps 脚本 Logger 服务。请改用 console 服务。

在记录日志时，为保护隐私，最好避免记录任何与用户相关的个人信息，例如电子邮件地址。云日志会自动标记有效用户密钥，以便在必要时找到特定用户的日志消息。

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

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

临时活跃用户密钥优于电子邮件地址等登录标识符，原因如下：

  • 您无需向日志记录添加任何内容，它们已存在于日志记录中！
  • 它们不需要用户授权。
  • 它们可以保护用户隐私。

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

如需获取临时有效用户密钥，请在脚本中调用 Session.getTemporaryActiveUserKey。使用此方法的一种方式是在用户运行脚本时向其显示密钥。然后，用户可以选择在报告问题时附上其密钥，以帮助您识别相关日志。

异常日志记录

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

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

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

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

启用异常日志记录

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

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

Error Reporting

异常日志记录会自动与 Cloud Error Reporting 集成，后者可汇总并显示脚本中产生的错误。在 Google Cloud 控制台中查看 Cloud 错误报告。您无需手动配置错误报告或创建轨迹条目。当抛出异常或您将 console.error 与 Error 对象搭配使用时，Apps 脚本会自动填充必需字段。如果您收到“设置错误报告”提示，则表示您的脚本尚未记录任何异常。除了启用异常日志记录之外，您无需执行任何设置。

日志记录要求

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

在 Apps 脚本信息中心中查看简化版 Cloud 日志。不过，为了充分利用 Cloud Logging 和错误报告，您必须有权访问脚本的 Google Cloud 项目。只有当脚本项目使用标准 Google Cloud 项目时，才能执行此操作。