Oracle9iAS Release 2 Containers for J2EE - Logging and Debugging

Introduction

As any good developer or administrator will tell you, comprehensive and flexible logging and debugging facilities go a long way to making their lives easier. Good logging and debugging facilities helps them to quickly track down and identify when and why an unexpected result or situation is occurring. Oracle9iAS Containers for J2EE (OC4J) provides these types of logging and debugging facilities. It enables the logging of specific events, errors, and exceptions that may be useful in troubleshooting problems. Similarly, it also enables the setting of specific debugging options to display details on what is happening behind the scene as as applications are running. In this article we will discuss the logging and debugging facilities in OC4J you can use.

OC4J is available in two different forms:

• Standalone: A standalone version of OC4J is available for download from the Oracle Technology Network (OTN). The standalone version is ideally suited to the development and testing of J2EE applications. The standalone version of OC4J has its own HTTP server, and is started and stopped manually. Configuration of the standalone version is performed by direct manipulation of the XML configuration files.
  
  
• Embedded within Oracle9iAS: OC4J is installed as a core component of Oracle9iAS Release 2 and provides the Java runtime for a lot of the other components of Oracle9iAS. In an Oracle9iAS installation, one or more instances of OC4J are started, managed, and monitored by the high availability infrastructure provided. This high availability infrastructure is called OPMN, for more details on OPMN please see the Oracle9iAS Release2 Concepts Guide. In this type of installation, the Oracle HTTP Server is configured to listen for HTTP requests and serves as front-end for OC4J. Any requests for J2EE applications running on OC4J are routed to an OC4J process via the mod_oc4j module.

The capabilities and techniques used for logging and debugging are slightly different when using the standalone model and the Oracle9iAS model. In this technical note, we will discuss how can you configure and use logging and debugging in both environments.

Logging in OC4J

OC4J provides several log files that record events generated by the OC4J runtime and applications that have been deployed.. The following table lists the log files.

The location of all of the above log files can be specified (except the web-access.log) using the <log> tag in the respective configuration files. For example you can specify the the server log file to use in the server.xml configuration file.

<log>
<file path="../log/debu-server.log" />
</log>


You can also specify an absolute path for the location of the log file

<log>
<file path="d:\log-files\Debu-server.log" />
</log>

Logging in OC4J Standalone

The following table shows the default location for the log files for a standalone OC4J. You can modify the location and names of these files by making changes in the configuration files as described in the previous section.

Many developers use the System.out.println() and System.err.println() methods in their applications to generate debugging formation. Normally the output from these method calls go to the console where the OC4J process is started. However you can specify command line options when starting OC4J to direct the stdout and stderr output directly to files. The ?out and ?err parameters tell OC4J which file to direct the

$ java -jar oc4j.jar -out d:\log-files\oc4j.out -err d:\log-files\oc4j.err

In this case all information written to stdout and stderr will be stored in the files d:\log-files\oc4j.out and d:\log-files\oc4j.err respectively.

Logging in an Oracle9iAS Environment

In an Oracle9iAS environment, an OC4J instance can is created and managed from the Enterprise Manager console. An OC4J instance can be configured to run as a single process or as multiple processes - think of an OC4J instance as a set of configuration files, and the OC4J processes simply as a set of runtimes that share the configuration information and deployed applications. The OC4J processes are managed by OPMN. Each OC4J process will have a set of log files. If there are multiple processes running for an OC4J instance, there will be multiple set of log files. The following table shows the default location for log files for an OC4J process

In an Oracle9iAS environment, the standard output and standard errors for OC4J are routed to the OPMN log for the OC4J instance. For example, if you have an OC4J instance called OC4J_Demos, and it has an island called default_island, and there is only one process in the island, the file that will contain the stdout, stderr streams will be $ORACLE_HOME/opmn/logs/OC4J_Demos.default_island.1

You can specify the ?out and ?err parameters in an Oracle9iAS environment by specifying a set of OC4J options for your OC4J Instance. This is shown in Figure 1. When you specify these parameters without specifying a specific directory, the log files will be created in the $ORACLE_HOME/j2ee/home/<OC4J InstanceName>_<Island Name>_<Process#> directory.

For example, if you have an OC4J instance called OC4J_Demos and it has an island called default_island, then the log file will be created in the $ORACLE_HOME/j2ee/home/OC4J_Demos_default_island_1

In the preceding examples it is assumed that there is only one OC4J process for the default island. If there are more processes for an island there are separate log files for each OC4J process.

Fig 1: EM Console to modify Server Properties for an OC4J instance

Debug Options in OC4J

OC4J provides several debug options for you to use to generate additional information on the operations performed by the various sub-systems of OC4J. These debug options can be set for a particular sub-system while starting up OC4J either in standalone or in an Oracle9iAS environment. Following are few debug options available with Oracle9iAS Release 2. Please note that some of these debug options may become obsolete in future releases of Oracle9iAS or Oracle may introduce completely different mechanism for debugging in future. Also worth noting is that turning on excessive debug options can potentially slow down the execution of your applications and use large amounts of disk space with the contents of the log files.

The following table provides the different debug options that available with OC4J. These debug options have two states either true or false. By default these are set to false.

In addition to the specific sub-system switches, you can also start OC4J with a supplied verbosity level. The verbosity level is an integer between 1 and 10. For example you can start OC4J standalone as follows:

java -jar oc4j.jar -verbosity 5

The higher the verbosity level, the more information that is printed in the console. In an Oracle9iAS environment you can specify the verbosity level using EM in the OC4J options area. An example of the output provided at verbosity level 5 is shown below.

