7 Tracing and Diagnostics

When you develop and deploy Oracle Forms applications, it is helpful to have information that allows you to optimize your applications. Tracing and diagnostic tools that are available with Oracle Forms allow you to analyze the performance and resource consumption of your Oracle Forms applications at runtime. Through Enterprise Manager Application Server Control, you can use trace output to diagnose performance and other problems with Oracle Forms applications.

The following tools are available to collect trace information for Oracle Forms:

• Forms Trace: Replaces the functionality that was provided with Forms Runtime Diagnostics (FRD) and Performance Event Collection Services (PECS), which were available in earlier releases of Oracle Forms. Forms Trace allows you to trace the execution path through a form, for example, the steps the user took while using the form.

• Servlet Logging Tools: Enables site administrators to keep a record of all Oracle Forms sessions, monitor Oracle Forms-related network traffic, and debug site configuration problems.

7.1 Forms Trace

Forms Trace allows you to record information about a precisely defined part of forms functionality or a class of user actions. This is accomplished by defining events for which you want to collect trace information. For example, you can record information about trigger execution, mouse-clicks, or both.

This section on Forms Trace contains the following information:

• Configuring Forms Trace

• Starting the Trace

• Viewing Forms Trace Output

• List of Traceable Events

• List of Event Details

7.1.1 Configuring Forms Trace

An event is something that happens inside Oracle Forms as a direct or indirect result of a user action. An event set specifies a group of events that you can trace simply by specifying the event set name rather than each event number individually when you start the trace.

Use the Forms Trace Configuration selection in the Configuration tab of Oracle Enterprise Manager Application Server Control Forms page to define the events that you want to trace. This page manages all changes in the ftrace.cfg file for you.

See "List of Traceable Events" for a list of events and their corresponding event numbers.

Note: As with most Web applications, it is easy to lose unsaved changes by switching pages. Be sure to save any changes you make through Oracle Enterprise Manager Application Server Control to Forms configuration, trace, or environment files before proceeding to other pages. The length of time it takes for changes to be saved is affected by the number of lines you have changed. For example, an additional fifty lines of comments will take longer to save than just the deletion of a single entry.

Note: If you manually edit any of the configuration or environment files, you'll need to restart Enterprise Manager as well as restart all Distributed Configuration Management (DCM) processes so that Enterprise Manager can read all changes. If you do not restart Enterprise Manager as well as DCM processes, any changes that you make through Enterprise Manager will overwrite any manual changes you've made to these files. These DCM processes include: emctl stop agent emctl stop em dcmctl stop opmnctl stopall opmnctl startall dcmctl start emctl start agent emctl start em

Note: You should backup the formsweb.cfg and default.env files before editing them with Oracle Enterprise Manager Application Server Control.

Note: If you first switch off trace, and then switch it on again with new settings, then trace is enabled with the new trace group.

Note: In order to trace Forms Processes on Windows, the ProcessManager Service needs to have the check box "Allow service to interact with the desktop" checked. If this is not set, attempting to switch on Trace will result in the error: oracle.sysman.emSDK.emd.comm.RemoteOperationException. Check the User Name and Password.

To configure Forms Trace:  

1. Start the Enterprise Manager Application Server Control.

2. From the Enterprise Manager Application Server Control main page, select the link to the Forms Services instance that you want to configure.

3. From the Overview page for the Forms Services instance, select the Configuration link.

To create a new parameter in the ftrace.cfg file:  

• Enter a Name and Value for this new parameter and click Add New Parameter at the bottom of the page.

To delete a parameter in the ftrace.cfg file:  

• Click the radio button next to the parameter to be deleted, then click Delete. Confirm the deletion on the next page.

To edit an existing parameter in the ftrace.cfg file:  

• Select the radio button next to it, and modify the values in the text areas. Click Apply to save your changes.

To save your changes:  

• Click the radio button next to a parameter, then click Apply.

The following is a sample ftrace.cfg configuration file where three event sets have been specified.

Figure 7-1 Configuring Trace Events in Enterprise Manager

Note the following if you are manually editing ftrace.cfg:

• There must be a blank line between keyword entries.

• An Event group can have any name as long as they do not contain spaces. For example, a_b_c is an acceptable keyword.

• There must be a comma between each event number.

• You can use a range of numbers

When you start the trace, you can specify tracegroup = "custom1" on the command line, which is equivalent to specifying tracegroup = "32-46, 65, 66, 96, 194"

7.1.1.1 Specifying URL Parameter Options

The following command line parameters are used to configure Forms Trace:

Tracegroup =   
Log = <filename> 

Table 7-1 Forms Trace Command Line Parameters

Parameter	Values	Description
Record	forms	Enables Forms Trace.
Tracegroup	Name, event number, or event range	Indicates which events should be recorded and logged. If Tracegroup is not specified, only error messages are collected. Tracegroup is ignored if Forms Trace is not switched on at the command line. You can create a named set of events using the Tracegroup keyword, for example Tracegroup=<keyword>, where <keyword> is specified in ftrace.cfg (for example, Tracegroup=MyEvents). This lets you log the events in the named set SQLInfo. You can log all events in a specified range using the Tracegroup keyword, for example Tracegroup = 0-3 This lets you log all events in the range defined by 0 <= event <=3. You can log individual events using the Tracegroup keyword, for example Tracegroup = 34,67 You can combine event sets using the Tracegroup keyword, for example Tracegroup = 0-3,34,67,SQLInfo
Log	Directory	Specifies where trace information is saved. Trace files must be saved to <ORACLE_HOME>/forms90/trace for Enterprise Manager to find and process them correctly. If a directory is not specified, the file is written to the current working directory. If a log file is not specified, the process ID (PID) of the user process is used as the name of the trace file, for example, forms_<pid>.trc.

7.1.2 Starting the Trace

You start a trace by specifying trace entries in the URL or from Enterprise Manager Application Server Control. Entries should include the grouping of events to collect and the trace file name. Trace collection starts when the form executes.

Note: You'll need to provide the credentials in the dialog box that displays (the user name and password that is required is for the operating system account that was used when Forms Services was installed).

The following are sample URLs to start a trace:

http://cx-pc/forms90/f90servlet?form=cxl&record=forms&tracegroup=0-199 
http://cx-pc/forms90/f90servlet?form=cxl&record=forms&tracegroup=mysql 
http://cx-pc/forms90/f90servlet?form=cxl&record=forms&tracegroup=0-199;log=run1.log

A later release of Oracle Forms will implement a method for starting a trace via a built-in. The most recent information regarding Oracle Forms, including updated documentation, whitepapers, and viewlet demonstrations, is available on OTN at http://otn.oracle.com/.

7.1.3 Viewing Forms Trace Output

Trace data is stored in a binary file with a *.trc extension. If you're not using Enterprise Manager Application Server Control, you'll need to use the Translate utility.

Note: The parameter allow_debug must be set to true in the default section of the Forms Web Configuration file before trace logs can be viewed from the Forms Enterprise Manager User Sessions screen in the Enterprise Manager Application Server Control.

To view trace data, use Enterprise Manager:  

1. In Enterprise Manager Application Server Control, select the User Sessions link.

2. Click View Trace Log to see the contents of the trace log.

7.1.3.1 Running the Translate Utility

The Translate utility converts trace data to XML format.

To convert trace data to XML format:  

• At the command line, enter:

  java oracle.forms.diagnostics.Xlate datafile=a.trc xmlfile=myfile.xml
  

to create myfile.xml.

7.1.4 List of Traceable Events

The following table lists the events that can be defined for tracing. In future releases of Forms, more events will be added to this list.

Event types are as follows:

• Point event: An event that happens in Oracle Forms as the result of a user action or internal signal for which there is no discernible duration, for example, displaying an error message on the status line. Each instance of this event type creates one entry in the log file.

• Duration event: An event with a start and end, for example, a trigger. Each instance of this event type creates a pair of entries in the log file (a start and end event).

• Built-in event: An event associated with a built-in. Each instance of this event type creates a greater quantity of information about the event (for example, argument values).

