日志记录

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

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

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

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

  • Play 管理中心的 Error Reporting 界面,用于收集并记录在脚本运行期间发生的错误。

以下各部分将为您介绍相关内容。除了这些机制之外,您还可以构建自己的日志记录器代码,例如将信息写入日志记录电子表格JDBC 数据库

使用 Apps 脚本执行日志

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

您可以在内置执行日志中使用 Loggerconsole 日志记录服务。

这些日志适用于开发和调试期间的简单检查,并且不会保留很长时间。

以下面的函数为例:

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 控制台中查看记录的异常

启用异常日志记录功能

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

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

Error Reporting

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

日志记录要求

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

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