При разработке любого приложения часто возникает необходимость регистрировать информацию, которая поможет диагностировать ошибки во время разработки, выявлять и диагностировать проблемы клиентов, а также использовать ее в других целях.
Apps Script предоставляет три различных механизма ведения журнала:
Встроенный журнал выполнения скриптов приложений . Этот журнал занимает мало места и ведётся в режиме реального времени, но хранится лишь в течение короткого времени.
Интерфейс Cloud Logging в консоли разработчика, предоставляющий журналы, которые сохраняются в течение многих дней после их создания.
Интерфейс отчетов об ошибках в консоли разработчика, который собирает и регистрирует ошибки, возникающие во время выполнения вашего скрипта.
Они описаны в следующих разделах. В дополнение к этим механизмам вы также можете создать собственный код для ведения журнала, который, например, будет записывать информацию в электронную таблицу или базу данных JDBC .
Используйте журнал выполнения скриптов приложений
Базовый подход к ведению журнала в Apps Script — использование встроенного журнала выполнения. Чтобы просмотреть эти журналы, нажмите «Журнал выполнения» в верхней части редактора. При запуске функции или использовании отладчика журналы передаются в режиме реального времени.
Вы можете использовать либо Logger
, либо console
службы ведения журнала во встроенном журнале выполнения.
Эти журналы предназначены для простых проверок во время разработки и отладки и не сохраняются слишком долго.
Например, рассмотрим эту функцию:
При запуске этого скрипта с входными данными «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.
Активные пользовательские ключи
Временные активные ключи пользователей — это удобный способ находить уникальных пользователей в записях 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 .