Logging application behavior

In this topic ... Turn on Logging Change Default Logging Level View a Log File Set up Custom Logging with the Logging Category Builder Use Builder Built-in Logging Use Logging with Data Page Builder Use Logging with the View & Form Builders Prevent log4j Properties from Being Overwritten Related Topics ... Overview: Logging How to use the Logging Category Builder log4j Categories and Appenders Overview: Debugging

You will often find it useful to debug an application by logging the output of arbitrary actions and methods during execution. The traditional means of placing System.out.println() statements in the code for debugging purposes as a means of narrowing down where a bug/error/exception is occurring and later removing is both tedious and error prone. In addition, using System.out, provides no control over when the line is printed.

In the Factory we can get the same degree of information more simply by defining methods that can output to log files or the system console. And we can control the behavior of these methods through central logging properties. This increased flexibility allows you to choose only to view warnings, or errors, or misc. info (when a button is pressed etc).

The following tasks represent the most common activities you will encounter when using Factory logging.

 

Turn on logging

No need to...logging is enabled by default in the Designer. Simply run a model and invoke some model actions and those actions will be written to the log.

By default, the logging level is set to "WARN" which will result in a lot of information being written to the various log files. (The hierarchy of logging levels is as follows DEBUG < INFO < WARN < ERROR < FATAL. )

 

Change the default logging level

There are default settings for the log4j features that are set when the project is initially built. The log4j property file is found in the < project name>/WEB-INF/config directory. This property file sets the log4j features for all models within the project. Within the log4j property file there are 5 priority levels: This set of priorities has the following hierarchy:

DEBUG < INFO < WARN < ERROR < FATAL.

This hierarchy implies that DEBUG is the most verbose and FATAL is the most restrictive. This means that if you set the priority level at ERROR, it will enable the program to write all messages with a priority level of ERROR or FATAL to the log. But it will not write any messages that have a priority less than ERROR (namely DEBUG, INFO, and WARN). The default setting for all WebSphere Portlet Factory projects is WARN, except for the log file used for the category "debug tracing", which defaults to INFO.

We can change the default logging level as follows:

1. Open the log4j.properties file located in the project's WEB-INF/config directory.

2. Near the top of this file locate the property: log4jrootCategory=

3. Change the first argument after the = sign from "WARN" to another level, such as "INFO".

4. Save and close the property file.

5. You might need to restart your server for these changes to take effect.

 

View a log file

The Designer provides a set of files that a model can use to write information from various sources, including: builderCalls, debugTracing, event_DATE, general, incomingSOAPRequests, modelActions, profileSelection, regen, request, serviceCalls.

Each of these files describes an abstract part of the programs run-time processes. For example, any actions/methods that are called by a model with an associated log4j method call are logged in the modelActions.txt file.

The Designer stores all logs within the WEB-INF\logs directory of the WAR file created from the project. To view a log:

1. Browse to the log file location within the WAR.

For example, on WebSphere 5 the path might be:

WebSphere\AppServer\installedApps\cell_name\<project_name>.EAR\wpf.war\WEB-INF\logs

2. Locate the log file that interests you and open and view in a text editor such as Notepad.

 

Set up custom logging with the Logging Category Builder

The Logging Category Builder allows you to create your own logging category and define the log file you want to write a message to. The specific message to be written can change depending on where you would like to place the logging category method.

1. Configure the Logging Category Builder. The Logging Category Builder has three required fields provide information for:

Builder name - Enter a name for the builder

log4j Category - Define which category you feel this builder will be most associated with. For example, for all requests using HTTP, you might want to write to the Request category log file.

Click Apply or Save to add the Builder to the model.

2. Add an Action List Builder to the model.

3. Select a row in the ActionList table and use the picker to open the Methods folder. In the Methods folder you will see a sub-folder with the same name as the Logging Category Builder.

4. Open this sub-folder to display a list of all public methods associated with the Logging Category Builder.

5. Select a log4j method (debug, error, fatal, warn, etc.) to make it an action.

6. After you pick the method, you will need to pass in whatever text you want to log as an argument to the method. In most builders there is an Input Mappings table that will prompt you for the text string to be written to the log.

When the model runs, messages associated with this error level are written to the output location specified in the Logging Category Builder.

For more information about the methods in the log4j.category, refer to the log4j API Javadoc documentation at http://jakarta.apache.org/log4j/docs/documentation.html.

 

Use built-in logging in Service Call & SQL Builders

