Эта страница переведена с помощью Cloud Translation API.

Ведение журнала

При разработке любого приложения часто возникает необходимость в сборе информации для диагностики ошибок в процессе разработки, выявления и диагностики проблем, возникающих у пользователей, а также для других целей.

Apps Script предоставляет три различных механизма для ведения журналов:

Встроенный журнал выполнения Apps Script . Этот журнал имеет небольшой размер и передается в режиме реального времени, но сохраняется лишь короткое время.
Интерфейс Cloud Logging в консоли разработчика предоставляет доступ к журналам, которые сохраняются в течение многих дней после их создания.
Интерфейс «Отчеты об ошибках» в консоли разработчика собирает и записывает ошибки, возникающие во время выполнения вашего скрипта.

Они описаны в следующих разделах. В дополнение к этим механизмам вы также можете создать собственный код логгера, который, например, записывает информацию в электронную таблицу для логирования или базу данных JDBC .

Используйте журнал выполнения Apps Script.

Один из основных способов ведения журналов в Apps Script — использование встроенного журнала выполнения. Чтобы просмотреть эти журналы, в верхней части редактора нажмите «Журнал выполнения» . При запуске функции или использовании отладчика журналы отображаются в режиме реального времени.

Встроенный журнал выполнения можно использовать либо службу логирования 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}`);
  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);
}

При запуске этого скрипта с входными данными "2" и "john@example.com" в лог записываются следующие данные:

[16-09-12 13:50:42:193 PDT] Отправка данных из строки 2 по электронной почте на адрес john@example.com
[16-09-12 13:50:42:271 PDT] Данные во второй строке: Стоимость 103,24

Облачный журнал

Apps Script также предоставляет частичный доступ к сервису Cloud Logging платформы Google Cloud Platform (GCP). Если вам требуется ведение журналов в течение нескольких дней или более сложное решение для многопользовательской производственной среды, Cloud Logging — предпочтительный выбор. Подробную информацию о сроках хранения данных и других параметрах квот см. в разделе «Квоты и ограничения Cloud Logging» .

Если вам требуется больше квоты на ведение журналов, вы можете отправить запрос на выделение квоты в Google Cloud Platform . Для этого вам потребуется доступ к проекту Cloud Platform , который использует ваш скрипт.

Использование облачного логирования

Журналы Cloud привязаны к проекту Google Cloud , связанному с вашим Apps Script. Вы можете просмотреть упрощенную версию этих журналов на панели управления Apps Script .

Чтобы в полной мере использовать возможности Cloud Logging, используйте стандартный проект Google Cloud вместе со своим скриптовым проектом. Это позволит вам получать доступ к журналам Cloud Logging непосредственно в консоли GCP и предоставит больше возможностей для просмотра и фильтрации.

При ведении журналов рекомендуется избегать записи любой личной информации о пользователе, например, адресов электронной почты, с целью обеспечения конфиденциальности. Журналы в облаке автоматически помечаются активными ключами пользователей, которые можно использовать для поиска сообщений журнала конкретного пользователя при необходимости.

С помощью функций, предоставляемых console службой Apps Script, вы можете записывать в лог строки, отформатированные строки и даже объекты JSON.

В следующем примере показано, как использовать console службу для регистрации информации в Cloud Operations.

utils/logging.gs

Посмотреть на GitHub

/**
 * A placeholder function to be timed.
 * @param {Object} parameters
 */
function myFunction(parameters) {
  // Placeholder for the function being timed.
}

/**
 * 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 Log без раскрытия их личности. Ключи присваиваются каждому скрипту и меняются примерно раз в месяц для обеспечения дополнительной безопасности в случае, если пользователь раскроет свою личность разработчику, например, при сообщении о проблеме.

Временные активные ключи пользователей превосходят идентификаторы для регистрации, такие как адреса электронной почты, по следующим причинам:

Вам не нужно ничего добавлять в журналы событий; они уже там есть!
Для их использования не требуется авторизация пользователя.
Они защищают конфиденциальность пользователей.

Чтобы найти временные активные ключи пользователей в записях Cloud Log, просмотрите журналы Cloud Log в консоли Google Cloud . Это можно сделать только в том случае, если ваш проект скрипта использует стандартный проект Google Cloud , к которому у вас есть доступ. После открытия проекта Google Cloud в консоли выберите интересующую запись журнала и разверните ее, чтобы просмотреть метаданные > метки > script.googleapis.com/user_key .

Вы также можете получить временный ключ активного пользователя, вызвав метод Session.getTemporaryActiveUserKey() в своем скрипте. Один из способов использования этого метода — отобразить ключ пользователю во время выполнения скрипта. Затем пользователи могут указать свои ключи при сообщении о проблемах, чтобы помочь вам идентифицировать соответствующие журналы.

Ведение журнала исключений

Журналирование исключений отправляет необработанные исключения в коде вашего скриптового проекта в Cloud Logging вместе с трассировкой стека.

Чтобы просмотреть журналы исключений, выполните следующие действия:

Откройте проект Apps Script.
Слева нажмите кнопку Executions .
Вверху нажмите «Добавить фильтр» > «Статус» .
Установите флажки «Сбой» и «Время ожидания истекло» .

Вы также можете просмотреть зарегистрированные исключения в консоли GCP, если ваш скриптовый проект использует стандартный проект Google Cloud , к которому у вас есть доступ.

Включить ведение журнала исключений

Для новых проектов ведение журнала исключений включено по умолчанию. Чтобы включить ведение журнала исключений для более старых проектов, выполните следующие действия:

Откройте проект скрипта.
В левой части экрана нажмите проекта» .
Установите флажок «Регистрировать необработанные исключения в облачных операциях» .

Сообщение об ошибках

Система регистрации исключений автоматически интегрируется с Cloud Error Reporting — сервисом, который собирает и отображает ошибки, возникающие в вашем скрипте. Вы можете просматривать отчеты об ошибках Cloud в консоли Google Cloud . Вам не нужно вручную настраивать систему регистрации ошибок или создавать записи трассировки. Apps Script автоматически заполняет необходимые поля при возникновении исключения или при использовании console.error() с объектом Error . Если вам предлагается «Настроить систему регистрации ошибок», это означает, что ваш скрипт еще не регистрировал никаких исключений. Никакой дополнительной настройки, кроме включения регистрации исключений, не требуется.

Требования к ведению учета

Для использования встроенного журнала выполнения никаких требований не существует.

Упрощенную версию журналов Cloud Logs можно просмотреть на панели управления Apps Script . Однако для максимального использования Cloud Logging и отчетов об ошибках вам необходим доступ к проекту GCP, в котором работает скрипт. Это возможно только в том случае, если ваш проект скрипта использует стандартный проект Google Cloud .