trace

This command displays and sets tracing options within Process Engine and is mainly intended for FileNet engineering staff use. You can trace a variety of server activity, such as remote procedure calls or log manager processes. You can route this trace information to the screen (stdout device), to a Process Engine trace file, or to memory—if you route the trace information to memory, you can subsequently save the trace information to a file of your choice.

The command displays each trace destination and option. Those that are currently enabled are prefaced with "**".

NOTE  Restarting the Process Engine server automatically turns off all trace options.

Syntax

The syntax varies depending on the mode you choose. The interactive mode requires that you indicate settings for all of the trace options. The command line mode allows you to enable selected options. (Note that as with all vwtool commands, the information for the interactive mode can be entered at the command line as well, as long as you provide all necessary information.)

Mode Syntax

Interactive

trace <change_tracing_options> [<trace_destinations>] [<trace_options>]

Command line

trace [set_or_reset] [<trace_destination>] [<trace_options>]

TIP You can set and reset options in the same command line, for example:
trace set file memory java reset transfer

Parameters

change_tracing_options

Enter "y" to change any of the displayed settings, or "n" to leave them as is.

The remaining prompts only appear if you answer 'y' to the change_tracing_options prompt.

set_or_reset Enter "set" or plus (+) to enable a trace destination or option. Enter "reset" or minus (-) to disable a trace destination or option.

trace_destination

Indicates where you want the trace information to be stored.

Interactive mode: For each destination, enter "y" for yes or "n" for no. The destinations appear in the order indicated below.

Command line mode: Enter the destination, in any order. You can abbreviate the destination to three characters, as noted below.

file (fil)

Save the trace to a file. If you enable this option, vwtool outputs the name of the log file it creates:

Windows: \fnsw_loc\tmp\vwtrace
UNIX: /fnsw/tmp/vwtrace
memory (mem) Save the trace to memory. Use the writetrace command to subsequently save this trace information to a file.

To turn tracing off:
Interactive mode: Enter the trace command with no parameters, and enter "n" at the <trace_destination> prompts.
Command line mode: Use the reset option followed by all enabled trace destinations or trace options.

NOTE  Disabling all trace destinations effectively turns off tracing. However, there is some performance overhead resulting from leaving trace options enabled.

trace_options

The trace activity that you can enable or disable.

Interactive mode: For each parameter, enter "y" for yes or "n" for no. The options appear in the order indicated below.

Command line mode: Enter the option name, in any order. You can abbreviate most options to three or more unique characters. Spaces are removed for syntax purposes (for example, Object Service becomes "objectservice"). The shortest usable abbreviation or an acceptable alternative for each option is shown in parentheses following its name.

Application (app)

Trace application functions.

Broker (bro)

Trace VWOrbBroker process communications. This option can be changed at runtime.

Broker trace level values
 

Broker trace level

Enter the level of information to be traced. You must set these values using the interactive option. Turning on broker tracing using the command line option sets the trace level to 128.

The broker trace level is a mask. You can enter any value between 1 and 255 to set the options that add up to the value. For example, setting the trace level to 51 turns on Information, Messages, Method Entry, and Timings (1+2+16+32).

1 Information
2 Messages
4 Severe
8 ORB
16 Method entry
32 Timings
128 Finest

Database access (databasea)
or
dbaccess (dba)

Trace database access.

This option outputs the SQL statements used by Process Engine, along with the values of the substitution variables. (This information can be useful for FileNet field personnel.)

Setting this option automatically sets the database time option.

Database time (databaset)
or
dbtime (dbt)

Trace database timings.

This prompt only appears if you answer 'n' to the database access prompt.

Environment cache (env) Trace Process Engine's interactions with its environment record cache where it keeps track of Process Engine user and group membership information.

External RPCs (ext)

Trace external Remote Procedure Calls (RPCs).

The extRPC and intRPC options reflect the number of RPCs going across the network.

Farming (far) Trace activities related to a farmed Process Engine system.
Global characters Low level tracing of character strings to help when debugging globalization issues. (This information is primarily useful for FileNet field personnel.)

Internal RPCs (int)

Trace internal Remote Procedure Calls (RPCs).

The extRPC and intRPC options reflect the number of RPCs going across the network.

ISI (isi)
or
InstructionSheetInterpreter (ins)

Trace Instruction Sheet Interpreter (ISI) process.

Log Manager (log)

Trace log manager process.

Network Connections (net)

Trace network connections.

Notification (not)
Email Notification (ema)

Trace e-mail notifications.

Object Service RPCs (obj)

Trace Object Service usage.

ORB Communication (orbc)

Trace ORB communication for all VW processes except vworbbroker. The ORB trace level defaults to 10.

If set from the command line, the trace level is set to the default.

ORB trace level

Enter the level of information to be traced. The trace level is cumulative -- level 40 includes all trace messages. The default is zero.

0 critical errors only
1 informational messages only
2 configuration information and warnings
5 notifications when server threads are created and communication endpoints are shut down
10 execution and exception traces
25 each send or receive of a giop message
30 dump up to 128 bytes of each giop message
40 dump complete contents of each giop message
ORB exceptions
(orbe)

Trace all ORB system exceptions. In interactive mode, you must turn ORB Communication tracing on to be prompted for this option. Enter "y" to log all system exceptions. The default is "n".

If set from the command line, ORB Communication tracing is enabled and the ORB trace level defaults to 5.

ORB invocations
(orbi)

Traces all ORB local and remote Invocations. In interactive mode, you must turn ORB Communication tracing on to be prompted for this option. Enter "y" to log all local and remote invocations. The default is "n".

If set from the command line, ORB Communication tracing is enabled and the ORB trace level defaults to 5.

ORB thread ID
(orbt)

Includes the thread ID of the thread outputting the message. This adds significant overhead to the logging function. In interactive mode, you must turn ORB Communication tracing on to be prompted for this option. Enter "y" to prefix all trace messages with the id of the thread outputting the message. The default is "n".

If set from the command line, ORB Communication tracing is enabled and the ORB trace level defaults to 5.

Rules (rul) Trace Process Engine's interactions with the Rules Engine and rules processing.

Security calls (sec)

Trace security calls.

StartStop (sta)

Trace the execution of the startstop chains.

Stored Procedure Calls (sto) Trace the execution of database instruction stored procedure calls.
Strings in HEX (str) Causes some of the directory service information traced by the "security call" tracing to be written in hexadecimal format. This option has no effect if the "security calls" tracing is not also enabled.

Workflow Termination (wor)

Trace calls made to the workflow termination process (vwdone).

Transfer (tra)

Trace all transfer processes.

VWKs RPCs (vwk) Trace Java™ calls via the VWKs process.
Web Services (web) Trace Process Engine interactions with applications using the Web Services protocol.