This section describes how to configure logging for NexJ applications running in the WebSphere Application Server or NexJ Server environments.

Logging activity in WebSphere Application Server environments

WebSphere Application Server generates log files for NexJ applications that run on the server.

You can modify settings in WebSphere Integrated Solutions Console to customize logging functionality for your specific business needs, such as logging information for individual users or specific components of the model. By default, logging is enabled at the info logging level.

Log files are output to a directory specified in Integrated Solutions Console.

Configuring named user and component logging

You can enable named user and component type logging by specifying logging properties in Integrated Solutions Console.

Named user logging enables you to target specific users for detailed logging without changing the general logging level for the rest of the user base. Filtering log information for individual users helps troubleshoot issues in a production environment with minimal performance overhead.

Component logging enables you to log specific components of the model for troubleshooting purposes. For example, you can enable logging for a class in the business model layer, such as the user class.

To configure named user and component logging:

1. In Integrated Solutions Console, navigate to the Logging and tracing page and select the server on which you want to enable logging.
2. Navigate to the Diagnostic trace service page and select Change log detail levels.
3. To enable named user or component logging, do either of the following:
   • Add properties for the users or components that you want to log directly in the field at the top of the components list.

   • Use the user interface to generate properties for the users or components that you want to log.

     Info

     Named user categories may not be available in the user interface.

4. Close Integrated Solutions Console.

Log messages for each user specified in WebSphere Integrated Solutions Console will be output in the application's log file. Logs will also be output for each component type that you specified.

Categories for enabling named user logging

Enable and configure named user logging by specifying user and class properties in the WebSphere Integrated Solutions Console. Categories define the users that are highlighted in log files and control their level of logging detail.

You need to add two types of category tags for named user logging:

• Enable named user logging for a specific user.
• Specify the logging level and which classes should be logged for the user.

Named user logging has no restriction on the number of users to be targeted. Each user may have their own set of specific classes that are logged at different levels.

Available properties and parameters

The following properties and parameters enable and control named user logging. You add them to Integrated Solutions Console to highlight user interactions with the application in the log files.

Enable logging for a targeted user

The following property enables named user logging for a targeted user:
nexj.enable.user.<username>=all

Where <username> specifies the name of the user to enable logging for.

If you delete this property, named user logging is disabled for the specified user.

Specify logging level for a targeted user
Once named user logging has been enabled for a targeted user, you can specify which classes should be logged and at what logging level.

To set the logging level for all classes:
nexj.user.<username>=<logging_level>

Where:

• <username> specifies the name of the user to define logging levels for.
• <logging_level> specifies the logging level for a class or group of classes. The following levels of logging detail are available: off, fatal, severe, warning, audit, info, config, detail, fine, finer, finest, and all.

Use a period and an asterisk (.*) to enable logging for all the subcategories for a component as shown in the following example:
nexj.user.<username>.*=<logging_level>

To set the logging level for a specific class or group of classes:
nexj.user.<username>.<classname>=<logging_level>

Where <classname> specifies the class to define logging levels for. The class name can be either a full or a partial class name. Partial category names must be appended with an asterisk (.*).

Properties and parameters used for named logging

The following example defines separate logging for three different users, at various levels of logging detail.

• For the first user, activities will be logged for the nexj.model.class.User class at the all level. All other activities will be logged at the fine level.

  nexj.enable.user.first1.last1@DOMAIN.EXT=all:
  nexj.user.first1.last1@DOMAIN.EXT.model.class.User=all:
  nexj.user.first1.last1@DOMAIN.EXT=fine:

• For the second user, all activity for all classes will be logged at the finest level.
  

  nexj.enable.user.first2.last2@DOMAIN.EXT=all:
  nexj.user.first2.last2@DOMAIN.EXT=finest:

• For the third user, activities will be logged for the nexj.core.rpc.http.session.SessionManager class and all the nexj.core.persistence classes at the all level. The logging level for all other activity will be inherited from the server defaults.
  
  

  nexj.enable.user.first3.last3@DOMAIN.EXT=all:
  nexj.user.first3.last3@DOMAIN.EXT.core.rpc.http.session.SessionManager=all:
  nexj.user.first3.last3@DOMAIN.EXT.core.persistence=all:

Configuring component logging

