日志记录

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

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

内置 Apps 脚本执行日志。此日志属于轻量级实时数据流，但只会持续很短一段时间。
Play 管理中心内的 Cloud Logging 接口，提供日志在创建后保留了多天的日志。
Play 管理中心内的 Error Reporting 界面，该界面会收集并记录脚本运行时发生的错误。

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

使用 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);
  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

在 GitHub 上查看

/**
 * 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。

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

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

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

启用异常日志记录

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

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

Error Reporting

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

日志记录要求

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

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