B
Activating Logging and Tracing

Each tier of the Enterprise Manager framework such as the Console, Management Server, and Intelligent Agents supports its own tracing and logging capabilities.

Both tracing and logging will provide the same detailed information on what actions the component is performing; however, tracing would be used to write data to a display for real-time viewing while logging would be used to redirect trace information to a file to view at a later time.

This appendix will describe how to enable both tracing and logging of the various Enterprise Manager components. The sections include:

• Logging and Tracing Enterprise Manager Client Applications
• Logging and Tracing Management Server
• Logging and Tracing of the Event Handler
• Logging and Tracing the Dynamic Web Site
• Logging and Tracing the Oracle Intelligent Agent
• Tracing Browser-Based Enterprise Manager
• Tracing the Paging Server
• Tracing the SQL Engine
• Tracing the Management Pack Applications

Logging and Tracing Enterprise Manager Client Applications

There are two ways to enable logging and tracing. One method will give you quick results without you having to set environment variables or variables in the ClientConfig.properties file. The other method is more deliberate and will require more time than the quick method because you will have to add properties and values to the ClientConfig.properties file.

Enabling Tracing Quickly

You can obtain information about client applications without setting environment variables or variables in the ClientConfig.properties file.

To obtain information for debugging a specific client application, at the command prompt, type

$ oemapp debug [app]

or

$ oemapp trace [app]

The command enables tracing at level 2 for the client application you specified, and the output is directed to the Console.

For example:

$ oemapp debug console
$ oemapp trace console

Enabling Tracing Deliberately

1. Update the clientConfig.properties files.

   The clientConfig.properties file is located in the $ORACLE_HOME/sysman/config directory.

   When you add logging and tracing parameters in the clientConfig.properties, all client applications will use these settings.

   The following variables can be specified in the clientConfig.properties file:

Table B-1 clientConfig.properties variables

Properties	Values
LOGGING.ENABLED	Boolean value. You can set the variable to true or false. This variable has to be set to TRUE if logging and tracing is needed. Default value is FALSE.
TRACING.ENABLED	Boolean value. You can set the variable to true or false. This variable has to be set to TRUE if logging and tracing is needed. If only this variable is set to TRUE, not all client applications will actually produce tracing. Therefore, if you want logging and tracing, you must also set the LOGGING.ENABLED parameter. Default value is FALSE.
TRACING.LEVEL	Level of tracing desired. Possible values: 2, 3 and 5. 2 = Development tracing. Show all messages. 3 = Admin tracing. Show all warning and errors. 5 = User tracing. Show only errors. Default value is 5.

2. After updating the clientConfig.properties file, set the special environment variable ORACLE_OEM_CLIENTTRACE (name in uppercase) to make the logging and tracing active.

Table B-2 ORACLE_OEM_CLIENTTRACE Examples

Platforms	Examples
Windows	C:\ > SET ORACLE_OEM_CLIENTTRACE=TRUE C:\ > OEMAPP CONSOLE
UNIX csh	$ setenv ORACLE_OEM_CLIENTTRACE TRUE $ oemapp console
UNIX sh	$ ORACLE_OEM_CLIENTTRACE=TRUE $ export ORACLE_OEM_CLIENTTRACE $ oemapp console

Performing Additional JAVA debugging

If you need to perform additional JAVA debugging, you can modify the OEMAPP script file and add debugging parameters. This level of JAVA detail is not necessary in most cases, and is only useful if specific JAVA errors about class mismatches or missing classes are reported.

On Windows

Change

SET JRE=jre -nojit ...rest of commandline...

to

SET JRE=jre -nojit -verbose ...rest of commandline...

On UNIX

Change

JRE="jre ...options... -nojit ...more options...

to

JRE="jre ...options... -verbose -nojit ...more options...

Logging and Tracing Management Server

Logging and tracing of the Management Server, the middle tier, is specified in the OMSCONFIG.PROPERTIES file, located in the $ORACLE_HOME\SYSMAN\CONFIG directory.

Parameters in the Management Server properties file are case sensitive; therefore, specify the parameters in the same case as specified in this section.

Table B-3 OMSCONFIG.PROPERTIES Variables

