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 two 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.

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.

Stackdriver Logging

Apps Script also provides partial access to Google Cloud Platform's Stackdriver Logging (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 the Stackdriver Quota Policy for retention and other quota details.

Stackdriver Logging provides two tiers of serivice: the free Basic tier and the Premium tier. Scripts use the Basic tier by default. You can upgrade your script's Cloud Platform project to the Premium tier if you need more logging quota. If you decide to upgrade, it is recommended that you create a Cloud Platform project and switch your script to use it before upgrading.

Requirements

You need to have access to the Apps Script's Cloud Platform project in order to view the logs the script creates. If the script resides in a Team Drives, your access to the Cloud Platfrom project may be limited. See the Cloud Projects and Team Drives guide section for details.

Using Stackdriver Logging

These logs are attached to the project associated with your Apps Script, and you can view them by selecting View > Console logs in the script editor. This opens the Stackdriver UI in a new tab (if the UI tab does not appear, check to see if your browser's pop-up blocker has blocked it). If there are no logs to display, you'll see a "Welcome to Strackdriver Logging" page.

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.

The following table lists the Apps Script logging methods provided by the console bean.

Method Description
console.log([data][,...]) Sends log output to Stackdriver Logging at LogSeverity.DEBUG.
console.info([data][,...]) Sends output to Stackdriver Logging at LogSeverity.INFO.
console.warn([data][,...]) Sends output to Stackdriver Logging at LogSeverity.WARNING.
console.error([data][,...]) Sends output to Stackdriver Logging at LogSeverity.ERROR.
console.time([label]) Marks a time under the specified label.
console.timeEnd([label]) Records the time since the original call to time with the same label.

The following example shows how to use the Stackdriver Logging API:

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 "structPayload".
  var parameters = {
      isValid: true,
      content: 'some string',
      timestamp: new Date()
  };
  console.log({message: 'Function Input', initialData: parameters});

  var 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 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, select View > Console logs in the script editor. 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.

Send feedback about...

Apps Script
Apps Script