日志记录

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

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

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

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

• 开发者控制台中的 Error Reporting 界面， 该界面会收集并记录脚本运行时发生的错误。

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

使用 Apps 脚本执行日志

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

在 内置执行日志中使用 Logger 或 console 日志记录服务。

这些日志旨在用于开发和调试期间的检查，不会保留很长时间。

例如，请考虑以下函数：

utils/logging.gs

在 GitHub 上查看

/**
 * 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”和“[e-mail]”运行时，系统会写入以下日志：

> [16-09-12 13:50:42:193 PDT] Emailing data row 2 to [e-mail]
> [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 服务。

进行日志记录时，良好的隐私保护做法是避免记录任何有关用户的个人信息，例如电子邮件地址。Cloud 日志会 自动使用 有效用户密钥进行标记，以便在必要时查找 特定用户的日志消息。

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

以下示例展示了如何使用 console 服务在 Cloud Operations 中记录信息。

utils/logging.gs

在 GitHub 上查看

/**
 * 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 日志条目中查找临时有效用户密钥， 请在 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 错误报告。您无需手动配置 Error Reporting 或创建跟踪条目。当抛出异常或您将 console.error 与 Error 对象搭配使用时，Apps 脚本会自动填充必填字段。如果您看到“设置 Error Reporting”提示，这是因为您的脚本尚未记录任何异常。除了启用异常日志记录之外，您无需进行任何 设置。

日志记录要求

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

您可以在 Apps 脚本信息中心内查看 Cloud 日志的简化版本。不过，如需充分利用 Cloud Logging 和错误报告，您必须有权访问脚本的 Google Cloud 项目。只有当您的脚本 项目使用的是标准 Google 云项目时，才能实现这一点。