Please use docs.servicenow.com for the latest documentation.

This site is for reference purposes only and may not be accurate for the latest ServiceNow version

Scoped Script Logging

From Wiki Archive
Jump to: navigation, search
Note
Note: This article applies to Fuji and earlier releases. For more current information, see Server API Reference at http://docs.servicenow.com

The ServiceNow Wiki is no longer being updated. Visit http://docs.servicenow.com for the latest product documentation.

Overview

The Scoped Logging API provides logging functions for scoped applications. The Scoped logging functions are available using the "gs" system prefix. For detailed reference information on the available scoped logging methods, see Scoped Logging API Reference.

The Scoped Logging API is available starting with the Fuji release.

Video Tutorials

The following video tutorials describes best practices for debugging issues in ServiceNow instances on the Fuji release.

Best Practices: Debugging in Fuji, pt 1 of 2 Best Practices: Debugging in Fuji, pt 2 of 2
GhQF5Rphz0E|500}} do7aDaEDLVw|500}}

Using the Scoped Logging Methods

The following examples show the format for generating log messages for each verbosity level. Optional parameters can be passed into the message using placeholders, and can be comma-delimited or a single JavaScript array:

<source lang="javascript"> gs.<verbosity_level>(message [, parameters]) </source>

The following example script generates a warning log message using two parameters:

<source lang="javascript"> var myFirstName = "Abel"; var myLastName = "Tuter"; gs.warn("This is a warning from {0}.{1}", myFirstName, myLastName); </source>

Output:

This is a warning from Abel.Tuter

The following method is available for determining if debug is active, returning true when either session debugging is active or log verbosity is set to debug for the current application:

<source lang="javascript"> gs.isDebugging() </source>

For detailed information on the scoped logging methods, see Scoped Logging API Reference.

Verbosity

The Scoped Logging API provides four levels of verbosity. In order from least verbose to most, they are:

Log Level Description
error (gs.error) Logs events that might still allow the application to continue running. Setting the log level for an application to error generates error messages only, but does not generate warn, info, or debug messages.
warn (gs.warn) Logs potentially harmful events. Setting the log level for an application to warn generates error and warn messages, but does not generate error or debug messages.
info (gs.info) Logs informational messages that describe the progress of the application. Setting the log level for an application to info generates info, warn, and error messages, but does not generate debug messages.
debug (gs.debug) Logs informational events that are useful for debugging an application. Setting the log level for an application to debug generates info, warn, error, and debug messages.

MessageFormat Placeholders

The scoped Logging API supports the Java MessageFormat placeholder replacement pattern. Currently there is support for up to 5 "varargs" placeholder arguments. Any more than five must be specified as a single JavaScript array argument. All of these are legal calls:

<source lang="javascript"> gs.info("Here's a log message from me"); // No parameters gs.info("Here's a log message from {0}", myName); // A single non-array parameter gs.info("Here's a log message from {0}.{1}", myFirstName, myLastName); // Multiple "varargs" parameters (up to 5) gs.info("Here's a log message from {0}.{1}", [myFirstName, myLastName]); // An array of n-number of parameters (no upper bounds) </source>

Logging Destination

Logging information can be routed to either a db or file destination. The destination is a system property.

Destination Description
db A log destination of db routes log messages within the specified logging verbosity to the syslog_app_scope table, which extends the syslog table. This table includes fields for the application that is issuing the log, as well as a Source Script field that links to the script that called into the Logging API. When destination is set to "db", logs also go to file system.
file A log destination of file logs to the node's file system log without broadcasting to log listeners, except in the case of Scripts - Background.

Handling Exceptions

An throwable exception can be passed as the first parameter after the string message. In this case, any other parameters that follow are ignored. This automatically appends the exception and stack trace to the specified message. For example:

<source lang="javascript"> try {

   foo.somethingThatThrows();

} catch (ex) {

   gs.error("There was an error doing something", ex);

} </source>

You can safely use gs.debug() in your applications. The debug messages are printed only when in debug mode or when session debug for that application is enabled. You should try out the scoped Logging API by printing with gs.debug() in your business rules and script includes, and enabling session debug in the UI.

Session Debug Logging

Session debug logging provides debug output in the UI, similar to what is available for business rules and SQL debugging. Session debug logging generates output at the debug verbosity level for the current application during the current session. To enable session debug logging, click Enable Session Debug under UI Actions; or click Disable Session Debug to turn it off.

Scripts - Background Special Treatment

Scripts executed in the Scripts - Background form (System Definition > Scripts - Background) always log at the debug level. This means that a call to gs.debug() in an application scope with property configured to log at the info level are logged as though verbosity were temporarily elevated to debug for the duration of the sys.scripts transaction. To indicate that a log line is emitted because of the special treatment of Scripts - Background, the log message includes a "(sys.scripts extended logging)" suffix.

For example, this script executed in the context of an application named x_my_app in Scripts - Background:

<source lang="javascript"> gs.info("This is an info log"); gs.debug("This is a debug log"); </source>

generates the following result:

x_my_app: This is an info log
x_my_app: This is a debug log (sys.scripts extended logging)

Logging that occurs within a sys.scripts transaction broadcasts to log listeners, unlike all other log entries created by the scoped Logging API. This is to accommodate the capture log output in the Scripts - Background result.

Viewing Application Logs

All logs from scoped applications are recorded in the App Log [syslog_app_scope] table, which tracks the source of the message, such as a business rule or script include. A history of all log messages generated by sopped applications are recorded and can be viewed in the Application Log form. To view current application logs, go to System Logs > System Log > Application Logs.

Field Description
Created The datetime when the log message was generated.
Level The verbosity level.
Message The log message.
App Scope The application scope associated with the log message.
Source Script The source script, if any, that generated the log message.

Properties

All scoped applications have two properties for control logging verbosity and destination. System properties are available by application for configuring log verbosity and destination, and for turning session debugging on or off:

Property Description
scope_name.logging.destination

Configuring the log destination: file system or db.

  • Type: String
  • Default value: db
  • Location: System Property [sys_properties] table
scope_name.logging.verbosity Configures log verbosity: error, warn, info, or debug.
  • Type: String
  • Default value: info
  • Location: System Property [sys_properties] table

From the global scope, the scoped Logging API routes to gs.logError, gs.logWarn, or gs.log, and applies MessageFormat parameter formatting.