AgileApps Support Wiki Pre Release

Debug Log

From AgileApps Support Wiki

GearIcon.png > Customization > Developer Resources > Debug Log

About the Debug Log

Custom java code executing in a JSP Page can use the Logger functions to add entries to the Debug Log. Messages can specify severity level, and can designate a message "type", or category.

In Developer Configuration, you control which severity levels are stored. In the Debug Log, you can search, filter, and inspect log records, as in any other View.

Working with the Debug Log

To work with the debug log, you need either of these permissions:

Adding entries to the Debug Log

To add statements to the log, use the Logger utility class.

By default, messages at the INFO severity level are logged, so general practice is to import com.platform.api.Logger and then code your debug statements like this:

Logger.info("Your message", "ClassName");

Thumbsup.gif

Tip: Using the class name as the information type helps when you're debugging multiple classes. It can also help to add an identifying number to the message--for example, one that more or less corresponds to the line number. You'll then be able to go straight to the right part of the source code.

Considerations
  • The category value can be used to filter records in the Debug Log. So make it something that will help to filter things, later. (The category is not shown in the default Debug Log view, but you can Edit the View to make it visible, and use it for filtering.)
  • The APIs take Java objects (not platform Objects), as well as Strings. If you use a Java object, make sure the toString() method returns a useful value. (That's what will appear in the log.)
  • Because the APIs take objects, you could pass this (the current object instance) as the "category". Then each message designates the class that was executing at the time. (But in that case, the category may not be as useful for filtering.)
  • For large applications, it may be desirable for administrators to have a standard set of messages that are always going into the log. In that case:
    • Use Logger.info(msg, category) for those messages.
    • Use Logger.debug(msg, category) for application debugging.
    • Then, since the severity levels running from lowest to highest, are: Trace, Debug, Info, Warn, Error, Fatal, normal operations will only see the Info messages.
    • To store debugging messages, set the recording level to Debug in the Developer Configuration.
Learn more:

Notepad.png

Note: The deprecated Functions.debug method can still be used to add entries to the Debug Log, for a time. That function adds statements at the INFO severity level.

Sample Code

This example logs a message after calling updateRecord to log the result code. The code also logs a message if the result code is less than zero (0). The category is "Account Update", so that these messages can be distinguished from other messages in the debug log.

Parameters params = Functions.getParametersInstance();
String accountID = "";
String debug_category = "Account Update";

// Some logic to populate accountID variable.

params.add("name", "Acme Solutions");
params.add("number", "GRG2323339");

Result result = Functions.updateRecord("ACCOUNT", accountID, params);

int resultCode = result.getCode();
Logger.info("Result code is " + resultCode, debug_category);

if(resultCode < 0)
{
    // Some error happened.
    String msg = "Account could not be updated";
    Logger.info(msg + ":\n" + result.getMessage(), debug_category); // Log it
    Functions.throwError(msg + "."); // Error message for user
}
else 
{
    // Take other actions on successful addition of the account.
}

Viewing the Debug Log

  1. Go to GearIcon.png > Customization > Developer Resources > Debug Log
    Debug Log entries are displayed in a View.
  2. Use standard Searching and Filtering operations to determine which records are displayed.
  3. To refresh the log, go to the sidebar and click Debug Log again.

Controlling Severity-Level Visibility

Debug messages have different severity levels. The default level is "Info".

In the Developer Configuration settings, you can specify which severity levels are recorded in the log. Those settings, from highest to lowest, are:

  • Fatal
  • Error
  • Warn
  • Info
  • Debug
  • Trace

Clearing the Debug Log

  1. Go to GearIcon.png > Customization > Developer Resources > Debug Log
  2. Click [Clear Debug Log]

Auto-Purge the Debug Log

This option allows configuring an automatic data purge of the Debug Log based on your choice of retention period. The retention period can be set from one to 60 days and is set to two days by default. All debug log entries older than the specified days are purged automatically.

Lock-tiny.gif

Users that have the Manage Debug Log permission can configure auto-purge settings 

When the auto-purge option is enabled, for example with a retention period of 10 days, then any record in the Debug Log that is more than 10 days old is deleted. The auto-purge action may not happen immediately, but the purge action is scheduled every day.

Notepad.png

Note: The deleted logs can be restored in the Global Recycle bin.

To configure Auto-Purge for Debug Log records:

  1. Click GearIcon.png > Administration > Monitoring > Debug Logs
  2. Click the [Retention Period] button
  3. Specify the number of days to retain the Debug Log entries
    • The value must be greater than or equal to one
  4. Click [Save]