Component logging enables logging of specific components of the model for troubleshooting purposes. For example, you can enable logging for a class in the business model layer, such as the user class.

You define which component to log using the following syntax:
nexj.model.<componenttype>.<identifier>=<logging_level>

Where <componenttype> indicates the component type, identifier refers to the associated component name, and <logging_level> indicates the logging level for the component.

For example, to enable logging for the user class, add the following to the log level details specification in Integrated Solutions Console:

nexj.model.class.User=detail

Use a period and an asterisk (.*) to enable logging for all the subcategories for a component. In the following example, logging is enabled for all NexJ forms.
nexj.model.form.*=detail

Available component types

The following table lists the component types that are available for logging.

Configuring exception logging in WebSphere environments

By default, all exceptions are logged and include JVM stack traces and, where applicable, include the NexJ model stack trace.  An example is shown below:

Unknown formula validate error: java.lang.ArithmeticException: / by zero
 at nexj.core.meta.Primitive.divide(Primitive.java:5692)
 at nexj.core.meta.Primitive$46.invoke(Primitive.java:631)
 at nexj.core.meta.Primitive.divide(Primitive.java:5812)
 at Formula.validate(text)$main(class:Formula.validate(text)$main:17)
 at Formula.validate(text)$main(class:Formula.validate(text)$main:4)
 at Formula.testFormulaValidationWithFields(unittest:Formula.testFormulaValidationWithFields:68)
 at ---.---(---:0)
 at nexj.core.scripting.Machine.invoke(Machine.java:748)
 at nexj.core.testing.unit.UnitTestPlayer.run(UnitTestPlayer.java:695)
 at nexj.core.testing.unit.UnitTestPlayer.run(UnitTestPlayer.java:500)
 at nexj.core.tools.UnitTestTool.runTests(UnitTestTool.java:507)
 at nexj.core.tools.UnitTestTool.end(UnitTestTool.java:569)
 at nexj.core.tools.GenericTool.run(GenericTool.java:131)
 at nexj.core.tools.UnitTestTool.main(UnitTestTool.java:826)

The ---.---(—:0) stack trace element acts as a separator between the Java stack traces (below) and NexJ stack traces (above) so that you can easily find the NexJ model stack trace. You can configure this behavior by using the following log categories:

• nexj.core.scripting.Machine.java:off (suppresses Java portion)
• nexj.core.scripting.Machine.scm:off (suppresses NexJ model portion)

If both are disabled then the Java portion is still included.

Logging activity in NexJ Server environments

All NexJ applications running on NexJ Server use Apache log4j, a Java-based logging utility, to generate log files.

By default, Log4j uses a configuration file called log4j.properties. It is located in the <SERVER_HOME>\conf directory. You can modify the file to customize logging functionality for your specific business needs, such as logging information for individual users or specific components of the model.

Log files are output to a directory specified in the log4j.properties file and can be opened using a text editor. By default, log files output to <SERVER_HOME>\log\<nodename>.log, where <nodename> is the name of the node. A separate log file is output for each node in a cluster.

NexJ Server supports runtime logging changes when it is run in standalone mode.

An alternate configuration file can be specified by passing log4j.configuration as a JVM argument when starting the server. For example:
modeld.bat "-Dlog4j.configuration=C:/log4jdebug.properties"

In this case, log4jdebug.properties will be used to configure Log4j and changes made to the configuration file will take effect every 60 seconds.

Configuring named user and component logging

You can enable named user and component type logging by specifying properties in the log4j.properties file.

Named user logging enables you to target specific users for detailed logging without changing the general logging level for the rest of the user base. Filtering log information for individual users helps troubleshoot issues in a production environment with minimal performance overhead.

Component logging enables you to log specific components of the model for troubleshooting purposes. For example, you can enable logging for a class in the business model layer, such as the user class.

To configure logging:

1. Open the log4j.properties file using a text editor.
   By default, the log4j.properties file is located in the <SERVER_HOME>\conf directory.
2. Add properties to the file for the users and components that you want to log.
   Note: Named user logging occurs only for users identified in the log4j.properties file who are authenticated in the NexJ application.
3. Save your changes and close the log4j.properties file.

Log messages for each user and each component specified in the log4j.properties file will be output in the application's log file.

Changes to the log4j configuration file can take up to one minute to take effect.

Log4j categories for enabling named user logging

