日志记录

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

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

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

  • 内置的 Apps 脚本执行日志。 此日志轻量级且实时流式传输,但持续时间很短。

  • Developer Console 中的 Cloud Logging 接口,该界面提供日志在创建后保留了很多天。

  • 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
    Logger.log('Failed with error %s', err.message);
  }
}

使用输入“2”和“john@example.com”运行此脚本时,系统会写入以下日志:

[16-09-12 13:50:42:193] 通过电子邮件将第 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 脚本关联的 GCP 项目。您可以在 Apps 脚本信息中心查看这些日志的简化版本。

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

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

异常日志记录

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

要查看异常日志,请按以下步骤操作:

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

如果您的脚本项目使用了您有权访问的标准 GCP 项目,您还可以在 GCP Console 中查看记录的异常

启用异常日志记录功能

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

  1. 打开脚本项目。
  2. 点击左侧的 Project Settings 图标
  3. 选中将未捕获到的异常记录到 Cloud Operations 中 (Log unccatedexception to Cloud Operations) 复选框。

Error Reporting

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

日志记录要求

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

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