Table 7-2 List of Traceable Events

Event Number	Definition	Type
0	Abnormal Error	point
1	Error during open form	point
2	Forms Died Error	point
3	Error messages on the status bar	point
4-31	Reserved	NA
32	Startup	point
33	Menu	point
34	Key	point
35	Click	point
36	Double-click	point
37	Value	point
38	Scroll	point
39	LOV Selection	point
40	not used	not used
41	Window Close	point
42	Window Activate	point
43	Window Deactivate	point
44	Window Resize	point
45	Tab Page	point
46	Timer	point
47	Reserved for future use	NA
48	Reserved for future use	NA
49-63	Reserved	NA
64	Form (Start & End)	duration
65	Procedure (Start & End)	duration
66	Trigger (Start & End)	duration
67	LOV (Start & End)	duration
68	Opening a Editor	point
69	Canvas	point
70	Alert	duration
71	GetFile	point
72-95	Reserved	NA
96	Builtin (Start & End)	builtin
97	User Exit (Start & End)	duration
98	SQL (Start & End)	duration
99	MenuCreate (Start & End)	duration
100	PLSQL (Start & End)	duration
101	Execute Query	duration
102-127	Reserved	NA
128	Client Connect	point
129	Client Handshake	point
130	Heartbeat	point
131	HTTP Reconnect	point
132	Socket (Start & End)	duration
133	HTTP (Start & End)	duration
134	SSL (Start & End)	duration
135	DB Processing (Start & End)	duration
136	DB Logon (Start & End)	duration
137	DB Logoff (Start & End)	duration
138-159	Reserved	NA
160-191	Reserved	NA
192*	Environment Dump	N/A
193*	State Delta	N/A
194*	Builtin Arguments	N/A
195*	UserExit Arguments	N/A
196*	Procedure Arguments	N/A
197*	Function Arguments	N/A
256 and higher	User defined	NA
1024 an higher	Reserved for internal use	NA

* These event numbers do not have a TYPE because they are not really events, but rather details for events. For example, the State Delta is something you can choose to see - it is triggered by a real action or event.

7.1.5 List of Event Details

The following tables list event details that can be defined for tracing:

• User Action Events

• Forms Services Events

• Detailed Events

• Three-Tier Events

• Miscellaneous

7.1.5.1 User Action Events

Table 7-3 User Action Event Details

Action	Details	Number
Menu Selection	Menu Name, Selection	33
Key	Key Pressed, Form, Block, Item	34
Click	Mouse/Key, Form, Block, Item	35
DoubleClick	Form, Block, Item	36
Value	Form, Block, Item	37
Scroll	Form, Up, Down, Page, Row	38
LOV Selection	LOV Name, Selection Item	39
Alert	AlertName, Selection	40
Tab	Form	45
Window Activate, Deactivate,Close, Resize	WindowName, FormName, Size	41,42,43,44

7.1.5.2 Forms Services Events

Table 7-4 Forms Services Event Details

Event Name	Details	Number
Form	Form ID, Name, Path, Attached Libraries, Attached Menus	64
Procedure	Procedure Name, FormID	65
Trigger	TriggerName, FormName, BlockName, ItemName, FormID	66
LOV	LOV name, FormId	67
Editor	FormId , Editor Name	68
Canvas	FormId , Canvas Name	69

7.1.5.3 Detailed Events

Table 7-5 Detailed Events

Event Name	Details	Number
Builtin	BuiltinName, FormId	96
User Exit	UserExitName, FormId	97
MenuCreate	MenuName, FormID	99
PLSQL	PLSQLSTmt, FormID	100
ExecQuery	Block Name	101

7.1.5.4 Three-Tier Events

Table 7-6 Three-Tier Event Details

Event Name	Details	Number
Client Connect	Timestamp	128
Client Handshake	Timestamp	129
Heartbeat	Timestamp	130
HTTP Reconnect	NA	131
Socket	FormId, Packets, Bytes	132
HTTP	FormId, Packets, Bytes	133
HTTPS	FormId, Packets, Bytes	134
DB Processing	FormId, Statement	135
DB Logon	FormId	136
DB Logoff	FormId	137

