Oracle Waveset 8.1.1 System Administrator's Guide

Tracing the Waveset Gateway Objects and Activities

This section describes how to trace objects and activities in Oracle Waveset Gateway, the information is organized as follows:


Note –

How to Configure Gateway Tracing

If you cannot access the Gateway, you can enable tracing to debug problems with Windows accounts on Waveset. You can enable or disable tracing from the Gateway Debug page (Gateway.jsp) or, if you want a wider range of options, you can enable tracing from the command line

ProcedureTo Enable Tracing from the Gateway Debug Page

Use the following instructions to enable and configure tracing from the Gateway Debug page (Gateway.jsp).

  1. Log in to the Waveset Administrator interface.

  2. Type the following URL in to your browser to open the Gateway Debug page:

    http://host :port/idm/debug/Gateway.jsp

  3. Choose a resource to trace from the Gateway Resource list.

  4. If necessary, modify existing settings.

    Click the following buttons to modify the settings:

    • Get Version. Returns the Gateway version and the operating system of the machine on which you are running the Gateway.

    • Get Trace File. Returns the contents of the trace file.

    • Get Trace Parameters. Returns the path of the trace file, the trace level, and the maximum size of the trace file.

    • Set Trace Parameters. See To Create a New Trace Configuration Object for information about these options.

    • Get Loaded Modules. Returns the load addresses of modules (DLLs) being used by the Gateway.

    The Get Loaded Modules list consists of load addresses, followed by module names and only includes loaded modules. The list does not include delay-loaded modules that have not been called.

    The Get Loaded Modules option only supports Active Directory and Domino.

ProcedureTo Enable Tracing from the Command Line

  1. Open a command window.

  2. Start the Gateway.

    • To start the gateway as a service, type the following command:

      #gateway -s

    • To start the gateway as a regular application rather than a service, type the following command:

      #gateway —d


    Note –
    • Do not use the -d and -s options at the same time on the same command line.

    • —p. Use this argument to specify a TCP/IP port number. (The default port is 9278.) For example,

      #gateway -d -p 9278


  3. Specify the necessary trace command arguments.

    The following table describes the Gateway tracing command line arguments.

    Argument 

    Description 

    -f

    Specify the path to the trace file 

    -l

    Specify the level of tracing: 

    • Level 0. Disables tracing. (Default)

    • Level 1. Traces the flow of control between components and generally defines a low-detail trace point that includes entry and exit from high-level functional methods.

    • Level 2. Generally defines a medium-detail trace point that includes entry and exit from every method, and information and data trace points for high-level functional methods. Level 2 adds the flow of control within each component, major decision points, and items of information.

    • Level 3. Generally defines a high-detail trace point that includes entry and exit from every method, information and data trace points for high-level functional methods, and significant subroutines. Level 3 adds lower-level decision points and items of information.

    • Level 4. Generally defines a hyper-detail trace point that includes everything traced in the other trace levels. Level 4 traces at a very low level and can provide a level of detail that is seldom needed but might be useful in characterizing complex behaviors of some components. NOTE: Not all components support level 4.

      Trivial methods, such as getters and setters, generally do not have entry or exit trace points because they add overhead.

    -m

    Specify the maximum trace file size in kilobytes 

    When the trace file reaches -m Kbytes, Waveset closes the current trace file, deletes any existing back-up files, renames the current trace file to the name specified by the -f argument with .bk appended, and opens a new trace file with the -f argument name.

    For example, if you specified -f beeble.trc on the command line, the following two files result after -m Kbytes are recorded:

    beeble.trc.bk

    beeble.trc

    Where beeble.trc contains the most recent traces.

    Usage: #gateway -l level -m size -f name -s

    For example:


    cd %WSHOME%\bin\winnt
    #gateway -p 11319 -l 2 -m 500 -f %CD%\gateway.trc -s

    The preceding invocation starts the Gateway with the following characteristics:

    • -p 11319 – Use port 11319

      You must configure this port for Gateway resources from the Waveset resource configuration. For example, for an Active Directory resource

    • -l 2 – Trace the gateway at output level 2.

    • -m 500 – Limit the size of the trace log file to 500 Kilobytes.

    • -f C:\gateway.trc – Write the trace output to a file called gateway.trc in the C:\ directory.

    • -s – Start the gateway service.


    Note –

    If specified, Waveset saves -p, -l, -m, and -f values in the registry, so the next time you run Gateway from the command line or as a service, the same values are used.

    If you started the gateway using the -d option, Waveset sends the Gateway trace output to the console and to a trace file.


