FAQ #33 - How to configure ADF diagnostics logging in WLS, Pt. 3

Introduction

In this third installment of posts related to the configuration of ADF diagnostics logging we will focus on the following topics: 1) how logs could be added programmatically to the diagnostics log, 2) how new Loggers could be added and configured to the diagnostics logging configuration and 3) how to dynamically configure the WebLogic diagnostics logging. This includes changing the logging levels for the configured loggers at run-time without the need to restart the server.


Main Theme

For some background information regarding diagnostics logging as it relates to ADF, JDeveloper and WebLogic refer to these earlier posts: FAQ #6 - How to fine tune ADF diagnostics logging in JDeveloper 11g R1  , FAQ #7 - How to configure ADF diagnostics logging in standalone WLS using JDeveloper 11g R1 and FAQ #8 - How to perform log analysis using the Diagnostic Log Analyzer in JDeveloper 11g . The main advantages of using Oracle Diagnostics Logging (ODL) when compared to other logging frameworks is its tight integration with WebLogic and JDeveloper. In WebLogic, the logs produced conform to and integrate with the diagnostics logging facility. Diagnostic logs include in addition to the message logged additional information such as the session and user that produced the log entry at run-time. This is essential when analyzing the logs. In JDeveloper the log configuration and analysis is integrated via the Oracle Diagnostics Logging Configuration and Oracle Diagnostics Log Analyzer respectively. Both are discussed in detail in the above referenced posts.

Programmatic Usage

Diagnostic logs can be generated programmatically from within your code by using the ADFLogger class. You simply instantiate an ADFLogger via the static createADFLogger() method and use its log() method. log() accepts a java.util.logging.Level parameter indicating the log level of the message that you are logging and it can be any of the ADFLogger.INTERNAL_ERROR, ADFLogger.ERROR, ADFLogger.WARNING, ADFLogger.NOTIFICATION and ADFLogger.TRACE. You can also use the severe(), warning(), info(), config(), fine(), finer() and finest() methods to do your logging. Here is an example:

// create the ADFLogger
private ADFLogger logger = ADFLogger.createADFLogger("package.class");
// log a trace
logger.log(ADFLogger.TRACE, "A trace log");


Configuration of Custom Loggers in JDeveloper

In the ADFLogger example above, "package.class" is a custom logger which is associated with the ADFLogger. You will need to configure this custom logger in the diagnostics logging configuration file logging.xml. Ensure that you load the appropriate logging.xml file for the WebLogic server you are configuring. The file can be found in the domain config\fmwconfig\servers directory for each server. So, open the appropriate logging.xml configuration file in JDeveloper and create a custom logger called "package.class" by clicking on the Add Logger icon as it shown below.

In the Add Persistent Logger dialog that is presented add the logger class specified above in the ADFLogger (i.e. package.class), set its logging level and click OK.

The custom logger will appear in the list of Loggers as it shown below. With its logging level set appropriately, your trace log in the earlier example will show in the diagnostics log.

Dynamic Configuration of Logging in WebLogic

Diagnostics logging can be configured dynamically in WebLogic via the wlst tool. Ensure that you run the wlst script located in the oracle common directory  - %MIDDLEWARE_HOME%\oracle_common\common\bin for a JDeveloper installation - and not the one under the WebLogic server home - %MIDDLEWARE_HOME%\wlserver_10.3\common\bin for the stand-alone WebLogic installed along with JDeveloper. The former provides custom commands for configuring diagnostics logging. First you will need to connect to the admin server via the connect() command as in connect('weblogic','weblogic1','t3://address:7001'). To change the logging level for the custom logger class above, use the setLogLevel() command as in setLogLevel(target="ManagedServer1", logger="package.class", level="ERROR"). Specify the target WebLogic server with the target= argument (ManagedServer1 in this example), the logger class with the logger= argument and the new logging level with the level= argument. It can be either a Java level or an ODL level. Some valid Java levels are: SEVERE, WARNING, INFO, CONFIG, FINE, FINER, or FINEST. Valid ODL levels include a message type followed by a colon and a message level. The valid ODL message types are: INCIDENT_ERROR, ERROR, WARNING, NOTIFICATION, TRACE, and UNKNOWN. The message level is represented by an integer value that qualifies the message type. Possible values are from 1 (highest severity) through 32 (lowest severity). Additional commands for dynamic configuration of the diagnostics log will allow you to configure the Log Handler for each logger class, display the currently configured loggers and so on. For more details, check out the documentation references sited below.



Conclusion

If you are considering a logging framework for an application to be deployed on WebLogic, I suggest that you take a closer look at the Oracle Diagnostics Logging facility. Its tight integration with JDeveloper (logging configuration and log analysis) and WebLogic (diagnostics log format, dynamic configuration) makes it a comparable choice.

Until the next time, keep on JDeveloping!


References

Logging Custom WLST Commands
Using Custom WLST Commands

FAQ #8 - How to perform log analysis using the Diagnostic Log Analyzer in JDeveloper 11g

Introduction

When it comes to diagnostics logging, a possibly lesser known feature of JDeveloper is its ability to perform log analysis. Known as the Oracle Diagnostic Log Analyzer, it allows the developer to open a diagnostics log file and do a limited yet useful log analysis. Let's see how it works.

