日志记录

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

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

内置的 Apps 脚本执行日志。此日志是轻量级的，并实时进行流式传输，但持续时间很短。
Developer Console 中的 Cloud Logging 界面，其中提供的日志可在创建后保留很多天。
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”时，系统会写入以下日志：

]

Cloud Logging

Apps 脚本还提供对 Google Cloud Platform (GCP) Cloud Logging 服务的部分访问权限。如果您需要持续几天的日志记录，或者需要针对多用户生产环境采用更复杂的日志记录解决方案，则 Cloud Logging 是首选选择。如需了解数据保留和其他配额详情，请参阅 Cloud Logging 配额和限制。

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

使用 Cloud Logging

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

若要充分利用 Cloud Logging 及其功能，请为您的脚本项目使用标准 GCP 项目。这样，您就可以直接在 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 日志条目中查找临时活跃用户密钥，请在 GCP Console 中查看 Cloud 日志。仅当您的脚本项目使用您有权访问的标准 GCP 项目时，您才能执行此操作。在控制台中打开 GCP 项目后，选择相关的日志条目并将其展开即可查看元数据 > 标签 > script.googleapis.com/user_key。

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

异常日志记录

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

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

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

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

启用异常日志记录

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

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

Error Reporting

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

日志记录要求

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

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