7.1.5.5 Miscellaneous

Table 7-7 Miscellaneous Event Details

Event Name	Details	Number
Environment Dump	Selected environment information	192
State Delta	Changes to internal state caused by last action/event	193
Builtin Args	Argument values to a builtin	194
Userexit args	Arguments passed to a userexit	195
Procedure Args	Arguments (in|out) passed to a procedure	196
Function Args	Arguments (in|out) passed to a procedure	197

7.1.6 Monitoring Forms Services Trace Metrics

Use this Enterprise Manager page to review Forms Services Trace metrics.

1. Start the Enterprise Manager Application Server Control.

2. From the Enterprise Manager Application Server Control main page, select the link to the User Sessions link

3. Click the icon in the View Trace Log column.

You can write your own classes to implement a write.output class that is XML-based.

7.2 Servlet Logging Tools

The servlet logging tools available with Oracle Application Server Forms Services provides the following:

• A record of all Oracle Forms sessions, including session start and end times, and the user's IP address and host name (session-level logging)

• Monitoring of Oracle Forms-related network traffic and performance (session-performance and request-performance-level logging)

• Information for debugging site configuration problems (debug-level logging)

This section on servlet logging tools contains the following information:

• Enabling Logging

• Location of Log Files

• Example Output for Each Level of Servlet Logging

7.2.1 Enabling Logging

You enable logging by:

• Appending one of the strings in Table 7-8, "Supported logging capabilities" to the serverURL parameter in the URL that starts the form.

• Appending one of the strings in Table 7-8, "Supported logging capabilities" to the serverURL client parameter in the Forms Configuration page of Enterprise Manager Application Server Control.

When you turn on logging, the Listener Servlet writes log messages to the servlet log file. Examples of output for the various levels of logging are in Example Output for Each Level of Servlet Logging.

Table 7-8 Supported logging capabilities