Main Theme

To demonstrate this FAQ, let's create a sample Fusion Web Application (Web) based on the HR schema. Let's create an Employee entity from the EMPLOYEES table and an Employees view based on the Employee entity. Finally, let's bundle the Employees view in the HrAppModule application module.

For the ViewController let’s create a View Activity called Employees directly in the unbounded adfc-config task flow and an Employees.jspx JSF page for the Employees View Activity. Finally, let’s drag the Employees view from the HrAppModuleDataControl in the Data Controls and drop it onto the Employees.jspx JSF page as an ADF Form.

In order to generate detailed diagnostic log entries, bring up the ViewController Project Properties dialog and in the Run/Debug/Profile page select the Default run configuration and click Edit.... In Launch Settings specify -Djbo.debugoutput=console for the Java Options.

Save the project settings and run the application. Detailed log entries should have been generated in the JDeveloper Log console.

Take a look at the Actions menu at the top right of the Log window. Clicking on it will display a menu from which we can select Analyze Log | Current in Console.

Let's do just that - go ahead and select it. This will bring up the Oracle Diagnostic Log Analyzer window.

We will use the Diagnostic Log Analyzer to do some elementary analysis for the log generated while running the sample application. Select all of the log levels (Incident Error, Error, Warning, Notification, Trace and Unknown for ODL Log Levels) and search for the word "select" in the Message Text. All SELECT SQL statements will be identified in the log and displayed in the Results section.

To group the log messages by time period or by request, in the Related column, select either Related by Time or Related by Request.

What makes things a bit more interesting is the ability to load a log file generated by some other application or by another server - a WLS log file for example - into the Diagnostic Log Analyzer and do some analysis on it. Let's try it: click on the Browse Log Files icon and select a WLS log file to open. Then do some analysis on it.

Finally, note that the Oracle Diagnostic Log Analyzer is also available directly from the Tools menu.

Conclusion

Using the Oracle Diagnostic Log Analyzer in JDeveloper to perform log analysis could prove to be just another "little" tool that does a "big" job when dealing with the chaos of thousand-line diagnostics log files. It is simple and easy to use, so give it a try.

Until the next time, keep on JDeveloping!

Code

http://jdeveloperfaq.googlecode.com/files/JDeveloperFAQNo8.rar

FAQ #7 - How to configure ADF diagnostics logging in standalone WLS using JDeveloper 11g R1

Introduction

In FAQ #6 - How to fine tune ADF diagnostics logging in JDeveloper 11g R1 we’ve seen how to configure diagnostics logging for the integrated WLS in JDeveloper. Configuration of diagnostics logging for the standalone WLS can be done in a similar fashion. Let’s take a look.


Main Theme

For some basic information regarding ADF diagnostics logging refer to FAQ #6 - How to fine tune ADF diagnostics logging in JDeveloper 11g R1. We will repeat some of the introductory information here as it applies to the standalone WLS.

ADF diagnostics logging is controlled via the usage of the jbo.debugoutput parameter. Using this parameter with the console value, i.e. -Djbo.debugoutput=console, produces diagnostic logs directly in the JDeveloper Log console window when deploying and running an application on the integrated WLS in JDeveloper. When set to the ADFLogger value, diagnostics are routed through the standard J2SE Logging API and are controlled through the logging.xml configuration file. For the standalone WLS this file can be found in the %MIDDLEWARE_HOME%\user_projects\domains\%DOMAIN_NAME%\config\fmwconfig\servers\%SERVER_NAME% for the Windows operating systems.

%MIDDLEWARE_HOME% is the installation directory of the standalone WLS, %DOMAIN_NAME% and %SERVER_NAME% are the WLS domain and server that we are configuring. For information on how to setup the standalone WLS, take a look at FAQ #1 – How to configue the standalone WebLogic server for deploying ADF applications from JDeveloper 11g R1 (11.1.1.2.0).

Let's locate the logging.xml file in the above directory and drag and drop it on JDeveloper.

JDeveloper will open the file and display it in the Overview tab.

In order to produce detailed diagnostic logs for the ADF BC oracle.jbo classes, we need to set the log Level to at least FINE. Let's set it to the most detailed level FINEST - TRACE:32 if using ODL Log Levels - for the oracle.jbo logger. Also let's ensure that the odl-handler log handler is configured to generate diagnostics for all log levels. To verify, select the odl-handler in the structure window and ensure that the level attribute is set to ALL.

Lastly we need to specify the -Djbo.debugoutput=adflogger -Djbo.adflogger.level=FINEST parameters when starting the standalone WLS, so let's open the setDomainEnv.cmd domain environment settings script in the %MIDDLEWARE_HOME%\user_projects\domains\%DOMAIN_NAME%\bin directory and add the following line:

set JAVA_OPTIONS=%JAVA_OPTIONS% -Djbo.debugoutput=adflogger -Djbo.adflogger.level=FINEST

That's all there is to it! Now let's start the standalone WLS, deploy and run our application. Take a look at FAQ #3 - How to deploy an ADF application on a standalone WebLogic server directly from JDeveloper for information on how to deploy an application onto WLS.