ProcedureTo Disable Tracing from the Debug Page

  1. Log in to the Waveset Administrator interface.

  2. Type the following URL in to your browser to open the Gateway Debug page:

    http://host:port/idm/debug/Gateway.jsp

  3. Deselect the Show Trace option or delete the file name from the Get Trace File text box.

ProcedureTo Disable Tracing from the Command Line

  1. If necessary, open a command window.

  2. Stop the Gateway service.

    • If you started the Gateway service using the -s option, stop the service by typing the following command:

      #gateway -k

    • If you used the -d option to start the gateway as a regular application, stop the gateway by typing Control-C in the same command window you used to start the gateway.

  3. Start the gateway with trace level 0 using the -l option. (You do not have to specify the -m or -f option.) For example

    #gateway -d -l 0

How to Capture Encrypted Information

Waveset encrypts all messages between the gateway and the Waveset server.

You can configure Waveset to log encryption and decryption message details while tracing at level 4 in the gateway, but this capability is disabled by default. Tracing encryption information at level 4 can cause a large amount of overhead because Waveset logs each message multiple times, once on entry to and once on exit from the encryption routines. In addition, Waveset limits the size of logged informational messages to 4000 characters, which can truncate large messages.

To enable message tracing, you must add the traceEncryptedInfo registry entry to the gateway registry key. This entry triggers a full log of each message before and after encryption and decryption. You must still use trace level 4 to trace this information.

You can use the following values for the traceEncryptedInfo registry entry.


Note –

Waveset preserves password encryption in the logs. Tracing encrypted information does not expose passwords in clear text.


How to Configure Tracing for the PowerShellExecutor.dll Add-On

The PowerShellExecutor.dll is an add-on that implements communication between the gateway and Microsoft PowerShell. You can use PowerShell to manage Exchange Server 2007 accounts. This add-on cannot share tracing facilities with the rest of the gateway and provides a similar stand-alone tracing facility as the rest of the gateway.

The trace configuration for the PowerShellExecutor is stored in the same registry key as the other gateway registry keys:

HKEY_LOCAL_MACHINE\Software\Waveset\Lighthouse\Gateway

You create this base key when you configure tracing through the Waveset debug pages or when you start the gateway with trace command arguments.

On shut down, the gateway writes the current PowerShellExecutor settings for the tracing to the registry. These settings include:

All trace settings are reread from the registry based on this timeout value. In a production environment, consider setting this value to a large value, such as 24 hours, to minimize overhead.

How to Capture Dr. Watson Logs

If the Gateway encounters a serious problem and exits abnormally, you can send the resulting Dr. Watson logs to Oracle Support for analysis.


Note –

You must have administrator privileges on the system to view these logs.


ProcedureTo Capture a Dr. Watson Log:

  1. Open the Windows Event Viewer.

  2. Open the application log.

  3. Look for an event with DrWatson source.

  4. Open the event to view detailed information.

  5. Ensure that the Bytes option is selected for Data.

  6. Right-click in the display dialog and choose Select all from the menu.

  7. Type Ctrl-C to copy the information.

  8. Paste the information into Notepad and save the file.

  9. Send the file in an email to Oracle Support with a detailed description of the problem. Be sure to indicate which version of the Waveset Gateway you are running.