These Builders connect to resources outside of your working model. Therefore, it is useful in development to be able to log the events that occur within these builders to ensure that the data from the resources is being accessed correctly. It is best to determine that the builders are acquiring valid data from the resource, before looking for an error in your model. The logging feature in these builders allows you to log the communication between the model and the data resource. To set up logging in one of these builders:

1. Enable logging at the Builder level as follows:

Open the Builder edit page and locate the check box related to logging, For example, in the Service Call Builder this box is labeled, "Log request/response." In the SQL Call Builder there are three logging-related boxes: "Log SQL Statements", "Log SQL Warnings", Log Server Stats". We can enable as many or few as you want.

Alternately, use the Designer Outline View to see which Builders in your application support logging. Press the Outline View down arrow to open the View menu and select "Debug Inputs..." A window will pop up listing (by assigned name) all builders in the model that offer built-in logging. Enable the logging check boxes in this window as desired and click OK to turn on the builder's built-in logging functionality. Once you click OK, your changes will be saved to the respective builders.

2. View log output.

Service Call and SQL Call Builders write their output to the debugTracing.txt log located in the ...\wpf.war\WEB-INF\logs directory.

For the Service Call Builder, the log4j features will log the initial call of the model associated with the Service Call Builder. It would then log the service call request with argument name, type and value followed by the response, if any, with the same type information that was logged in the request. With each log entry in the debugTracing.txt is the Time/Date, Category, Priority, Thread, and the Message.

A typical log entry might look as follows:

Example of a request:

*-- TIME: [2004-08-26 11:36:25,061] --*

Category: bowstreet.system.debugTracing

Priority: INFO

Thread:   http-8080-Processor3

Msg:      ServiceCall: arg name=registrationInfo class=com.bowstreet.util.IXml val=<RegistrationRequest xmlns="http://bowstreet.com/registrationinfo"><userName>johnDoe</userName>

<firstName>John</firstName>

<lastName>Doe</lastName>

<address1>200 Ames Pond Drive</address1>

<address2>Suite 200</address2>

<city>Tewks</city>

<state>MA</state>

<zip>02155</zip>

<phone>9788631500</phone>

<email>johnD@bowstreet.com</email>

<isBusiness>true</isBusiness>

</RegistrationRequest>

 

Use logging with the Data Page Builder

The Data Page builder is one of the most versatile and popular Builders. However, the Data Page Builder will not let you call a function that takes inputs, even if one is necessary. Thus, you could specify the Logging Category Builder method in a Data Page Builder input field, but it would not prompt you for the method

To used the Logging Category Builder in the context of an action called by Data Page, use an Action List Builder to wrap that action together with a call to the logging method. This will ensure that both are executed and that parameters can be passed to the logging method.

For example, in the Failure Action input in the Data Page Builder call editor, you could place a call to an action list that calls your logging method, taking an argument (variable/string message/output from an action/method) to write to a log for a particular priority (ERROR or WARN) and then calls the action associated with the failure condition, such as an error page.

 

Use Logging with the View & Form Builders

When you place a View & Form Builder (Domino, SAP, PeopleSoft, etc.) in a model, you are unable to insert calls to a method before a method call made by the View and Form Builder. This can cause a problem if you want to log database access parameters or other activities performed by the View and Form Builder.

All View and From Builders are model-based Builders. As a result, we can edit the Builder s base model in order to change its action flow and behavior. This allows you to insert into the flow calls to logging operations.

To edit a View and Form Builder s base model, perform the following steps:

1. Open a View & Form Builder, such as the Domino View and Form Builder.

2. Expand the Builder Call Editor s "Advanced" section and note the name of the Builder s base model in the "Model name" input field.

3. Open the Builder s base model. For example: domino_viewandform_base model.

4. In the base model perform steps 1 and 2 above and open the Builders portlet model. For example: "domino_portlet" model. Note that the "domino_portlet" model contains all the calls to the Domino Database.

5. In the portlet model insert the calls to your logging functionality or other methods in this model and regen the base model.

We can use this same approach with any other model-based builder.

 

Preventing log4j Properties from Being Overwritten

In the Eclipse workspace, the log4j properties file is overwritten when you modify a WebApp project.. This issue occurs because the files from the 'WPFDesigner\FeatureSets\Web- App_X.X.X\Templates\Project project template folder, overwrite the eclipse project files

There are two ways prevent this from happening:

• Manual Method - Modify the log4j.properties file in the Templates\Project folder.

• In Project Wizard - Select "No" when the Project Modify Wizard asks you if you wish to overwrite the file (log4j.properies). This approach is the easiest way to preserve the log4j.propertie file settings.