You should see those familiar ADF BC oracle.jbo diagnostic logs come flying in the WLS log window!

Conclusion

ADF Diagnostics Logging for the standalone WLS is done through the logging.xml file in a similar fashion as for the integrated WLS. It is a powerful feature that allows us to fine tune the log generation of our application and much more.

Until the next time, keep on JDeveloping!

FAQ #6 - How to fine tune ADF diagnostics logging in JDeveloper 11g R1

Introduction

FAQ #2 – How to enable debug information generation for an ADF BC project demonstrated a simple rather known technique to generate diagnostics logging in the JDeveloper Log window when testing an ADF BC application module with the BC tester. This barely scratched the surface of what is actually available in JDeveloper concerning diagnostics logging.

Main Theme

ADF diagnostics logging is controlled via the usage of the jbo.debugoutput parameter. Using this parameter with the console value, i.e. -Djbo.debugoutput=console, produces diagnostic logs directly in the JDeveloper Log window. When set to the ADFLogger value, diagnostics are routed through the standard J2SE Logging API and is controlled through the logging.xml configuration file. For the integrated WebLogic server this file can be found the C:\Users\username\AppData\Roaming\JDeveloper\ system11.1.1.x.x.x.x\DefaultDomain\config\fmwconfig\servers\DefaultServer for Windows 7 and in the C:\Documents and Settings\username \ApplicationData\JDeveloper\system11.1.1.x.x.x.x \DefaultDomain\config\fmwconfig\servers\DefaultServer for older Windows versions.

Let’s take a closer look:

In the Application Server Navigator – use View | Application Server Navigator to display if needed – expand the Application Servers node and right-click on the IntegratedWebLogicServer connection. This connection is generated automatically by JDeveloper for accessing the integrated WebLogic server. From the context menu select Configure Oracle Diagnostic Logging for “IntegratedWebLogicServer”.

JDeveloper opens the logging.xml diagnostics logging configuration file and displays it in the Overview tab. In the Loggers section expand the Root Logger (default) node to display all the loggers that are declared.

The three columns in the Overview tab display the Name of the logger, the diagnostics logging Level for the logger and any log handlers associated with the logger. The Name of the logger represents the Java package that will be generating the specific diagnostics logs. The Level value specifies the granularity of the diagnostic logs to be generated and it is defined either in terms of the ODL (Oracle Diagnostics Logging) Log Levels below

or as any of the Java Log Levels below

You can control the Log Level type (ODL or Java) through the drop down on the top right just above the Declares Handles column.

The Declares Handles column associates one or more log handlers to the specific logger. To illustrate, select a logger that has an associated log handler - an icon in the Declares Handles column - and expand the Handler Declarations section to display the associated log handlers.

The definition of the loggers in the Overview tab is hierarchical and is derived from top-down. For example: a logger that is specified at the oracle package level, applies to all other loggers below in the same hierarchy (oracle.*) unless it is overwritten.

All of this information and more is accessible in the Structure window. Let’s expand the logging_information node and then the log_handler node and let’s take a closer look at two of those log handlers:

 console-handler

This handler will log diagnostics to the console. Observe that the level attribute is set to ALL. This will allow the hander to log diagnostic messages for all log levels.

odl-handler
This handler will log ODL diagnostics to a log file. Expand the odl-handler log_handler node and observe the path property. It points to the location of the log file where the diagnostic logs will be saved. It is set to ${domain.home}/servers/${weblogic.Name}/logs/${weblogic.Name}-diagnostic.log, which is the C:\Users\username\AppData\Roaming\JDeveloper\system11.1.1.2.*.*.*\DefaultDomain\servers\DefaultServer\logs\ DefaultServer-diagnostic.log file in Windows 7.

OK. Let's generate some diagnostics now. Select the oracle.jbo logger in the Loggers tree and set its Level to FINEST – you may need to switch the log type to Java Log Types. This will override the default setting of the Root Logger in order to log all diagnostics generated by the oracle.jbo classes. There is no need to declare a specific handler, the one(s) defined for the Root Logger will be used as long as we ensure that the Use Parent Handlers checkbox remains selected. Make sure that you save the logging.xml file.

Before running your application open the ViewController Project Properties dialog, select the Run/Debug/Profile page and Edit… the Run Configuration. In the Edit Default Configuration dialog Launch Settings enter -Djbo.debugoutput=adflogger -Djbo.adflogger.level=FINEST in the Java Options.

Save the Project Properties and run your application. Observe the oracle.jbo diagnostic logs generated in the Log window. The same log entries are written in the C:\Users\username\AppData\Roaming\JDeveloper\system11.1.1.2.*.*.*\DefaultDomain\servers\DefaultServer\logs\ DefaultServer-diagnostic.log file as well.

Conclusion

ADF Diagnostics Logging is a powerful feature in JDeveloper. Through simple configuration, it allows you to fine tune the log generation of your application and much more.

Until the next time, keep on JDeveloping!

Code

http://jdeveloperfaq.googlecode.com/files/JDeveloperFAQNo6.rar