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

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

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

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

Встроенный журнал выполнения 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 . Для этого необходим доступ к проекту облачной платформы , который использует ваш скрипт.

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

Журналы облака прикреплены к проекту Google Cloud, связанному с вашим скриптом приложений. Вы можете просмотреть упрощенную версию этих журналов на панели управления 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.
Слева нажмите Казни .
Вверху нажмите Добавить фильтр > Статус .
Установите флажки «Сбой» и «Время ожидания истекло» .

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

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

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

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

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

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

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

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

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