When developing any kind of app, you often want to log information to help diagnose faults during development, to identify and diagnose customer issues, and for other purposes.
Apps Script provides three different mechanisms for logging:
The built-in Apps Script Logger, which is lightweight but persists only for a short time.
The Stackdriver Logging interface in the Developer Console, which provides logs that persist for many days after their creation.
The Stackdriver Error Reporting interface in the Developer Console, which collects and records errors that occur while your script is running.
These are described in the following sections. In addition to these mechanisms, you can also build your own logger code that, for example, writes information to a logging Spreadsheet or JDBC database.
Basic logging
A basic approach to logging in Apps Script is to use the built-in Logger. Logs created this way can be viewed by selecting View > Logs in the script editor. These logs are intended for simple checks during development and debugging, and do not persist very long.
For example, consider this function:
When this script is run with inputs "2" and "john@example.com" the following logs are written:
[16-09-12 13:50:42:193 PDT] Emailing data row 2 to john@example.com
[16-09-12 13:50:42:271 PDT] Row 2 data: Cost 103.24
The Logger.log()
method
expects a string or other JavaScript object. The logs can only hold a limited
amount of data, so avoid logging large amounts of text.
Stackdriver Logging
Apps Script also provides partial access to the Google Cloud Platform (GCP) Stackdriver Logging service (formerly known as "Cloud Logging"). When you require logging that persists for several days, or need a more complex logging solution for a multi-user production environment, Stackdriver Logging is the preferred choice. See Stackdriver Logging quotas and limits for data retention and other quota details.
If you need more logging quota, you can submit a Google Cloud Platform quota request. This requires that you have access to the Cloud Platform project that your script uses.
Using Stackdriver Logging
Stackdriver logs are attached to the GCP project associated with your Apps Script. You can view a simplified version of these logs in the Apps Script dashboard. To make full use of Stackdriver Logging and its capabilities, use a standard GCP project with your script project. This lets you access Stackdriver logs directly in the GCP Console and gives you more viewing and filtering options.
When logging, it is good privacy practice to avoid recording any personal information about the user, such as email addresses. Stackdriver logs are automatically labeled with active user keys you can use to locate a specific user's log messages when necessary.
You can log strings, formatted strings, and even JSON objects using the
functions provided by the Apps Script
console
service.
The following example shows how to use the console
service to log information in Stackdriver.
Active user keys
Temporary active user keys provide a convenient way to spot unique users in Stackdriver Log entries without revealing the identities of those users. Keys are per script and change roughly once a month to provide additional security should a user reveal their identity to a developer, for example while reporting an issue.
Temporary active user keys are superior to logging identifiers like email addresses because:
- You don't have to add anything to your logging; they're already there!
- They don't require user authorization.
- They protect user privacy.
To find temporary active user keys in your Stackdriver Log entries, view your Stackdriver logs in the GCP console. You can do this only if your script project is using a standard GCP project that you have access to. Once you've opened the GCP project in the console, select a log entry of interest and expand it to view metadata > labels > script.googleapis.com/user_key.
You can also get the temporary active user key by calling
Session.getTemporaryActiveUserKey()
in your script. One way to use this method is to display the key to the user
while they are running your script. Then users may choose to include their keys
when reporting issues to help you identify the relevant logs.
Exception logging
Exception logging sends unhandled exceptions in your script project code to Stackdriver Logging, along with a stack trace. You can view these exceptions in the Apps Script dashboard by viewing the project details and selecting > Failed Executions. You can also view logged exceptions in the GCP console if your script project is using a standard GCP project that you have access to.
Exception logging is enabled by default for new projects. You can also enable exception logging for older projects by checking the box File > Project properties > Info > Log exceptions from the Apps Script editor.
Stackdriver Error Reporting
Exception logging automatically integrates with Stackdriver Error Reporting, a service that aggregates and displays errors produced in your script. You can view your Stackdriver error reports in the GCP console. If you are prompted to "Set up Error Reporting" this is because your script has not yet logged any exceptions. No setup is required beyond enabling exception logging.
Logging requirements
There are no requirements for using Basic logging.
You can view a simplified version of Stackdriver logs in the Apps Script dashboard. However, to make the most of Stackdriver logging and error reporting you must have access to the GCP project of the script. This is only possible if your script project is using a standard GCP project.