Logging

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 execution log . This log is lightweight and streams in real time, but persists only for a short time.

  • The Cloud Logging interface in the Developer Console, which provides logs that persist for many days after their creation.

  • The 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 .

Use the Apps Script execution log

A basic approach to logging in Apps Script is to use the built-in execution log. To view these logs, at the top of the editor, click Execution log. When you run a function or use the debugger, the logs stream in real time.

You can use either the Logger or console logging services in the built-in execution log.

These logs are intended for simple checks during development and debugging, and do not persist very long.

For example, consider this function:

utils/logging.gs
 /** 
 * 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 
 ); 
  
 } 
 }

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

Cloud Logging

Apps Script also provides partial access to the Google Cloud Platform (GCP) Cloud Logging service. When you require logging that persists for several days, or need a more complex logging solution for a multi-user production environment, Cloud Logging is the preferred choice. See Cloud 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 Cloud Logging

Cloud logs are attached to the Google Cloud 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 Cloud Logging and its capabilities, use a standard Google Cloud project with your script project. This lets you access Cloud 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. Cloud 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 Cloud Operations.

utils/logging.gs
 /** 
 * 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. 
 }

Active user keys

Temporary active user keys provide a convenient way to spot unique users in Cloud 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 Cloud Log entries, view your Cloud logs in the Google Cloud console . You can do this only if your script project is using a standard Google Cloud project that you have access to. Once you've opened the Google Cloud 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 Cloud Logging, along with a stack trace.

To view exception logs, follow the steps below:

  1. Open the Apps Script project.
  2. At the left, click Executions .
  3. At the top, click Add a filter > Status.
  4. Select the Failedand Timed outcheckboxes.

You can also view logged exceptions in the GCP console if your script project is using a standard Google Cloud project that you have access to.

Enable exception logging

Exception logging is enabled by default for new projects. To enable exception logging for older projects, follow the steps below:

  1. Open the script project.
  2. At the left, click Project Settings .
  3. Select the Log uncaught exceptions to Cloud Operationscheckbox.

Error Reporting

Exception logging automatically integrates with Cloud Error Reporting , a service that aggregates and displays errors produced in your script. You can view your Cloud error reports in the Google Cloud 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 the built-in execution log.

You can view a simplified version of Cloud logs in the Apps Script dashboard . However, to make the most of Cloud 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 Google Cloud project .