7
Tracing and Diagnostics

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

The following tools are available to collect trace information for Oracle9i 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 Oracle9i 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 Oracle9i Forms sessions, monitor Oracle9i Forms-related network traffic, and debug site configuration problems.

• Oracle Trace: A tool to gather and analyze the performance of the Oracle Database, Oracle9iAS Forms Services, and other products which implement the Oracle Trace API for tracing.

This chapter describes the tracing tools and contains the following sections:

• Forms Trace

• Servlet Logging Tools

• Oracle Trace

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

Configuring Forms Trace

You define the events that you want to trace in the ftrace.cfg file or in the URL when you start the trace. An event is something that happens inside Oracle9i Forms as a direct or indirect result of a user action. See "List of Traceable Events" for a list of events and their corresponding event numbers.

ftrace.cfg

The ftrace.cfg file is installed in the %forms_home%/forms90/server directory by default, and the FORMS90_TRACE_PATH environment variable is set in the default.env file. (The FORMS90_TRACE_PATH environment variable specifies the location of the ftrace.cfg file and the location of trace output files.)

In a text editor, edit the ftrace.cfg configuration file to specify named event sets. An event set specifies a set of events that you can trace simply by specifying the event set name rather than each event number individually when you start the trace.

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

// 
// example ftrace.cfg file 
// This file is used to specify event groups for use with Forms Trace 
// 
// The file format is 
// name1: event1, event2, ... , event_n 
// name2: event1-event_m 
// 
all: 0-199 
errors: 0-3 
custom1: 32-46, 65, 66, 96, 194 

Note the following:

• There must be a blank line between keyword entries.

• Keywords can be 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.

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"

URL Parameter Options

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

Record = forms | otrace

Tracegroup =

Log = <filename>

Table 7-1 Forms Trace Command Line Parameters

Parameter	Values	Description
Record	forms	Enables Forms Trace.
	otrace	Enables Oracle Trace integration
