Tracing the Identity Manager Gateway Objects and Activities

This section describes how to trace objects and activities in Sun Identity Manager Gateway, the information is organized as follows:

• How to Configure Tracing from the Gateway Debug Page

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

• How to Capture Dr. Watson Logs

• When viewing or editing a Gateway trace file, use Notepad to avoid file restrictions.

• When you start the Gateway, the program appends new trace entries to the trace file instead of deleting entries. To locate the point at which the Gateway trace entries begin, look for a Gateway version string.

• The Gateway version is output in the trace automatically when you start the Gateway. You can also type gateway -v from the command line to get the version.

How to Configure Tracing from the Gateway Debug Page

You can enable tracing from the Gateway Debug page (Gateway.jsp) or from the command line to debug problems with Windows accounts on Identity Manager.

Instructions are provided in the following sections:

• From the Gateway Debug Page

• From the Command Line

From the Gateway Debug Page

Enable tracing from the Gateway Debug page (Gateway.jsp) if you cannot access the Gateway. You can specify and retrieve Gateway trace files from this debug page.

To Enable Tracing:

1. Log in to the Identity Manager 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.

From the Command Line

Enabling trace from the command line is useful if you want a wider range of options.

To Enable Tracing:

1. Open a command window.

2. Start the Gateway, specifying 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 provides 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, Identity Manager 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 -f name -l -m

   For example:

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

   The preceding invocation starts the Gateway with the following characteristics:

   • -d – Use regular application (not a service)

   • -p 11319 – Use port 11319

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

   • -f %CD%\gateway.trc – Directory to which the trace output is written. Identity Manager writes the trace output to a text file in this directory.

   • -l 2 – Output level 2 of Gateway tracing.

   • -m – Maximum size in Kilobytes of trace log file.

   ---

   Note –

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

   Identity Manager sends the Gateway trace output to the console and to a trace file.

   ---

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. The PowerShell is used 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 Identity Manager 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:

• traceFileName

  Content. File name for the trace output (registry type REG_SZ)

  Default. " "

  Name of the trace file to generate for the PowerShellExecutor tracing. Where the name:

  • Can be a fully qualified path, including the filename

  • Cannot end in a slash (\)

    The full path, except the file, provided in the traceFileName must exist.

    If configured, log rotation adds a timestamp to the configured filename after rotation, when the file is no longer active. This timestamp displays in the following format:

    yyyyMMddHHmmss

• traceLevel

  Content. Trace level (registry type REG_DWORD)

  Default. 0 (no tracing)

  Allowed. 0–4

  This key is shared with the rest of the gateway. The whole gateway always provides tracing at the same level.

• traceMaxSize

  Content. Maximum file size in bytes (registry type REG_DWORD or REG_QWORD)

  Default. 100000 bytes

  Minimum. 100000 bytes

  Tracing text is written as UTF–8 encoded text with a byte order mark to make it portable to other systems.

• traceMaxFiles

  Content. Number of trace files (registry type REG_DWORD)

  Default. 2

  Minimum. 1

  This setting controls the number of trace files to keep on the system. Setting the maximum number of files to keep to 1, causes the file to be overwritten when the maximum size is reached. The oldest file, based on last write time, is removed when the maximum number of files is reached.

• traceConfigInterval

  Content. Time out in milliseconds (registry type REG_DWORD)

  Default. 300000 ms (5 minutes)

  Minimum. 60000 ms (1 minute)

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 Sun Support for analysis.

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

To 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 Sun Support with a detailed description of the problem. Be sure to indicate which version of the Identity Manager Gateway you are running.