логирование

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

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

• Встроенный журнал выполнения скриптов приложений . Этот журнал невелик и передается в режиме реального времени, но сохраняется только в течение короткого промежутка времени.

• Интерфейс Cloud Logging в консоли разработчика, который предоставляет журналы, которые сохраняются в течение многих дней после их создания.

• Интерфейс отчетов об ошибках в консоли разработчика, который собирает и записывает ошибки, возникающие во время работы вашего скрипта.

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

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

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

Вы можете использовать либо Logger , либо console службы ведения журнала во встроенном журнале выполнения.

Эти журналы предназначены для простых проверок во время разработки и отладки и не сохраняются очень долго.

Например, рассмотрим эту функцию:

утилиты/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» и «[e-mail]», в журнал записываются следующие журналы:

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

Облачное ведение журнала

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

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

Примечание. Cloud Logging предоставляет ряд услуг помимо хранения журналов, таких как оповещения и метрики. В настоящее время эти службы недоступны в Apps Script.

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

Облачные журналы прикреплены к проекту GCP, связанному с вашим скриптом приложений. Вы можете просмотреть упрощенную версию этих журналов на панели инструментов Apps Script .

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

Примечание. Если вы используете среду выполнения Rhino, Cloud Logging не поддерживает службу Apps Script Logger . Вместо этого используйте службу console .

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

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

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

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

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

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

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

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

Регистрация исключений

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

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

1. Откройте проект скрипта приложений.
2. Слева нажмите Executions .
3. Вверху нажмите Добавить фильтр > Статус .
4. Установите флажки Failed и Timed out .

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

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

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

1. Откройте проект сценария.
2. Слева нажмите проекта .
3. Установите флажок Записывать неперехваченные исключения в облачные операции .

Отчет об ошибках

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

Требования к ведению журнала

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

Вы можете просмотреть упрощенную версию облачных журналов на панели инструментов Apps Script . Однако, чтобы максимально эффективно использовать облачное ведение журнала и отчеты об ошибках, у вас должен быть доступ к проекту скрипта GCP. Это возможно только в том случае, если ваш проект скрипта использует стандартный проект GCP .