Tracegroup		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		Specifies where trace information is saved. If a directory is not specified, the file is saved in the directory specified by the FORMS90_TRACE_PATH environment variable. (If this variable is not set, the output 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.

Starting the Trace

You start a trace by specifying trace entries in the URL or formsweb.cfg file. Entries should include the grouping of events to collect and the trace file name. Trace collection starts when the form executes.

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 Oracle9i Forms will implement a method for starting a trace via a built-in. The most recent information regarding Oracle9i Forms, including updated documentation, whitepapers, and viewlet demonstrations, is available on OTN at http://otn.oracle.com.

Viewing Forms Trace Output

Trace data is stored in a binary file with a *.trc extension. To view trace data, you must either:

• Use the Upload/Translate utility to convert the data in the *.trc file to XML format, and then view the data using an XML viewer.

• Use the Upload/Translate utility to upload the data in the *.trc file to database tables. (See "Creating Database Tables for the Trace Data" for information about scripts that will create the tables for you.)

Running the Upload/Translate Utility

The Upload/Translate utility performs two functions:

• Converts trace data to XML format.

• Uploads trace data to database tables.

To convert trace data to XML format, on the command line, type

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

to create myfile.xml.

To upload trace data to database tables, on the command line, type

java oracle.forms.diagnostics.Xlate datafile=a.trc userid=[password]=pw url=[server]:1521:orcl9i

to upload the trace data to the tables.

The following are valid command line options for the utility:

Table 7-2 Translate Utility Command Line Options

Parameter	Description
DataFile	Specifies the name of the binary trace data collection file.
XMLFile	Specifies the name of the XML output file, if required.
Url	Specifies the database connection of the form -- hostname:port:oracle_sid.
UserName	Specifies the database username.
Password	Specifies the database password.
CollectionId	Specifies a unique identifier for the trace. If one is not provided, the default of "0" is used.
Regressflag	Specifies whether the output file is going to be used for testing or not. If set to TRUE, the timestamp information is suppressed so that collected details can be compared across runs.

Creating Database Tables for the Trace Data

Scripts are provided to create tables for trace data.

Run the frmtrc.sql script on the binary trace file to create the database tables, indexes, and views. The frmtrc.sql script calls the frmtrc.tab script (to create tables), the frmtrc.con script (to create constraints), and the frmtrc.vw script (to create views).

The scripts create the following database schema for your trace data:

Table 7-3 Database Schema for Forms Trace Data

Table	Column	Attribute Description
Collections	Collection_Id	Unique ID to identify the collection
	Collection_Name	Name of the trace collection file
	Upload_Date	Date on which the data is uploaded
	Trace_Date	Date on which the data is Collected
	User_IP_Address	IP address from which the connection was made
	PID	Process id for the runform process.
User_Actions	Action_Id	Sequence no. to identify the actions within a collection
	Module_Module_Id	Module Id used as a foreign key to Module.
	Collection_Collection_Id	The collection to which the Action Corresponds. Used as a foreign key to correlate the data
	Action_Context	Context in which the Action took place
	Action_Name	The UserAction
	TimeStamp	Time of Occurrence of the Action
User_Action_Details	Usr_Action_Id	The action to which the attributes correspond to. Used as a foreign key to correlate the data.
	Collection_Collection_Id	The collection to which the Action Corresponds. Used as a foreign key to correlate the data
	Attribute_Name	Action Detail Attribute Name
	Attribute_Value	Action Detail Attribute Value
Events	Event_ID	Event Identifier, to identify the sequence of collection events
	Collection_Collection_Id	The collection to which the Event corresponds to
	Usr_Action_Id	Foreign key to User_Actions
	Event_Event_Id	To identify the associated event. This is useful for duration events.
	Event_Context	Context in which the event took place
	Event_Name	Name of the event
	Event_Number	The number assigned to a particular event, for example, 0-3 are errors.
	Timestamp	Timestamp indicating when the event occurred.
	Duration	How long the event took to complete. Only valid for duration events.
Event_Details	Detail_Id	The Detail ID
	Collection_Collection_ID	The collection to which the Event corresponds to
	Event_Event_Id	The EventID to which the Detail Corresponds to
	Attribute Name	Name of the Attribute
	AttributeValue	Value of the Attribute
Modules	Module_Id	The internal id of the module. Primary key.
	Collection_Collection_Id	Foreign key to Collection.
	Module_Name	Name of the module, for example, my.fmx.
	Physical_Path	Physical path to the form, for example, d:\temp\my.fmx.
	Attached_Libraries	Names of libraries attached to the form.
	Attached_Menus	Menu attached to the form.

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 Oracle9i 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-4 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
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
48	Reserved for future use
49-63	Reserved
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
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
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
160-191	Reserved
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
1024 an higher	Reserved for internal use

* 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.

List of Event Details

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

• Errors

• User Action Events

• Forms Services Events

• Detailed Events

• Three-Tier Events

• Miscellaneous

Errors

Lists the error type and the details describing the error.

User Action Events

Table 7-5 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

Forms Services Events

Table 7-6 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

Detailed Events

Table 7-7 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

Three-Tier Events

Table 7-8 Three-Tier Event Details

Event Name	Details	Number
Client Connect	Timestamp	128
Client Handshake	Timestamp	129
Heartbeat	Timestamp	130
HTTP Reconnect		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

Miscellaneous

Table 7-9 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

Servlet Logging Tools

The servlet logging tools available with Oracle9iAS Forms Services provides the following:

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

• Monitoring of Oracle9i 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:

• Turning on Logging

• Location of Log Files

• Example Output for Each Level of Servlet Logging

Turning on Logging

Turn on logging by:

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

• Appending one of the strings in Table 7-10, "Supported logging capabilities" to the serverURL client parameter in the formsweb.cfg file

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-10 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.

Specifying Logging in the URL

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

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

Specifying Logging in the formsweb.cfg File

As an example, to start session-level logging for all users, you would change the serverURL entry in the default section of the formsweb.cfg file to the following:

serverURL=/forms90/l90servlet/session

Specifying Full Diagnostics in the URL Used to Invoke the Forms Servlet

As an example, to start full diagnostics, you would start the Oracle9i 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

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 Oracle9iAS, the full path is:

<ORACLE_HOME>/j2ee/ProductGroup2/application-deployments/forms90app/1_default_island/application.log 

In Oracle9iDS, it is:

<ORACLE_HOME>/j2ee/iDS/application-deployments/forms90app/application.log 

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

(none)

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

/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

/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

/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

/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. 
***********************************************

Oracle Trace

Oracle Trace is part of Oracle Enterprise Manager (EM). Oracle Trace is the Oracle tool to gather and analyze the performance of the Oracle9i Database, Oracle9iAS Forms Services, and other products which implement the Oracle Trace API for tracing. To take full advantage of Oracle Trace, you must install Diagnostics Pack, one of the optional packs provided in the Oracle Enterprise Manager product suite. The Diagnostics Pack contains a set of tools to administer the Oracle Trace collections remotely through a GUI interface and to efficiently view the Oracle Trace output.

See the Oracle Enterprise Manager documentation for details.