D:\java\oc4j-902-production\j2ee\home>java -jar oc4j.jar -verbosity 5
Application default (default) initialized...
Application cmpapp (cmpapp j2ee application) initialized...
Application threadload (ThreadLoad Test) initialized...
Application fiscus-bean (fiscus-bean) initialized...
Application TestFilter (webapp1) initialized...
Web-App default:defaultWebApp (0.0.0.0/0.0.0.0:8888) started...
Oracle9iAS (9.0.2.0.0) Containers for J2EE initialized

Debugging OC4J in a Standalone Environment

You can start OC4J with one or more debug options. The default value for the debug options is false and must be explicitly set to true to become active. For example, if you want to generate debug information on HTTP session events then you will start OC4J as follows:

java -Dhttp.session.debug=true -jar oc4j.jar

After OC4J is started with a specific debug option, debug information will be generated and routed to standard output.  For example you will see HTTP session information on your OC4J console as follows:

Oracle9iAS (9.0.2.0.0) Containers for J2EE initialized
Created session with id '36c04d8a1cd64ef2b6a9ba6e2ac6637e' at Mon Apr 15 12:24:20 PDT 2002, secure-only: false
Created session with id '36c04d8a1cd64ef2b6a9ba6e2ac6637e' at Mon APR 15 12:36:06 PDT 2002, secure-only: false
Invalidating session with id '36c04d8a1cd64ef2b6a9ba6e2ac6637e' at Mon APR 15 12:44:32 PDT 2002
(created at Mon APR 15 12:24:23 PDT 2002) due to timeout

java -Dhttp.session.debug=true -jar oc4j.jar -out oc4j.out -err oc4j.err

Debugging OC4J in an Oracle9iAS Environment

By default the debug information will be written to the OPMN log file for the OC4J instance. This log file normally resides in the $IAS_HOME/opmn/logs/ directory. For example you have a OC4J instance named OC4J_DEMOS and there is only one island and the island has only process for this OC4J instance these debug information will be logged in $IAS_HOME/opmn/logs/OC4J_Demos.default_island.1

However if there is ?out and ?err parameters specified with OC4J as depicted in Fig 1 then these debug information will be redirected to the appropriate files.

Typical Scenario for Debugging

Now that we have learnt the debugging options in OC4J we take a loot at some scenarios to see where and how to set helpful debugging options.

Servlet Debugging Example

Let?s assume that you have deployed a web application to OC4J and you are having some problems with the Servlets. For example, you are losing the client session when you use a pre-configured DataSource to make database connection. You want to know what OC4J is doing when the Servlet is accessing the DataSource. In order to generate the debug information on HTTP Session and DataSource usage you need to set two debug options - http.session.debug and  datasource.verbose to true.

For the standalone OC4J, you can set these debug options on the command line when you start OC4J as follows:

java -Dhttp.session.debug=true  -Ddatasource.verbose=true -jar oc4j.jar

For OC4J in an Oracle9iAS R2 environment you have to perform the following tasks

1)      Logon to EM console as administrator.

2)      Select the OC4J instance from IAS Home Page in EM

4)    Then enter Java Options as follows: -Dhttp.session.debug=true  -Ddatasource.verbose=true

5)     Restart the OC4J instance

After the OC4J instance is restarted you can execute your servlet and you will see the following type of debug information in the standard output for the OC4J instance

DataSource logwriter activated... jdbc:oracle:thin:@localhost:1521:DEBU: Started
jdbc:oracle:thin:@localhost:1521:DEBU: Started
Oracle9iAS (9.0.2.0.0) Containers for J2EE initialized
Created session with id '4fa5eb1b9a564869a426e8544963754f' at Tue APR 23 16:22:56 PDT 2002, secure-only: false
Created new physical connection: XA XA Orion Pooled jdbc:oracle:thin:@localhost:1521:DEBU
null: Connection XA XA Orion Pooled jdbc:oracle:thin:@localhost:1521:DEBU allocated (Pool size: 0)
jdbc:oracle:thin:@localhost:1521:DEBU: Opened connection
Created new physical connection: Pooled oracle.jdbc.driver.OracleConnection@5f18
Pooled jdbc:oracle:thin:@localhost:1521:DEBU: Connection Pooled oracle.jdbc.driver.OracleConnection@5f1832 allocated (Pool size: 0)
Pooled jdbc:oracle:thin:@localhost:1521:DEBU: Releasing connection Pooled
oracle.jdbc.driver.OracleConnection@5f1832 to pool (Pool size: 1)
null: Releasing connection XA XA Orion Pooled jdbc:oracle:thin:@localhost:1521:DEBU to pool (Pool size: 1)
Orion Pooled jdbc:oracle:thin:@localhost:1521:DEBU: Cache timeout, closing connection (Pool size: 0)
com.evermind.sql.OrionCMTDataSource/default/jdbc/OracleDS: Cache timeout, closing connection (Pool size: 0)

Remote Debugging Using Oracle9i JDeveloper

You can remotely debug your applications deployed in OC4J using any Java debugging facility that supports the JPDA (Java Platform Debugging Architecture). Oracle's great Java IDE, Oracle9i JDeveloper, provides a very convenient and feature rich debugging environment for OC4J. With OC4J being embedded directly inside of the Oracle9i JDeveloper IDE, debugging both locally deployed and remote J2EE applications is a snap. For more details, please see the Oracle9i JDeveloper documentation or take a look at the Remote Debugging How-To documents that are posted on OTN.

Conclusion

In this article we discussed how can you use different logging and debugging facilities in OC4J. Inappropriate and excessive use of debugging and logging and slow down your OC4J server and applications so use these options in an intelligent manner only when you require them.