日志记录

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

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

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

  • Play 管理中心中的 Cloud Logging 界面，该界面提供的日志可在创建后保留很多天。

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

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

使用 Cloud Logging

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

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

记录时，隐私保护方面的良好做法是避免记录有关用户的任何个人信息，例如电子邮件地址。Cloud 日志会自动添加活跃用户密钥标签，必要时您可以使用这些密钥查找特定用户的日志消息。

您可以使用 Apps 脚本 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 日志条目中查找临时有效的用户密钥，请在 Google Cloud 控制台中查看 Cloud 日志。只有在脚本项目使用您有权访问的标准 Google Cloud 项目时，您才能执行此操作。在控制台中打开 Google Cloud 项目后，选择所需的日志条目并展开该条目，然后查看元数据 > 标签 >script.googleapis.com/user_key。

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

异常日志记录

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

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

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

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

启用异常日志记录

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

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

Error Reporting

异常日志记录功能会自动与 Cloud Error Reporting 集成，后者是一项可汇总并显示脚本中产生的错误的服务。您可以在 Google Cloud 控制台中查看 Cloud 错误报告。如果系统提示您“设置 Error Reporting”，这是因为您的脚本尚未记录任何异常。只需启用异常日志记录即可，无需进行任何其他设置。

日志记录要求

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

您可以在 Apps 脚本信息中心查看简化版 Cloud 日志。但是，为了充分利用 Cloud Logging 和错误报告，您必须有权访问脚本的 GCP 项目。只有在脚本项目使用标准 Google Cloud 项目时，才能这么做。