Logging client messages in the z/OSMF log

For more information about the z/OSMF log, including how to access and view the log, see the topic about working with z/OSMF runtime log files in IBM z/OS Management Facility Configuration Guide.

Setting up client side logging

To implement client side logging, add code to your plug-in that:

• Specifies the name and location of the Dojo package that contains the client side logger.
• Imports the client side logger package.
• Creates an instance of the client side logger, and assigns a unique identifier to the logger. To uniquely identify your plug-in's client side logger, include the name of your company, product, and module in the identifier, and specify "ui" as the lower level qualifier. For example, com.ibm.zosmf.NavigationTree.ui.
• Defines the methods for the logging levels to be included in the z/OSMF log. The logging levels include: FINE, FINER (trace), FINEST (debug), INFO, WARNING, and SEVERE (fatal).
  To help you identify your plug-in's messages in the log, append a prefix to each message that contains the module name, package name, and method name.

  Figure 1. Sample code for creating a log prefix

  var LOGPREFIX=MODULE+" "+PACKAGE_NAME+" "+methodName+": ";
  LOGGER.entering(LOGPREFIX+"entry stuff");

  For sample log data, see Sample z/OSMF client side log data.

• Issues JavaScript log statements that match the logging levels you specified. When issued, the client side logger stores the statements in a message queue until the interval, threshold, or trigger is activated, as follows:

  interval 

  By default, the client side logger sends the queued messages to the z/OSMF log every 60 seconds.

  threshold

  By default, the message queue can contain a maximum of 50 JavaScript log statements. When this threshold is reached, the client side logger sends the queued messages to the z/OSMF log.

  trigger

  By default, the push level for the client side logger is INFO. When the severity of a JavaScript log statement equals or exceeds the push level, the client side logger sends the queued messages to the z/OSMF log.

  Note: To prevent denial of service attacks or filling the log with useless data, the client side logger logs only messages that your plug-in issues on behalf of z/OSMF authenticated users.

Sample code for setting up client side logging

Figure 2 provides sample code that you can use as a reference when setting up the client side logger.

var dojoConfig = {
isDebug:      false,
parseOnLoad:  false,
usePlainJson: true,
async: true,

//Specify the name and location of the client side logger package.
packages: [{name: "izuLogger", location: "/zosmf/IzuUICommon/js"}]
};

//Import the client side logger package.
require(["izuLogger/izuUILogger/log4js17"],
	  
function(log4js){
    //Create an instance of the client side logger.
    var LOGGER = log4js.getLogger("com.mycompany.myproduct.mymodule.ui");
    var MODULE = "MYMODULE";
    var PACKAGE_NAME = "MYPACKAGE.jsp";

    //Define methods for logging messages.
    function init(){
        var methodName="init";
        var LOGPREFIX=MODULE+" "+PACKAGE_NAME+" "+methodName+": ";
        LOGGER.entering(LOGPREFIX+"entry stuff");
        LOGGER.finest(LOGPREFIX+"finest stuff");
        LOGGER.finer(LOGPREFIX+"finer stuff");
        LOGGER.info(LOGPREFIX+"info stuff");
        LOGGER.warning(LOGPREFIX+"warning stuff");
        LOGGER.severe(LOGPREFIX+"severe stuff");
        LOGGER.exiting(LOGPREFIX+"exiting stuff");
    }
});

Methods provided for the client side logger

Table 1 lists the methods you can use when setting up the client side logger, and provides summary descriptions and sample JavaScript code for each method.

var LOGGER = log4js.getLogger(
             "com.ibm.zosmf.NavigationTree.ui");

LOGGER.warning(LOGPREFIX+"Test warning message");
LOGGER.severe(LOGPREFIX+" Exception: " + text);

LOGGER.entering(LOGPREFIX+"entry stuff");

LOGGER.exiting(LOGPREFIX+"exiting stuff");

LOGGER.logp(Level.WARNING, PACKAGE_NAME, MODULE, 
   methodName, msg, " targetid=", targetid); 
LOGGER.logp(Level.SEVERE, PACKAGE_NAME, MODULE, 
   methodName, "Exception received attempting 
   to authenticate user", userid, exception); 

if(LOGGER.isLoggable(Level.FINEST)){ 
  LOGGER.finest(LOGPREFIX+ "FTP Host : " 
  + dojo.byId('<%= HADDataAdaptor.FTPHOSTNAME %>').
  value);
}

var msgvars = ["tkdole", 10, "try again"]; 
LOGGER.logMessage("IZUG400E", msgvars);

LOGGER.turnOnTracing();

LOGGER.turnOffTracing();

LOGGER.turnOnPopup();

LOGGER.turnOffPopup();

LOGGER.setLogToConsole(true);
LOGGER.setLogToConsole(false);

LOGGER.flush();

Sample z/OSMF client side log data

The message entries in the z/OSMF log have a uniform structure, which is depicted in Figure 3.

2009-04-29T22:08:09.609Z|00000031|com.ibm.zoszmf.util.log.servlet.UILoggerServlet|UILoggerServlet::doPost()
FINER: [2009-04-29T22:07:13.938Z] ENTRY MYMODULE MYPACKAGE.jsp init: entry stuff
[tx0000000000002183:zosmfad@localhost (POST) /zosmf/IzuUICommon/UILoggerServlet?preventCache=1240947046138]
2009-04-29T22:08:09.609Z|00000031|com.ibm.zoszmf.util.log.servlet.UILoggerServlet|UILoggerServlet::doPost()
FINER: [2009-04-29T22:07:13.474Z] RETURN MYMODULE MYPACKAGE.jsp init: exiting stuff
[tx0000000000002184:zosmfad@localhost (POST) /zosmf/IzuUICommon/UILoggerServlet?preventCache=1240946722135]

If the log record includes an exception, the exception class and the message text are logged next followed by the traceback information that is embedded in the exception. If the exception has attached causes, each cause is also logged with "+->" indicating the start of an attached cause.