8 Tracing and Diagnostics

8.1 About 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. From the Enterprise Manager Application Server Control Console, you can use trace output to diagnose performance and other problems with Oracle Forms applications.

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.

8.2 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 10g Application Server Control Console Forms page to define the events that you want to trace. This page manages all changes in the ftrace.cfg file for you.

Keep these items in mind when working with Forms Trace:

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

• In order to trace Forms Processes on Windows, the Process Manager Service needs to have the check box "Allow service to interact with the desktop" selected. When 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.

• Backup the formsweb.cfg and default.env files before editing them with Oracle Enterprise Manager 10g Application Server Control Console.

• 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 10g Application Server Control Console 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.

• 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

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

To configure Forms Trace: 

1. Start the Enterprise Manager Application Server Control Console.

2. From the Enterprise Manager Application Server Control Console 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.

Figure 8-1 is a sample ftrace.cfg configuration file where three event sets have been specified.

Figure 8-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"

Tracegroup =   
Log = <filename> 

8.3 Starting Forms Trace

You start a trace by specifying trace entries in the URL or from Enterprise Manager Application Server Control Console. 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/forms/frmservlet?form=cxl&record=forms&tracegroup=0-199
http://cx-pc/forms/frmservlet?form=cxl&record=forms&tracegroup=mysql
http://cx-pc/forms/frmservlet?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://www.oracle.com/technology/products/forms/.

8.4 Viewing Forms Trace Output

Only users with administrator privilige can view trace log files. The user needs to log in as a user that is in the administrators' group. By default, user 'admin', which is present as a default user in the 'adminstrators' group, can be used. Users can then be created and added later into this group to for logging in and viewing trace log files.Once the user has logged in, he will not have to log in again in the same browser session to view trace log files for different formsweb sessions.

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

To view trace data, use Enterprise Manager: 

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

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

8.5 List of Traceable Events

Table 8-2, "List of Traceable Events" 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).

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

8.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 Console.

2. From the Enterprise Manager Application Server Control Console 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.

8.7 Servlet Logging Tools

Servlet logging tools enable site administrators to keep a record of all Oracle Forms sessions, monitor Oracle Forms-related network traffic, and debug site configuration problems.The features of servlet logging tools available with Oracle Application Server Forms Services include:

• Recording 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)

• Generating debugging information for site configuration issues (debug-level logging)

These sections on the servlet logging tools contain the following:

• Section 8.7.1, "Enabling Logging"

• Section 8.7.2, "Location of Log Files"

• Section 8.7.3, "Example Output for Each Level of Servlet Logging"

FormsServlet init(): 
configFileName:     d:\Oracle/forms/server/formsweb.cfg
testMode:           false

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

Forms session <10> ended

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

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

=============== FormsServlet =============== 
GET request received, cmd=debug,
qstring=config=myapp&serverURL=/forms/lservlet/debug 
No current servlet session 
File baseie.htm not found, looking in d:\Oracle/forms/server 
The SSO_USERID is: null 
=============== FormsServlet =============== 
GET request received, cmd=startsession, qstring=config=myapp&serverURL= 
/forms/lservlet/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:\Oracle/forms/server 
envFile = d:\Oracle\forms\server\default.env 
serverURL: /forms/lservlet/debug 
rewrittenURL: /forms/lservlet/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 frmweb server webfile=HTTP-0,0,1 
Getting stdin, stdout and stderr of child process 
Writing working directory to stdin: d:\Oracle\forms 
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. 
***********************************************