The following discussion of logging and debugging will be included in the next release of SmartClient. Every API discussed is available in SmartClient 5.5.
---------
In any page in which ISC has been loaded, you have access to the Developer Console, which can be opened by entering the following URL into your browser from the running application:
Basic information on the features of the Developer Console can be found in the QuickStart Guide. This topic focuses on use of the log system and related debugging facilities.
The Developer Console contains a "Results" pane that displays a list of diagnostic messages logged by the SmartClient framework. You can enable and disable diagnostic messages for specific subsystems, and you can also log your own messages. Because important diagnostic messages may be logged at any time, you should have the Developer Console open whenever you are working with SmartClient.
Log messages are of the format:
For example, the following log message:
Occured at 11:59 local time and 806 milliseconds. It's priority was INFO, it occurred in the category Page, and the message is "Page loading complete.".
Each logging category has a priority associated with it. If a message's priority is lower than the current priority for the category it is logged in, the message will be suppressed (will not appear in the "Results" pane).
You can use the "Logging Preferences" menu in the Results Pane to set the priority for each category. This allows you to enable diagnostics relevant to the particular problem you are working on.
It is critical to be familiar with the diagnostic categories built-in to SmartClient - you will use them in most debugging sessions. Open the Logging Preferences menu and select "More.." to see a list of diagnostic log categories. Hover over each category name to see a description of what kind of messages are logged in the category.
Logging your own messages
In typical debugging sessions, it's best to simply use the isc.Log.logWarn() method to output diagnostics. Since the default priority setting is WARN, logging via logWarn() ensures your message will not be suppressed.
NOTE: never use the native alert() method to output diagnostics. Among other issues, alert() can affect timing, masking or altering the behavior you were trying to debug. SmartClient's logging system doesn't suffer from these problems and provides much more control.
Typically diagnostic messages will want to include the current properties of a request, component, record or other object. You can use the isc.Log.echo() and isc.Log.echoAll() to get simple, highly readable string summaries of the current properties of an object or Array of objects. For example, given a ListGrid named "myGrid", you might inspect the first record of it's dataset like so:
Note that the "Evaluate JS Expression" area of the Results Pane uses echo() on the results of evaluated expressions. Hence, if you had an application loaded that contained "myGrid", the following expression could be eval'd to inspect its first record:
The ability to evaluate expressions frequently makes it unnecessary to add log statements and reload.
Adding your own diagnostic categories
Calling logWarn() is fine for a log statement you plan to delete at the end of the debugging session. However, many log statements have lasting value if you could enable or disable them only when you need the relevant diagnostics, like SmartClient's built-in diagnostic categories. To do this, pick a priority level less than WARN (INFO or DEBUG), and call the corresponding method on the Log class (logInfo() or logDebug()), passing the category name as a second parameter. For example:
This message will no longer appear in the Results Pane by default, because it's priority (INFO) is less than the default of WARN. To see this message, open the Logging Preferences menu and pick "More..", then click the "Add" button, enter "myGridLoading" as the category name and set the priority to INFO. The message will now appear next time it is logged.
Now you have a custom log category that you and other developers can use to debug your subsystem, which is available both in development and production environments.
As with SmartClient's built-in diagnostics, you may choose to log certain messages in your custom category at the DEBUG level and a lesser number of messages at the INFO level, to create different depths of diagnostic output.
Logging refinements
The core log methods (logDebug(), logInfo(), logWarn()) and the "echo" facilities (echo() and echoAll()) are available on every SmartClient component and Class. Hence, in many cases, the special JavaScript value "this" will refer to an object that supports logWarn() et al. For example:
The special value "this" is not always set to a SmartClient component, for example, in some kinds of callbacks (eg fetchData()). When in doubt, use these methods via the Log class as isc.Log.logWarn().
Logging performance
Because the log message is actually formed before the call to the log system, logs that are suppressed can still carry a performance penalty. This is particularly true of logs that output a lot of data or occur frequently. To avoid this penalty, you can check in advance whether a message will be suppressed using isc.Log.logIsDebugEnabled() and isc.Log.logIsInfoEnabled(). For example:
Generally, it is only important to do this for logs that will occur multiple times during a given user interaction (eg a mousedown or keypress) and/or that call echo() on objects with many properties.
---------
In any page in which ISC has been loaded, you have access to the Developer Console, which can be opened by entering the following URL into your browser from the running application:
Code:
javascript:isc.showConsole()
The Developer Console contains a "Results" pane that displays a list of diagnostic messages logged by the SmartClient framework. You can enable and disable diagnostic messages for specific subsystems, and you can also log your own messages. Because important diagnostic messages may be logged at any time, you should have the Developer Console open whenever you are working with SmartClient.
Log messages are of the format:
timestamp:priority:category:message
For example, the following log message:
Code:
11:59:25:806:INFO:Page:Page loading complete.
Each logging category has a priority associated with it. If a message's priority is lower than the current priority for the category it is logged in, the message will be suppressed (will not appear in the "Results" pane).
You can use the "Logging Preferences" menu in the Results Pane to set the priority for each category. This allows you to enable diagnostics relevant to the particular problem you are working on.
It is critical to be familiar with the diagnostic categories built-in to SmartClient - you will use them in most debugging sessions. Open the Logging Preferences menu and select "More.." to see a list of diagnostic log categories. Hover over each category name to see a description of what kind of messages are logged in the category.
Logging your own messages
In typical debugging sessions, it's best to simply use the isc.Log.logWarn() method to output diagnostics. Since the default priority setting is WARN, logging via logWarn() ensures your message will not be suppressed.
NOTE: never use the native alert() method to output diagnostics. Among other issues, alert() can affect timing, masking or altering the behavior you were trying to debug. SmartClient's logging system doesn't suffer from these problems and provides much more control.
Typically diagnostic messages will want to include the current properties of a request, component, record or other object. You can use the isc.Log.echo() and isc.Log.echoAll() to get simple, highly readable string summaries of the current properties of an object or Array of objects. For example, given a ListGrid named "myGrid", you might inspect the first record of it's dataset like so:
Code:
isc.Log.logWarn("first record is: " + isc.Log.echo(myGrid.data.get(0)));
Code:
myGrid.data.get(0)
Adding your own diagnostic categories
Calling logWarn() is fine for a log statement you plan to delete at the end of the debugging session. However, many log statements have lasting value if you could enable or disable them only when you need the relevant diagnostics, like SmartClient's built-in diagnostic categories. To do this, pick a priority level less than WARN (INFO or DEBUG), and call the corresponding method on the Log class (logInfo() or logDebug()), passing the category name as a second parameter. For example:
Code:
isc.Log.logInfo("first record is: " + isc.Log.echo(myGrid.data.get(0)),
"myGridLoading");
Now you have a custom log category that you and other developers can use to debug your subsystem, which is available both in development and production environments.
As with SmartClient's built-in diagnostics, you may choose to log certain messages in your custom category at the DEBUG level and a lesser number of messages at the INFO level, to create different depths of diagnostic output.
Logging refinements
The core log methods (logDebug(), logInfo(), logWarn()) and the "echo" facilities (echo() and echoAll()) are available on every SmartClient component and Class. Hence, in many cases, the special JavaScript value "this" will refer to an object that supports logWarn() et al. For example:
Code:
Canvas.create({
ID:"canvasExample",
contents:"Hello World!",
click:"this.logWarn('the Canvas is: ' + this.echo(this))"
});
Logging performance
Because the log message is actually formed before the call to the log system, logs that are suppressed can still carry a performance penalty. This is particularly true of logs that output a lot of data or occur frequently. To avoid this penalty, you can check in advance whether a message will be suppressed using isc.Log.logIsDebugEnabled() and isc.Log.logIsInfoEnabled(). For example:
Code:
if (isc.Log.logIsInfoEnabled("myGridLoading")) {
isc.Log.logInfo("first record is: " + isc.Log.echo(myGrid.data.get(0)),
"myGridLoading");
}