Enable and configure named user logging by specifying user and class properties in the log4j.properties file. Categories define the users that are highlighted in log files and control their level of logging detail.

You need to add two types of category tags for named user logging:

• Enable named user logging for a specific user.
• Specify the logging level and which classes should be logged for the user.

Named user logging has no restriction on the number of users to be targeted. Each user may have their own set of specific classes that are logged at different levels.

Named user logging highlights user actions in application log files. By default, application logs do not contain a user reference:

2015-12-11 15:44:33,134 DUMP [nexj.core.rpc.http.session.SessionManager]
 (http-127.0.0.1-8080-6:[SessionId=C4616C6EE08438F96145E1A9B42B0F28.node1]) Started
 intercept

Whereas named user logging prints the name of the user in the details:

2015-12-11 15:44:33,134 DUMP
 [nexj.user.username.core.rpc.http.session.SessionManager] (http-127.0.0.1-8080-6:
[SessionId=C4616C6EE08438F96145E1A9B42B0F28.node1]) Started intercept

Available properties and parameters

The following properties and parameters enable and control named user logging. You add them to the log4j.properties file to highlight user interactions with the application in the log files.

Enable logging for a targeted user

The following property enables named user logging for a targeted user:
log4j.logger.nexj.enable.user.<username>=ALL

Where <username> specifies the name of the user to enable logging for.

To disable named user logging for the specified user without restarting the server, set the priority value to OFF.
log4j.logger.nexj.enable.user.<username>=OFF

If you delete this property, you will need to restart the server before named user logging is disabled for the specified user.

Specify logging level for a targeted user

Once named user logging has been enabled for a targeted user, you can specify which classes should be logged and at what logging level.

To set the logging level for all classes:
log4j.logger.nexj.user.<username>=<logging_level>

Where:
• <username> specifies the name of the user to define logging levels for.
• <logging_level> specifies the logging level for a class or group of classes. The following levels of logging detail are available in log4j: OFF, FATAL, ERROR, WARN, INFO, DEBUG, TRACE, and ALL.

To set the logging level for a specific class or group of classes:
log4j.logger.nexj.user.<username>.<classname>=<logging_level>

Where <classname> specifies the class to define logging levels for. The class name can be either a full or a partial class name.

Log4j properties and parameters used for named logging

The following example defines separate logging for three different users, at various levels of logging detail.

• For the first user, log4j will log the activity for the nexj.model.class.User class at the ALL level. All other activities will be logged at the DEBUG level.

  log4j.logger.nexj.enable.user.first1.last1@DOMAIN.EXT=ALL
  log4j.logger.nexj.user.first1.last1@DOMAIN.EXT.model.class.User=ALL
  log4j.logger.nexj.user.first1.last1@DOMAIN.EXT=DEBUG

• For the second user, all activity for all classes will be logged at the DEBUG level.

  log4j.logger.nexj.enable.user.first2.last2@DOMAIN.EXT=ALL
  log4j.logger.nexj.user.first2.last2@DOMAIN.EXT=DEBUG

• For the third user, log4j logs all activity for the nexj.core.rpc.http.session.SessionManager class and all the nexj.core.persistence classes at the ALL level. The logging level for all other activity will be inherited from the server defaults.

  log4j.logger.nexj.enable.user.first3.last3@DOMAIN.EXT=ALL
  log4j.logger.nexj.user.first3.last3@DOMAIN.EXT.core.rpc.http.session.SessionManager=ALL
  log4j.logger.nexj.user.first3.last3@DOMAIN.EXT.core.persistence=ALL

Configuring component logging

Component logging enables logging of specific components of the model for troubleshooting purposes. For example, you can enable logging for a class in the business model layer, such as the user class.

You define which component to log using the following syntax:
nexj.model.<componenttype>.<identifier>

Where <componenttype> indicates the component type and <identifier> refers to the associated filename.

For example, to enable logging for the user class, add the following to the log4j.properties file:
nexj.model.class.User=ALL

Available component types

The following table lists the component types that are available for logging.

Configuring exception logging in NexJ Server environments

The configuration is the same as for WebSphere server environments but the log settings are:

• nexj.core.scripting.Machine.java=OFF (suppresses Java portion)
• nexj.core.scripting.Machine.scm=OFF (suppresses NexJ model portion)