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

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

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

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

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

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

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

Базовый подход к ведению журнала в 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);
  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

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

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

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

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

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

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

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

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

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

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

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

Чтобы найти временные активные ключи пользователей в записях журнала Cloud, просмотрите журналы Cloud в консоли 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 . Если вам предлагается «Настроить отчёты об ошибках», это означает, что ваш скрипт ещё не регистрировал исключения. Настройка не требуется, кроме включения ведения журнала исключений .

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

Требований по использованию встроенного журнала выполнения нет.

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