Skip Headers

Oracle® Application Server Forms Services Deployment Guide 10g Release 2 (10.1.2) B14032-02 |
| Library | Product | Contents | Index

Previous | Next |

# 8 Tracing and Diagnostics

This chapter contains the following sections:

- Section 8.1, "About Forms Trace"

- Section 8.2, "Configuring Forms Trace"

- Section 8.3, "Starting Forms Trace"

- Section 8.4, "Viewing Forms Trace Output"

- Section 8.5, "List of Traceable Events"

- Section 8.6, "Monitoring Forms Services Trace Metrics"

- Section 8.7, "Servlet Logging Tools"

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

### 8.2.1 Specifying URL Parameter Options

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

    Tracegroup =
    Log = <filename>

Table 8-1, "Forms Trace Command Line Parameters" describes the parameter values:

Table 8-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/forms/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.

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

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

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 User Sessions screen in the Enterprise Manager Application Server Control Console.

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.4.1 Running the Translate Utility

The Translate utility converts trace data to XML or HTML formats. You'll need to specify an additional parameter "OutputClass" which has two legal values: "WriteOut" and "WriteOutHTML". If you use "WriteOut", the output file will be in XML format. If you use "WriteOutHTML", the output file will in HTML format.These two values ("WriteOut" and "WriteOutHTML") are case-sensitive.

To convert trace data to XML format:

- At the command line, enter:

  `java oracle.forms.diagnostics.Xlate datafile=a.trc outputfile=myfile.xml outputclass=WriteOut`

to create `myfile.xml`.

To convert trace data to HTML format:

- At the command line, enter:

  `java oracle.forms.diagnostics.Xlate datafile=a.trc outputfile=myfile.html outputclass=WriteOutHTML`

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

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

### 8.5.1 List of Event Details

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

- Table 8-3, "User Action Event Details"

- Table 8-4, "Forms Services Event Details"

- Table 8-5, "Detailed Events"

- Table 8-6, "Three-Tier Event Details"

- Table 8-7, "Miscellaneous Event Details"

#### 8.5.1.1 User Action Events

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

#### 8.5.1.2 Forms Services Events

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

#### 8.5.1.3 Detailed Events

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

#### 8.5.1.4 Three-Tier Events

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

#### 8.5.1.5 Miscellaneous Events

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

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

### 8.7.1 Enabling Logging

You enable logging by:

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

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

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 Section 8.7.3, "Example Output for Each Level of Servlet Logging".

Table 8-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 computer 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.

#### 8.7.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/forms/frmservlet?serverURL=/forms/lservlet/perf`

#### 8.7.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=/forms/frmservlet/session`

#### 8.7.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/forms/frmservlet/debug?serverURL=/forms/lservlet/debug`

### 8.7.2 Location of Log Files

The servlet log file is application.log. It is written to the application-deployments/formsapp 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/formsapp/OC4J_BI_Forms_default_island_1/application.log`

In Forms Developer, it is:

`ORACLE_HOME/j2ee/DevSuite/application-deployments/forms/application.log`

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

#### 8.7.3.1 (none)

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

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

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

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

#### 8.7.3.5 /debug

Here is an example run by going to a URL like http://test-machine:8888/forms/frmservlet/debug&config=myapp&serverURL=/forms/lservlet/debug):

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