Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun Java[tm] System Identity Manager 6.0 Tuning, Troubleshooting, and Error Messages 2005Q4M3  

2

Troubleshooting and Tracing

Trace output can be helpful when identifying and resolving problems, or when developing a custom resource adapter.

The following sections discuss how to trace a variety of objects and activities:

General Tracing Method

Generally, these are the steps you will follow when using tracing to help identify and resolve problems:

  1. Turn on tracing.
  2. Reproduce the problem.
  3. Evaluate the results.
  4. Optionally, turn tracing on for additional packages or classes, or turn up the tracing level and repeat steps 2 and 3 as needed.
  5. Turn off tracing.

Tracing the Identity Manager Server

The Identity Manager system is a Java-based product whose executables are made up of Java classes grouped as packages. When the code is implemented, many classes have trace output entered.

Identity Manager server tracing can provide helpful information about where the server is failing, having problems, or not running. You can use the Identity Manager debug Web pages (http://<host>:<port>/<idm>/debug) to enable package-level and method-level tracing in a running Identity Manager server.

Note  You should configure Identity Manager to trace at this advanced level only if instructed by Sun Support.

By default, Identity Manager stores a trace configuration object, which can contain any number of server-specific trace configurations. The default configuration is named Global, but each server can have its own configuration. The server-specific configuration overrides the Global configuration when named with the same name as the host where the Identity Manager server is running.

To view and edit the list of defined trace configurations:

  1. From the Identity Manager Administrator Interface, display the System Settings page (http://<host>:<port>/<idm>/debug).
  2. Click Show Trace List.
    • Click an item in the list to edit it.
    • Click New to define a new trace configuration.

Defining a Trace Configuration

To set up a trace configuration:

  1. Determine the package or method that you need to trace. Typically, this is the resource adapter name, or is revealed in an error message.
  2. Click New from the trace list, or click Show Trace from the System Settings page.
  3. Enter a name for this configuration.
  4. Select the Trace Enabled option.
  5. Enter the name or names of classes/packages or methods you want to trace.

    6. For example:

    • To trace all classes in the waveset.repository package, enter com.waveset.repository.
    • To trace the AbstractDataStore class in the waveset.repository package, enter com.waveset.repository.AbstractDataStore.
    • To trace the list method in the AbstractDataStore class in the waveset package, enter com.waveset.repository.AbstractDataStore#list.
  6. Enter a trace level (0-4). Each level captures different types of information:
    • 0 – Disable tracing
    • 1 – Entry and exit of public methods, plus major exceptions
    • 2 – Entry and exit of all methods
    • 3 – Significant informational displays (such as the value of variables that control flow) that occur only once per method invocation
    • 4 – Informational displays that occur n times per method invocation
  7. Select the location to send trace output information. You can send it to standard output or to a file. If you select file, the Trace File field appears; you can enter an alternate file location and name for the trace output. (The default location and name is PathtoLighthouseInstallation\config\WSTrace.log).
  8. Set the maximum number and size of trace files. When the maximum size is reached, a new trace file is created. When all designed trace files are created and full, the files are overwritten.
  9. Set the date and time format that displays in the trace output.
  10. Set the maximum number of methods that will be cached.
  11. Select synchronous (the default selection) or asynchronous mode. If you select synchronous, data is written to the trace output file as it is generated. If you select asynchronous, data is first queued and then written to the trace file.

    12. Note  You can also use the Identity Manager console to enable and disable tracing. After setting $WSHOME, open the Identity Manager console from the bin directory with the command:

    lh console

    From the console, type trace to see a detailed summary of available trace options.

Viewing the Trace File

By default, tracing information sent to a file is stored in the config directory, in files named WSTrace#.log. Each file is numbered, up to the maximum number you specify on the Edit Trace Configuration page.

Tracing Custom Code

You can also use the Identity Manager tracing facility in custom-written code to provide seamless integration when troubleshooting the deployment.

The following two classes are used to provide tracing facilities:

For more details on their use, refer to the Javadoc for these classes.

Note  If custom code is instrumented in this fashion, be aware that the com.sun.idm.logging.trace facilities are not available in releases prior to Identity Manager 6.0. If this code also needs to be usable with earlier versions of Identity Manager, use the com.waveset.util.Trace class instead.

Global XPRESS Tracing

Global XPRESS tracing may be helpful when you are developing and updating forms and processes. You can enable tracing for all XPRESS functions on the server. XPRESS tracing is written to the JVM standard output.

For the recommended method of tracing XPRESS functions, refer to the section on block tracing in Identity Manager Technical Reference.

Alternatively, use the following procedure to enable XPRESS tracing. While not the recommended method, you may want to use this procedure because it shows all XPRESS output and may better expose where the problem is happening.

  1. Edit the config/Waveset.properties file.
  2. Modify the xpress.trace line to:

    3. xpress.trace=true

  3. Save the Waveset.properties file.
  4. Restart your application server, or reload the Waveset.properties file from the Identity Manager debug area.
  5. Redirect XPRESS trace output to a file by adding this line to the Waveset.properties file:

    6. xpress.traceFile=FileName.txt

Workflow Tracing

You can enable workflow tracing to help resolve problems with workflow activities. Tracing may also help you more thoroughly understand the workflow process and how it works.

Note  To debug workflow in a multi-server environment, you may want to shutdown all but one server for debugging. Otherwise, you cannot determine which server in the environment will execute the workflow, which can cause troubleshooting problems.

Setting Up Workflow Tracing

To set up workflow tracing

  1. Edit one (or more) of the following tracing output options in the SystemConfiguration object:

    2. Note  Normally, you enable only one of the tracing output options at a time, although you can enable more than one or all of them.

    • waveset.fileTrace – Set waveset.fileTrace=PathtoFile (where PathtoFile is the full pathname of the file) to print trace messages to a file.

      • This option is the most useful workflow trace setting because it writes the tracing to one file that is easy to read.

    • workflow.trace – Set workflow.trace=true to place trace messages in the task’s WavesetResult.

      • This option appends one long string to the WavesetResult, which is difficult to read because it is not formatted. This option is most useful when you do not have access to the file system.

    • waveset.consoleTrace – Set workflow.consoletrace=true to print messages to the console.

      • This option can be useful when workflows are terminating due to a fatal exception. The previous two options might lose the last bit of workflow trace when a fatal exception occurs.

  2. Save the SystemConfiguration object.
  3. Restart your application server, or reload the SystemConfiguration object from the Identity Manager debug area.

Setting Up Workflow Trace for a Designated Process

You can turn on workflow trace for a designated workflow in one of two ways:

Example Workflow Variable Trace

<Variable name='trace'>

   <cond><eq><ref>accountId</ref><s>jfaux</s></eq>

     <s>workflowTrace.txt</s>

   </cond>

</Variable>

This setting turns trace on only if the workflow is operating on a user named jfaux. You could also set this in a form field to control trace interactively.

Task Scheduler Tracing

You can use the standard tracing facility on com.waveset.task.Scheduler to trace the task scheduler if a task is having problems.

See Tracing the Identity Manager Server for more information.

Exceptions Tracing

Identity Manager provides a configuration option to log exceptions as they occur. Not all exceptions are included in trace data, so this can be an important and informative troubleshooting tool when combined with other data.

To log all exceptions that are created, specify exception.trace=true in config/Waveset.properties in your Identity Manager installation. Setting this option to true causes the creation of all exceptions to be logged to stdout of the web application instance, which is often the application server console.

It is common to see an exception when an expected error condition occurs or the error condition is subsequently handled appropriately. Consequently, not all exceptions are true error conditions that require attention or action. For example, sometimes the only way to test for the existence of an object is to ask for it. An exception might be thrown, indicating that the object was not found, but this could be an acceptable situation and therefore the exception does not indicate a problem.

To prevent unnecessary output to the application server logs (and the confusion that this output might create), remember to disable the exception.trace option by setting the value back to false after the troubleshooting exercise is complete.

Analyzing Application Server Logs

You can analyze application server logs to see fatal errors and other server-related problems. Most application servers have a standard location for standard out and standard error for the JVM running the application server.

Find the logs directory or the log files specified for your Identity Manager application server. To see minor messages and other tracing, open the standard out (stdout) file. For fatal and critical exceptions, view the standard error (stderr) file.

Enabling Identity Manager Gateway Tracing

You can configure the Sun Identity Manager Gateway to trace debugging Windows management for Identity Manager. The trace output is useful for determining problems when managing Windows accounts.

To enable gateway tracing:

  1. Go to the gateway Debug page at http://server_name/idm/debug/Gateway.jsp.
  2. Select a resource to be traced from the first select list.
  3. Select one of the following options:
    • Get Version — Returns the version of the Identity Manager gateway, and the operating system on the machine 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 Defining a Trace Configuration for information about these options.

      • Notes:

    • View or edit the trace file with Notepad to avoid file restrictions.
    • When the maximum file size is reached, Identity Manager renames the file to FileName.bk and opens a new file.
    • When the gateway is started, it appends new trace entries to the existing trace file (rather than deleting existing entries). To find points where the gateway starts, look for the “Gateway version” string.
    • The gateway version is output in the trace on startup. You can also type gateway -v from the command line to show the version.

Capturing Dr. Watson Logs for the Gateway

If the gateway encounters a serious problem and exits abnormally, the resulting Dr. Watson logs can be captured and sent to Sun Support for analysis.

To capture a Dr. Watson log:

  1. Open the Windows Event Viewer.
  2. Open the application log.
  3. Look for an event with source “DrWatson.”
  4. Open the event to view detailed information.
  5. Ensure that the Bytes option is selected for Data:.
  6. Right-click in the display box, and then select Select all from the menu.
  7. Type Ctrl-C to copy the information.
  8. Paste the information into Notepad, and then save the file.
  9. Email the file to Sun Support with a detailed description of the problem. Be sure to indicate which version of the Identity Manager Gateway you are running.

Debugging Errors Displayed through the Browser

If a red error message displays in the Identity Manager interface after you have performed an action, you may be able to view more complete information and further analyze the error by viewing and saving the page source. To do this:

  1. From the page where the error appears, select to view the page source. (If you are using Internet Explorer, select View > Source from the menu bar; in Netscape, select View > Page Source.)
  2. Select File > Save to save the file to your system.
  3. Search for the error in the saved file.
  4. Capture the error, the URL where the problem occurred, and a description of the problem, and then email it to Sun Support for resolution assistance.


Previous      Contents      Index      Next     

Copyright 2006 Sun Microsystems, Inc. All rights reserved.