Properties	Values
LOGGING.ENABLED	Boolean flag. Specifies if the trace information is written to a file. The information will only be written to a file if the TRACING.ENABLED flag is also activated. Possible values are TRUE and FALSE. Default is FALSE.
LOGGING.DIR	Directory in which the OMS.LOG file will be written to. Default value is $ORACLE_HOME\SYSMAN\LOG. On Windows NT, in order to set LOGGING.DIR to a directory of c:\temp, you must use "\\" (in order to escape the "\" character) and set LOGGING.DIR=c:\\temp For example, LOGGING.DIR = C:\\temp\\filename.log If you do not, the \t in c:\temp is read as a tab character and the Management Server fails to start.
LOGGING.FILENAME	Filename to use for the Management Server logging. Default value is OMS.LOG. An index counter will be appended to this file. Every time the maximum size is reached, a new file with the increased index number will be created. At startup the counter is always 0 (zero), and the value of this counter will be increased if the log file reaches its specified maximum size.
LOGGING.MAX_SIZE	Maximum file size of the log file. Default value is 50 MB. When set to 0 (zero), no file limit is imposed, and only 1 OMS.LOG file will be created and used. If a specific size is specified, all of the log files generated will be suffixed with a counter value.
LOGGING.MAX_FILE_CNT	Defines the maximum number of files the log will span at any given time. The cumulative size of all the files would be less than or equal to LOGGING.MAXSIZE. Default value is 2. If LOGGING.MAX_SIZE=0 (unlimited log size), LOGGING.MAX_FILE_CNT will not make sense and hence be ignored.
TRACING.ENABLED	Boolean flag specifying if trace information needs to be generated. If logging is disabled, the trace information will be written to the Console from which the Management Server was started. Possible values are TRUE and FALSE. Default is FALSE.
TRACING.LEVEL	Tracing level to be used. Possible values are: 2 - dev: View all messages 3 - admin: View only critical errors and warnings 5 - user: View only critical errors
LOGGING.SAVE_PREVIOUS_LOG	Boolean flag. Specifies if the previous Management Server log files will be renamed to a filename with a timestamp (format: yyyyMMddHHmmss) to prevent them from being overwritten when the Management Server is started again. Possible values are TRUE and FALSE. Default is FALSE.

The oms.nohup file (the Management Server trace file) is automatically created (on both Windows NT and UNIX). The oms.nohup file has entries corresponding to when the Management Server is started and stopped and if the Management Server restarts itself for any reason. Any critical error messages (for example, running out of sessions, SQL exceptions, and others) are also logged to this file. Any other detailed tracing is directed to the oms.log files (if tracing is turned on)

Logging and Tracing of the Event Handler

The Event Handler is part of the Oracle Management Server. In order to trace the Event Handler, perform the steps to trace the Management Server. Trace information about the Event Handler will be included in the Management Server's trace/log file.

Refer to "Logging and Tracing Management Server", for more information about the properties and values to add to the OMSCONFIG.PROPERTIES file in order to enable tracing.

Logging and Tracing the Dynamic Web Site

Logging and Tracing the Oracle HTTP Server

Use this section only if you are using the Oracle HTTP server installed with the Management Server.

Change or modify the following settings:

1. The log modules need to be present and loaded when the Oracle HTTP server starts. This is the default installation and unless the list of modules and linked in objects has been changed or altered, nothing additional should be done for this step.
2. Modify $ORACLE_HOME/Apache/Apache/conf/httpd.conf

   Oracle HTTP server logging and tracing should be enabled

   # LogLevel: Control the number of messages logged to the error_log.
   # Possible values: debug,info,notice,warn,error,crit,alert,emerg
   Loglevel warn
   
   

The following log files will be created:

• access_log

  The default directory is $ORACLE_HOME/Apache/Apache/logs unless overruled by a CustomLog setting in httpd.conf. This file contains a list of all HTML requests handled by the Oracle HTTP server.

• error_log

  The default directory is $ORACLE_HOME/Apache/Apache/logs unless overruled by the ErrorLog setting in httpd.conf. This file contains a list of all failed HTML requests handled by the Oracle HTTP server.

Logging and Tracing JServ

Use this section only if you are using the Oracle HTTP server installed with the Management Server.

Change or modify the following settings:

1. Modify $ORACLE_HOME/Apache/Jserv/etc/jserv.properties. Make sure the log switch is set to true. You can also specify the location of the jserv log file:

   log=true
   log.timestamp=true
   log.file=<path to jserv log file>/jserv.log
   log.channel.servletException=true
   log.channel.jservException=true
   log.channel.warning=true
   log.channel.servletLog=true
   log.channel.critical=true
   
   

2. Modify $ORACLE_HOME/Apache/Jserv/etc/jserv.properties, and disable the JAVA JIT (Just In Time) compiler to obtain line numbers and more JAVA debug output in exceptions and JAVA tracing.

   Near the top of the file, there is the list command line switches:

   wrapper.bin.parameters=-Xms64m
   wrapper.bin.parameters=-Xmx128m
   

   Add the line:

   wrapper.bin.parameters=-Djava.compiler=NONE
   

The jserv.log is created. The default directory is $ORACLE_HOME/Apache/Jserv/logs unless the value is overruled by the log.file setting in jserv.properties. This file contains all actions the Jserv has performed.

Logging and Tracing the Dynamic Web Site

Modify $ORACLE_HOME/sysman/config/reporting.properties by adding the following lines:

TRACING.ENABLED=true
LOGGING.ENABLED=true
TRACING.LEVEL=2

The reporting.log is created. The default directory is $ORACLE_HOME/sysman/log. This file will contain all the actions the reporting servlets have performed.

Logging and Tracing the Oracle Intelligent Agent

Tracing and logging of the third tier Intelligent Agent enables tracking of all communication between the Intelligent Agent and Management Servers. For information on activating tracing and logging of the Intelligent Agent, refer to the Oracle Intelligent Agent User's Guide.

Tracing Browser-Based Enterprise Manager

If you encounter problems bringing up Oracle Enterprise Manager in a browser, collect tracing information before reporting the problem to Oracle Support Services.

To set up tracing for your browser perform the following steps:

1. Exit your browser session
2. Start the Java plug-in Console.

   From the Windows Start menu, select Programs > JInitiator Control Panel. A Java Plug-in Properties window appears.

   1. Select the Show Java Console box.
   2. In the Java Run Time Parameters box, append the following to the end of the line:

      -DTRACING.ENABLED = TRUE -DTRACING.LEVEL = 2
      
      

   3. Click Apply.
   4. Close the Oracle JInitiator Properties dialog.
3. Restart your browser and Oracle Enterprise Manager.

   The Java Console window appears, showing the Java classes loaded by the plugin as well as any exceptions that may occur. If no exceptions are displayed, clear the window (by clicking Clear) every 3rd or 4th window-full of displayed information.

4. If an exception appears in the Java Console window, copy and paste it into a file and send it to Oracle Support Services along with a description of your problem.

Tracing the Paging Server

The Enterprise Manager Paging Server can be debugged and traced separately from the Management Server. Tracing for the paging server is disabled by default. If tracing is enabled, the server writes trace statements for all telephone line handling and any successes or failures to a log file by default. Since information is logged whenever a page is sent, the log file grows proportionally to the number of pages sent. To delete a log file, you must shut down the paging server and delete the file.

The installation of the Oracle Enterprise Manager Paging Server provides a template configuration file, paging.cfg.template, located in the ORACLE_HOME\sysman\config directory.

1. Copy the paging.cfg.template file to the paging.cfg file, which is also located in the ORACLE_HOME\sysman\config directory.

   Oracle recommends copying this file (not renaming it) to retain information. If you do not copy this file, all comments concerning enabling tracing of paging will be removed. In addition, when updates to Enterprise Manager software are made, any configuration will be lost and not retrievable.

2. Based on the instructions in the paging.cfg.template file, modify the paging.cfg file according to your tracing needs and save it.

To enable tracing of the Enterprise Manager Paging Server, add the following properties and appropriate values to the paging.cfg file:

Table B-4 paging.cfg variables

Properties	Values
TRACING.ENABLED	Set value for debugging purposes; paging service will then track what paging is occurring by writing trace statements for all telephone line handling and any successes or failures. The value can be either true or false. If the value is set to true, you must specify a value for TRACEFILENAME and a value for TRACING.LEVEL. If the value is set to false, you need not specify values for TRACEFILENAME and TRACING.LEVEL.
TRACING.LEVEL	Set value to specify the detail of trace information to collect if tracing is enabled. 5 - user: collects critical messages and error messages. 3 - admin: collects critical, error, and warning messages. 2 - dev: collects all messages from admin trace level as well as informational and debug messages.
TRACEFILENAME	Set value for where to write tracing output if tracing is enabled. Oracle recommends setting the value to PAGING_LOG.TRC. By default, this file is located in the Paging Server's ORACLE_HOME\SYSMAN\LOG directory. If you specify a different directory, you must specify <Drive_Letter>:\\<directory_path>\\paging_log.trc. For example, if you want the tracing file stored in C:\temp\, set the value to C:\\temp\\paging_log.trc.

Tracing the SQL Engine

The SQL engine accepts, executes, and transmits the results of the SQL statements issued by the Enterprise Manager software.

Client applications include the Enterprise Manager Configuration Assistant and the database management portion of the Console. Depending on how the client application was started, the SQL Engine can be running on either the client or the Management Server:

• A client application connecting to the Management Server will use the SQL Engine of the Management Server.
• A client application connecting directly to a database will use its own SQL engine.

Since the engine can be traced on both the client and the Management Server, these parameters can be specified in both the omsconfig.properties and the ClientConfig.properties files.

The possible VDB (SQL Engine) parameters are mutually exclusive. You should use the highest requested tracing.

Table B-5 SQL Engine Variables

Properties	Values
VDB_DEBUG	When enabled, the SQL Engine will display trace stack traces and messages that are the first level of information. Boolean value. Possible values: true and false. Defaults to false.
VDB_VERBOSE_DEBUG	In this case, the SQL engine will display the methods as they are being entered and exited as well as any DEVELOPER DEBUG information. Boolean value. Possible values: true and false. Defaults to false.
VDB_SESSION_DEBUG	This is validated when displaying the contents of the database session pool. It is also used to trace session creation and destruction, as well as session pool activity. Boolean value. Possible values: true and false. Defaults to false.
VDB_VERBOSE_SESSION_DEBUG	This parameter gives more detail on session activity including stack traces when sessions are opened, closed, released to, or retrieved from the session pool. Like VDB_VERBOSE_DEBUG, it is a verbose version of the session tracing. Boolean value. Possible values: true and false. Defaults to false.

Tracing the Management Pack Applications

Refer to Database Tuning with the Oracle Tuning Pack for information on tracing.