Skip Headers

Oracle Application Server Forms Services Deployment Guide 10g (9.0.4) Part Number B10470-01 |
Home | Contents | Index

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

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

Text description of the illustration edit_tra.gif

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 implemenet 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/forms90/1_default_
    island/application.log

In Forms Developer, it is:

    <ORACLE_HOME>/j2ee/OracleDS/application-deployments/forms90/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.
    ***********************************************

| Copyright © 2003 Oracle Corporation. All Rights Reserved. |
Contents | Index