String appended to serverURL client parameter	Description of logging
(none)	No log messages are produced. However, during Forms Servlet initialization, a message is written to the log file stating the name and path of the configuration file being used.
/session	Log messages are written whenever a Forms session starts or ends. These give the host name and IP address of the client (the machine on which the user's web browser is running), the runtime process id, and a unique internal session id number.
/sessionperf	Performance summary statistics are included with the session end message.
/perf	A performance message is written for every request from the client.
/debug	Full debug messages. Other debug messages are written in addition to the messages mentioned above. This logging level is very verbose and is intended mainly for debugging and support purposes.

7.2.1.1 Specifying Logging in the URL

As an example, to start a performance-level trace, you would start the Oracle Forms application using a URL as follows:

http://yourserver/forms90/f90servlet?serverURL=/forms90/l90servlet/perf

7.2.1.2 Specifying Logging through Enterprise Manager

As an example, to start session-level logging for all users, you would change the serverURL entry in the default section in the Forms Web Configuration page to the following:

serverURL=/forms90/f90servlet/session

7.2.1.3 Specifying Full Diagnostics in the URL that Invokes the Forms Servlet

As an example, to start full diagnostics, you would start the Oracle Forms application using a URL as follows. Note that if you append /debug to the URL used to invoke the Forms Servlet that servlet will output debug messages to the log file too.

http://yourserver/forms90/f90servlet/debug?serverURL=/forms90/l90servlet/debug

7.2.2 Location of Log Files

The servlet log file is application.log. It is written to the application-deployments/forms90app directory of the OC4J instance to which Forms is deployed.

In Oracle Application Server Forms Services, the full path is:

<ORACLE_HOME>/j2ee/OC4J_BI_FORMS/application-deployments/forms90app/OC4J_BI_Forms_default_island_1/application.log

In Forms Developer, it is:

<ORACLE_HOME>/j2ee/DevSuite/application-deployments/forms/application.log

7.2.3 Example Output for Each Level of Servlet Logging

The following are examples of the type of output you will get when you use the following levels of logging:

• (none)

• /session

• /sessionperf

• /perf

• /debug

7.2.3.1 (none)

FormsServlet init(): 
configFileName:     d:\orant9i/forms90/server/formsweb.cfg 
testMode:         
  false

7.2.3.2 /session

Session start messages (example):

Forms session <10> started for test-pc.mycompany.com ( 138.56.98.72 ) 
Forms session <10> runtime process id = 373 

Session end message (example):

Forms session <10> ended

7.2.3.3 /sessionperf

Forms session <3> started for test-pc.mycompany.com ( 138.56.98.72 ) 
Forms session <3> runtime process id = 460 
Forms session <3> ended 
  Total duration of network exchanges: 1.041 
  Total number of network exchanges: 2 (1 "long" ones over 1.000 sec) 
  Average time for one network exchange (excluding long ones): 0.030 
  Total bytes: sent 1,110, received 316

7.2.3.4 /perf

Forms session <3> started for test-pc.mycompany.com ( 138.56.98.72 ) 
Forms session <3> runtime process id = 460 
Forms session <3>: request processed in 1.011 sec. Received 8 bytes,returned 8 bytes. 
Forms session <3>: request processed in 0.030 sec. Received 308 bytes, returned 1,102 bytes. 
Forms session <3> ended 
  Total duration of network exchanges: 1.041 
  Total number of network exchanges: 2 (1 "long" ones over 1.000 sec) 
  Average time for one network exchange (excluding long ones): 0.030 
  Total bytes: sent 1,110, received 316

7.2.3.5 /debug

Here is an example run by going to a URL like http://test-machine:8888/forms90/f90servlet/debug&config=ienative&serverURL=/forms90/l90servlet/debug):

=============== FormsServlet =============== 
GET request received, cmd=debug,
qstring=config=ienative&serverURL=/forms90/l90servlet/debug 
No current servlet session 
File baseie.htm not found, looking in d:\orant9i/forms90/server 
The SSO_USERID is: null 
=============== FormsServlet =============== 
GET request received, cmd=startsession, qstring=config=ienative&serverURL= 
/forms90/l90servlet/debug&ifcmd=startsession 
No current servlet session 
New servlet session started 
SSO_USERID in startSession: null 
SSO_AuthType in startSession: null 
User DN: null 
Subscriber DN: null 
EM mode in the config file: 0 
File default.env not found, looking in d:\orant9i/forms90/server 
envFile = d:\orant9i\forms90\server\default.env 
serverURL: /forms90/l90servlet/debug 
rewrittenURL: /forms90/l90servlet/debug;jsessionid=27f6412da05c 
426ab47db4ae77636113 
=============== ListenerServlet =============== 
GET request received, cmd=getinfo,
qstring=ifcmd=getinfo&ifhost=test-pc.mycompany.com&ifip=130.35.96.71 
Existing servlet session, id = 27f6412da05c426ab47db4ae77636113, not from cookie 
Creating new Runtime Process using default executable 
Starting Forms Server in EM mode 
startProcess: executing ifweb90 server webfile=HTTP-0,0,1 
Getting stdin, stdout and stderr of child process 
Writing working directory to stdin: d:\orant9i\forms90 
New server process created 
Forms session <4> started for test-pc.mycompany.com ( 138.56.98.72 ) 
*********************************************** 
Got POST request, length = 8 
HTTP request headers: 
      ACCEPT-LANGUAGE: en 
      PRAGMA: 1 
      CONTENT-TYPE: application/x-www-form-urlencoded 
      ACCEPT: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2 
      USER-AGENT: Mozilla/4.0 (compatible; MSIE 5.0; Win32) 
      HOST:test-machine:8888 
      CONTENT-LENGTH: 8 
      CONNECTION: Keep-Alive 
Existing servlet session, id = 27f6412da05c426ab47db4ae77636113, not from cookie 
Forms session <4> runtime process id = 474 
Port number is 2791 
RunformProcess.connect(): connected after 1 attempts 
Connected to ifweb process at port 2791 
Forms session <4>: request processed in 1.032 sec. Received 8 bytes,  
returned 8 bytes. 
***********************************************