Debugging Tools Best Practices

From ServiceNow Wiki
Home > Administer > Technical Best Practices > Maintenance Best Practices > Debugging Tools Best Practices
Jump to: navigation, search
Technical Best Practices

1 Overview

Debugging can provide information to help you understand system processes. There are a number of different debugging features you can use within a ServiceNow instance. Many browsers also feature a console log, which you can use for additional debugging.

2 Common Tester Questions

Before you start debugging, it is important to identify the source of the issue, and to be able to reproduce the defect or bug. Potential sources include user error, invalid test data, test script inaccuracy, and technical implementation. To help identify and remediate the issue, the tester should provide the following information:

  • The record being worked on—for example, CHG0012513
  • The user ID used for the test—for example, Change Test User 3
  • The steps required to reproduce the issue
  • The expected result of the test
  • The actual result of the test

3 Server-Side Debugging

Before starting work on an implementation, consider using one or more of the system debugging modules in the System Diagnostics and System Security applications. Enter debug in the navigation filter to display all debugging modules.

KB-Debug-1.png


Click a debugging module to activate it. When any debugging feature is active, an area labeled Debug Output appears at the bottom of the content frame.

3.1 Commonly Used Debugging Modules

Several commonly used debugging modules are described in the next few sections.

3.1.1 Debug Log

System Diagnostics > Debug Log displays gs.print() and gs.log() statements as well as server logging information and error messages at the bottom of the content frame. This helps you avoid alternating between the record you are trying to debug and the log output.

Note
Note: Debug Log is automatically activated when you activate Debug Business Rule.


Debug_Log.png

3.1.2 Debug Business Rule

System Diagnostics > Debug Business Rule displays messages about business rules. These messages indicate which business rules are being run and when they are started (==>), finished (<==), or skipped (===). If a business rule is skipped, the failed condition is displayed.

KB-Debug-2.png


3.1.3 Debug Security Rules

System Security > Debug Security Rules places a debug icon on each field of a form. Point to the icon to see if there are any debug messages for the associated element. Click the icon to expand details about read and write access. This module is very helpful when you are using ACLs to control access to records and fields.

Debug-Security-Rules.png


The debug security rules has enhanced functionality, allowing you to view a context parameter. This feature is available starting with the Eureka release.

3.1.4 Stop Debugging

System Security > Stop Debugging disables all debugging processes.

3.2 Server-Side Debugging Persistence

When you activate a server-side debugging module, it remains active until one of the following occurs:

  • You activate the Stop Debugging module, located in System Security.
  • You log out from the instance.
  • The session expires (for example, the session times out).
  • You close the browser.
Note
Note: Debugging processes persist even if you impersonate someone else. This is very helpful when impersonating users with multiple roles or no roles. Often, the biggest challenge to troubleshooting a reported issue is recreating it. Having debugging active while impersonating another user allows you to continue debugging while recreating the conditions around the reported issue.


3.3 Log Messages Controlled by a Property

The recommended way to debug server-side scripts is to use gs.print statements controlled by system properties. A common use case is a debug function in a script include that checks the value of a specific system property to determine if it should output the message indicated. For example:

var MyUtil = Class.create();
 
MyUtil.prototype = {
    initialize: function(){
        this.debug       = gs.getProperty('debug.MyUtil') == 'true';
        this.debugPrefix = '>>>DEBUG: MyUtil: ';
    },
 
    myMethod : function(id) {
 
        // Some logic here
        this._debug('myMethod(): Sample debug output');
    },
 
    _debug : function(msg) {

        if (this.debug) {
            gs.print(debugPrefix + msg);
        }
    },
 
    type : "MyUtil"
}

If the system property debug.MyUtil is set to false, nothing will be output to the log. If it is set to true, the debug message will be displayed. When combined with Debug Log or Debug Business Rule, this property can be used to enable or disable debug information without changing code and without impacting the user experiences of others on the system.

If a tester or user reports that something is not behaving as expected in test, QA, production, or another instance, you can enable the property, enable debugging output, and investigate your results quickly.

3.4 Other Methods

Some developers use the gs.addInfoMessage() or gs.addErrorMessage() JavaScript methods, but these may have an impact on the user experience. Consider the following situation: another developer is trying to debug a business rule running on the Task table while you are trying to do a code review or demo on the Incident table. Suddenly several messages appear at the top of the content frame, leaving you to wonder if they will appear in production when you are not even sure where they came from in development.

Using gs.log() statements in scripts may seem fairly anonymous to other users at first. They do not show up on the screen and you have to know where to look to see them. The drawback to using gs.log() statements to output debug messages is that they often get left in the code. If gs.log() statements are left in the code, they can have a considerable impact on the size of the system log file. Just one gs.log() file in the right spot can be triggered hundreds or thousands of times by users, system imports, scheduled jobs, and so on. Large log files full of debug messages adversely impact backup and restore times for information with little value in production. Controlling log messages with a system property prevents gs.log() statements from filling up the log.

4 Client-Side Debugging

To debug processes on the client side, click the debug icon in the banner frame.

KB-Debug-3.jpeg


Clicking the debug icon launches the JavaScript Debug window. Along with useful system information, you may choose to include jslog() statements in client scripts and UI policy scripts to help isolate and resolve issues. Unlike server-side debug statements, jslog() statements in client-side scripts do not consume disk space. This means you can leave them enabled, even in production.

Note
Note: When using jslog() statements, append a prefix string to messages you want to differentiate in the JavaScript debug window. For example:

>>>DEBUG (CT): Client script: windowLocator():

You can then use the browser's find feature to locate specific messages or fragments.


For information about using Chrome to debug, see Using Chrome to Debug Client Side Errors on the ServiceNow Community.

5 Browser Debugging

If available, check the browser's console log for additional debugging information. For example, the Firefox and Chrome console logs often display error messages that do not appear anywhere else. Using these logs can help speed up the development and troubleshooting processes by locating undefined objects.

KB-Debug-4.png


6 Disabling Debugging

Before you close out an update set or complete testing of the production instance, be sure to disable all server-side debugging to save log space in production. To disable debugging, search for all system properties that contain the string debug in the name and ensure they are all set to false.

This is another good reason to use properties to control debugging in a script. It makes enabling or disabling debugging a simple task, such as when you need to validate use cases or data.

Was this article helpful?
Yes, I found what I needed
No, I need more assistance