Trace output can be very helpful when you are trying to identify and resolve problems, or when you are developing custom resource adapters.
This section describes how to enable tracing for a variety of Identity Manager objects and activities. The information is organized as follows:
Tracing affects system performance. To ensure optimal performance, specify the minimum tracing level or turn tracing off after debugging the system.
You can enable and configure tracing from several locations within Identity Manager. Instructions are provided in the following sections:
The System Settings page is the primary Identity Manager Debug page.
From this page, you can
View and edit objects in the repository
Clear caches
Set specialized traces
Reload the Waveset.properties file
Use the following steps to enable tracing from the Identity Manager System Settings page:
Open a browser and log in to the Identity Manager Administrative interface.
Type the following URL:
http://hostport/idm/debug
where:
host is the local server on which you are running Identity Manager.
port is the number of the TCP port on which the server is listening.
When the System Settings page displays, click Show Trace (located near the bottom of the page) to manage a single trace configuration, where you can create, modify, or delete up to ten trace settings.
The remaining instructions assume you have only one trace configuration.
To manage multiple trace configurations, click the Show Trace List button instead. When the Trace Configuration page displays, click the configuration name to edit the current settings.
Identity Manager supplies one configuration, called Global, by default. However, if you have multiple servers in an Identity Manager instance, defining different configurations for particular servers might be useful. If the name of a trace configuration matches the name of the current host, the host configuration overrides the Global configuration.
After you configure tracing, you can view and edit the default global trace configuration object or create a new configuration object as described in the following sections:
From the Edit Trace Configuration page, click the Trace Enabled box to enable tracing.
Deselecting this box stops tracing, but keeps your configuration. You can turn tracing on and off without having to remember and retype the classes you were tracing.
Specify which classes, packages, or methods to trace by typing their names into the table.
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.
Do not enable trace for the com.waveset class. The com.waveset class is verbose and has many classes, so tracing this class might cause your server to hang.
In the same table, choose a Method/Class tracing level from the Level menu.
Each level captures different types of information, as described in the following table:
Trace Level |
Description |
---|---|
0 |
Minimum debugging output, traces exceptions and error information only |
1 |
Trace Level 0 events, plus entries and exits for public methods |
2 |
Trace Level 1 events, plus entries and exits for non-public methods |
3 |
Trace Level 2 events, plus decision points and significant variables |
4 |
Maximum debugging output |
Method/Class tracing produces a predictable, but possibly very large volume of trace output. Try to be as specific as possible when specifying methods and classes to trace.
(Optional) To enable subcall tracing, choose a level from the Subcall Trace menu. This menu uses the same trace numbering scale described in the previous table.
The default Subcall Tracing level is none, which disables subcall tracing on a per-method or per-class basis.
Subcall Tracing levels are independent of the Method/Class tracing levels you specified in the previous step.
When you enable Subcall Tracing for a particular method that supports subcall tracing, you are automatically setting the tracing level for methods that are called by this method. Subcall Tracing enables you to produce a short, but detailed burst of trace output that is triggered by the entry into a specified method and terminated by the method’s exit.
For example, assume you created a trace configuration setting for the com.waveset.adapter.NewRes#init method, set Method/Class tracing to level one and set Subcall tracing to level three.
Also, assume that the init method calls two other methods:
NewRes#subcallA
NewRes#subcallB
When the init method runs, the com.waveset.adapter.NewRes#init method produces trace output at level one until reaching subcallA. When subcallA begins executing, the trace level changes to three and continues at that level until subcallA exits. The com.waveset.adapter.NewRes#init method returns to the init method and restores the trace level to one. Later, when init calls subcallB, there is another burst of level three trace detail that lasts until subcallB exits. Finally, when init exits, level one tracing stops.
Send the trace results to a specified file location or to stdout.
If you choose output to a file, the Trace File field displays. Use this field to specify an alternate location and file name for trace output files. The default location and file name is
path_to_idm_install\export\pipeline\config\WSTrace.log |
Specify the maximum number of trace files to store (default is 2).
Specify the maximum size for each file (default is 512K).
Specify whether to write the trace output file as generated (synchronously) or to queue the data and then write it to the trace file (asynchronously).
Save your changes.
Use the following steps to create a new trace configuration object:
Decide which package or method you want to trace.
Generally, you specify a resource adapter name or use information that was revealed in an error message.
Log in to the Identity Manager Administrator interface and open the System Settings page as described in To Enable Trace from the System Settings Page.
On the Systems Setting page, click Show Trace List.
When the Identity Manager Trace Configuration page displays, click New.
Enable tracing from the Edit Trace Configuration page.
Choose one of the following options from the Trace Configuration menu:
Global. Select to enable tracing for all servers.
Server_name. Select a server name to enable tracing for a particular server.
Select the Trace Enabled box to enable tracing for this object and configure the remaining parameters on this page as described in To Edit the Default Configuration Object.
Save your changes.
This section describes how to enable tracing from an Identity Manager Debug page.
Open a browser and log in to the Identity Manager Administrative interface.
Type the following URL:
http:// host:port /idm/debug/pageName.jsp
where:
host is the local server on which you are running Identity Manager.
port is the number of the TCP port on which the server is listening.
pageName.jsp is the particular Debug page you want to open.
For example, to trace adapter classes and methods for a custom adapter, you can open the Edit Trace Configuration page by typing the following URL:
http://host :port/idm/debug/Show_Trace.jsp
This section explains how to enable tracing from the Identity Manager console.
Set $WSHOME.
For example, to set the variable to the default installation directory:
set WSHOME=C:\Program Files\tomcat\webapps\idm |
Type lh console to open the Identity Manager console from the bin directory.
From the console, type trace to see a detailed summary of available trace options, including enable and disable.
The syntax for this command is:
trace [ -s server ] $subcommand
By default, Identity Manager sends tracing information to a file named WSTrace#.log that is stored in the path_to_idm_install\export\pipeline\config\ directory. If necessary, you can specify alternate file names and locations when you configure tracing for an object.
Each log file is numbered sequentially, up to the maximum number of files specified on the Edit Trace Configuration page. For example, if you specify a maximum of three files, the files are named WSTrace1.log, WSTrace2.log, and WSTrace3.log.
Use one of the following methods to view these log files:
If you are sending trace information to a file, open the trace file from the specified location. For example:
path_to_idm_install \export\pipeline\config\WSTrace2.log |
If you are sending trace information to stdout, open your application server’s stdout file in a text editor to view the trace output logs.
Identity Manager is a Java-based product whose executables consist of Java classes grouped as packages. When the code is implemented, many classes can supply trace output.
Tracing the Identity Manager server can provide helpful information such as where a server is failing, having problems, or not running. You can use the Identity Manager Debug pages to enable package-level and method-level tracing in a running Identity Manager server.
Configure Identity Manager to trace at this advanced level only if instructed by Sun Support.
You can use trace information to verify that a resource adapter has started, to verify that all setting changes were saved, and to diagnose problems with the adapter.
This section contains information to help you configure adapter tracing, and is organized into the following topics:
When you enable tracing for an adapter, you must identify the methods that you want to trace by typing:
com.waveset.adapter.sample.MyResourceAdapter |
You must also provide calls to create log entries for any new methods in your custom resource adapter so the adapter can write its resource settings to a log file.
In some cases, you can specify additional logging parameters for the resource instance, such as:
Maximum Log Archives
Maximum Active Log Age
Log File Path
Maximum Log File Size
Log Level
To further debug the synchronization process, you can configure synchronization logging for an ActiveSync adapter. Instructions are provided in the Identity Manager online help.
Tracing custom Java code can be useful when you are writing your own resource adapter. See Tracing Custom Code for more information.
You can instrument code with trace points to help assess and resolve problems more effectively. See Instrumenting Code with Trace Points for more information.
For more information about tracing specific adapter methods, see the Sun Identity Manager 8.1 Resources Reference.
The Identity Manager trace facility enables you to instrument code with trace points in the adapters component (resource adapters). This section contains some guidelines to help you to consistently use trace points to assess and resolve adapter problems.
Some guiding principles for instrumenting code with trace points are as follows:
Make trace points as useful as possible for troubleshooting in both production and development environments by displaying relevant information.
Create one entry point and one exit or exception trace point for every significant method.
Use trace points as efficiently as possible during normal operations and when tracing is enabled by
Minimizing the number of trace level checks
Minimizing object creation when tracing is enabled
You can specify a trace level for a trace point to control how much information displays. The following table describes each of the trace levels that are defined in the com.sun.idm.logging.TraceManager interface.
Table 5–2 Defined Trace Levels
Trace Level |
Trace Variable |
Usage |
---|---|---|
1 |
Trace.LEVEL1 |
Entry and exit points of public methods of the resource adapter interface |
2 |
Trace.LEVEL2 |
Entry and exit points of non-public methods or methods not included in the Identity Manager component external interface |
3 |
Trace.LEVEL3 |
Decision points or significant variables |
4 |
Trace.LEVEL4 |
Very detailed information, such as significant variables within a loop |
n/a |
Trace.ALWAYS |
Do not perform a trace-level check Note: Use this option if you have already specified the trace level in a condition. |
Use the com.sun.idm.logging.Trace class to prevent circular dependencies on the com.sun.idm.logging package that implements the com.sun.idm.logging.TraceManager interface.
When adding trace points to code, be aware of the following information:
Trace arguments to the method and return values from the method.
If the arguments “print large,” where the text representation is not brief, specify whether the Object is null or not. If the argument or return value is an array or a list, and the value could print large, showing the array size or list size is sufficient. You can use the com.waveset.util.Util.length() utility method to guard against null values.
To format trace information or to create objects that present trace information in a meaningful way, put an if statement around the trace statements, using the Trace.getLevel method and the isLogging(level) method, so that Identity Manager does not marshal the trace point data unless the specified trace level is enabled.
When using this construct, specify the Trace.ALWAYS trace level for trace points inside the condition. This trace level prevents an unnecessary check for the trace level when that check has already been performed in the condition.
If you are tracing an object value that requires a method call to get a printable representation of the object, such as obj.getName(), guard against a null object to prevent a NullPointerException occurring if trace becomes enabled.
In general, do not use trace points for simple getter and setter methods or for any other trivial methods.
When tracing a WSUser object, use the toString() method instead of the getName() method to present the value of the object. The toString()) method is more robust and prints more useful information than the getName() method. Instead of tracing user.getName(), trace user, which calls toString() implicitly.
If a method or constructor is just a wrapper, where that method or constructor does nothing significant except call another method or constructor with the same name but a different signature, just put trace points into the destination method or constructor.
If performance is critical and the method is called many times, use information trace points to indicate errors. Do not add entry or exit trace points to the method. Use this option carefully.
Before adding a trace point, ask yourself if that trace point will provide useful information when determining problems in the field.
The following sections describe specific trace levels in greater detail and provide examples showing how to use trace points in code.
Consider these guidelines before adding entry and exit trace points to your code:
Use Trace.Level1 entry or exit trace points for all Identity Manager component external interface methods, which are the public methods declared in the resource adapter interface.
Use Trace.Level2 entry or exit trace points for significant non-public methods including constructors and static methods or methods not included in the Identity Manager component external interface.
Specify arguments in the trace points.
If the argument is not a primitive type or java.lang.String, and the argument requires any kind of object creation or method calls, conditionalize the entry trace point so that the formatting work is only done when tracing is enabled.
When specifying an exit trace point, show the return value if the method is a primitive type or java.lang.String. If the return value requires some sort of formatting, conditionalize the object formatting as specified in these guidelines. Use the following:
int getLevel() int getLevel (Method) boolean isLogging(level,method) boolean level1 (method) boolean level2 (method) boolean level31 (method) boolean level4 (method) |
If you are tracing information that requires appending several java.lang.Strings together, use java.lang.StringBuffer instead of java.lang.String. Appends are faster using java.lang.StringBuffer. Also, conditionalize as in the preceding bullet item.
When adding entry or exit trace points for significant constructors, remember that you cannot place a trace point before a this() or super() method call within a constructor. Put the entry trace point immediately after the this() or super() method call.
Do not use an exit trace point to trace an exception condition. If the method throws an exception, use an exception trace point at the same trace level as the entry or exit trace point just before the exception is thrown. See Using Exception Trace Pointsfor more information.
If a method contains an entry trace point, that method also must contain a code path that executes either a throwing method, a caught method, or an exit.
Following are some simple entry and exit trace statements. For these examples, assume the following CLASS variables are declared for each statement.
private static final String CLASS = "com.waveset.adapter.MyResourceAdapter"; protected static Trace _trace = Trace.getTrace();
final String METHOD = methodName; _trace.entry(_trace.LEVEL1, CLASS, METHOD); _trace.entry(_trace.LEVEL1, CLASS, METHOD, user); if (_trace.level1(CLASS, METHOD)) { _trace.entry(_trace.ALWAYS, CLASS, METHOD, user= + user); } // Show the size of an array argument // ASSUME: password is an argument to the method // Note the use of the Util.length() method. It is // a convenience method that guards against null. if (_trace.level1(CLASS, METHOD)) { StringBuffer sb = new StringBuffer(32); sb.append(password length=); ab.append(Util.length(password)); _trace.entry(_trace.ALWAYS, CLASS, METHOD, sb.toString()); }
_trace.exit(_trace.LEVEL1, CLASS, METHOD); _trace.exit(_trace.LEVEL1, CLASS, METHOD, returnValue); if (_trace.level1(CLASS, METHOD)) { _trace.exit(_trace.ALWAYS, CLASS, METHOD, returnValue != null ? returnValue.getName() : returnValue); } // Show the size of an array String[] accounts = ... if (_trace.level1(CLASS, METHOD)) { StringBuffer sb = new StringBuffer(32) sb.append(accounts length=); ab.append(accounts.length); _trace.exit(_trace.ALWAYS, CLASS, METHOD, sb.toString()); }
Consider these guidelines before adding information trace points to your code:
Generally, use Trace.Level3 or Trace.Level4 for information, variable and data trace points. The trace level depends upon the significance, expense, and the verbosity of the information presented.
Use Trace.Level3 and Trace.Level4 information and variable trace points to trace significant conditions, branches, and other information as they occur in the code path.
A variable trace point is a convenience method that is the same as an information trace point, except that a variable trace point prints out variable=<variable> instead of just printing the argument value. In addition, this method does not format the information unless the trace level specified in the argument is matched.
Do not use an information trace point if the method contains an exception condition but does not rethrow the exception. Use the caught method. For an example, see Using Exception Trace Points.
Use Trace.Level3 and Trace.Level4 data trace points to show information in byte arrays. You can use a lower trace level if the information is appropriate for that trace level and the information presented is brief.
You can use Trace.Level1 and Trace.Level2 information, variable, and data trace points to trace significant, but brief, information. However, you should rarely use these trace points at these levels.
Following is an example of a simple information trace statement. For this example, assume the following CLASS variables are declared.
private static final String CLASS = "com.waveset.adapter.MyResourceAdapter"; protected static Trace _trace = Trace.getTrace();
_trace.info(_trace.LEVEL3, CLASS, METHOD, Some Message); WavesetResult result = new WavesetResult(); try { someMethod(); } catch(Exception e) { String msg = Some Error Message; WavesetException we = new Waveset(msg, e); _trace.caught(_trace.LEVEL3, CLASS, METHOD, e); result.addException(we); }
Consider these guidelines before adding exception trace points to your code:
Use exception trace points in all methods where entry or exit trace points are specified, and in methods that catch and rethrow exceptions. Identity Manager sometimes throws exceptions in which a new exception wraps the original exception. Use the same trace level being used by the entry and exit trace points.
Use an exception trace point if an exception is created and thrown from the current method.
Use an exception trace point caught method if an exception is caught and handled. For example, when the exception is not thrown from the current method. This situation typically occurs when Identity Manager catches and handles the exception by placing it in a container, such as a WavesetResult, to be examined later.
If the exception thrown from the current method is not a checked exception, which is an exception that extends java.lang.RuntimeException or java.lang.Error, the method exit point will not be traced unless other measures are taken. One way to set an exception trace point in this situation is to use a try/catch block around the critical section of the method and rethrow the exceptions that occur. In general, this means that you should use Trace.Level3 and higher when it is critical to know whether a method has succeeded or failed.
Following is an example of a simple exception trace statement. For this example, assume the following CLASS variables are declared:
private static final String CLASS = "com.waveset.adapter.MyResourceAdapter"; protected static Trace _trace = Trace.getTrace();
try { someMethod(); } catch(Exception e) { _trace.throwing(_trace.ALWAYS, CLASS, METHOD, e); throw e; } try { someMethod(); } catch(Exception e) { _trace.throwing(_trace.ALWAYS, CLASS, METHOD, e); WavesetException we = new WavesetException(Some Message, e); throw we; } if (error) { WavesetException e = new WavesetException(Some Error Message.; _trace.throwing(_trace.LEVEL3, CLASS, METHOD, e); throw e; } try { someMethod(); } catch(Exception e) { _trace.caught(_trace.LEVEL1, CLASS, METHOD, e); } // execution continues. someOtherMethod();
Using trace point templates can help you provide consistent and useful trace points in Identity Manager resource adapters. Identity Manager provides Eclipse templates in the following location:
src/wps/doc/eclipse-trace-templates.xml
To import these templates into Eclipse, select Window -> Preferences -> Java -> Editor -> Templates.
You can create similar templates if you are using Emacs or IDEA.
This section describes some additional tracing guidelines, including the following:
Remember to trace significant methods in inner classes. Be sure to declare a final static CLASS variable if there are any trace methods in the inner class.
private final static String CLASS = com.waveset.adapter.SomeResourceAdapter$AdapterInnerClass;
In general, do not use the trace facility in static initializers. Identity Manager executes these initializers when the class is loaded, which can occur when the repository is initialized. Use the Debug class to trace anything significant in static initializers.
You can trace the following methods to troubleshoot issues with Identity Auditor:
com.sun.idm.auditor.policy to trace issues with Audit Scans.
com.sun.idm.auditor.accessreview to trace issues with Access Reviews.
com.sun.idm.auditor.report to trace issues with Audit Reports.
com.sun.idm.auditor.view to trace issues with Auditor Views.
Open a browser and log in to the Administrator interface.
Select Configure -> Servers.
When the Configure Servers page displays, click the server name in the Server column to edit the settings.
On the Edit Server Settings page, click the Scheduler tab.
Select the Tracing Enabled box to activate Scheduler debug tracing and write the results to stdout.
Save your changes.
You can use the Identity Manager tracing facility in custom-written code to provide seamless integration when troubleshooting your deployment.
Use the following classes to provide this tracing facility:
Use com.sun.idm.logging.trace.Trace objects to interface with the tracing subsystem.
Use com.sun.idm.logging.trace.TraceManager as a factory for these objects.
You can also use these com.sun.idm.logging.trace facilities to record trace output. See the JavadocTM for more information about these facilities and classes.
Be aware that the com.sun.idm.logging.trace facilities were not available prior to the Identity Manager Version 6.0 SP1 release. For earlier versions of Identity Manager, you must use the com.waveset.util.Trace class instead.
Exception logs are stack traces that you can view from the Identity Manager Debug pages or from the config/Waveset.properties file. Trace data does not include all exceptions by default, but exception logging can be an important and informative troubleshooting tool.
Use one of the following methods to enable exception logging:
Open the Waveset Properties page (debug/Show_WSProp.jsp) in the Identity Manager Administrator interface. Locate the exception.trace key and change the Value to true.
Open the config/Waveset.properties file in a text editor, and change the exception.trace key value to true. The following figure shows an example exception trace.
Identity Manager sends exception logs to stdout on the web application instance, which is often the application server console.
When you are finished, disable exception logging to stop unnecessary output to the application server logs. To disable exception logging, set the exception.trace key value back to false.
You can enable tracing to troubleshoot edited forms and to check for expression statement errors within your form fields.
Use either of the following methods to enable tracing:
Open the Waveset Properties page (debug/Show_WSProp.jsp) in the Identity Manager Administrator interface. Locate the form.trace key and change the Value to true.
Open the config/Waveset.properties file in a text editor, and change the form.trace key value to true.
Identity Manager reports any problems with form expression syntax to standard output.
The form.trace key is disabled by default because it produces trace information for every field on every page, including the Accounts List page, which affects system performance. Consider using a more targeted form and field tracing method.
When you are finished troubleshooting your forms, remember to disable tracing by changing the form.trace key value back to false.
Global XPRESS tracing might also be helpful while you are developing and updating forms and form processes. Although Global XPRESS tracing produces a large amount of output that affects system performance, this tracing method shows XPRESS output and might expose where problems are happening in your form.
For more information, see
While not generally recommended, you can use global XPRESS tracing to trace any and all XPRESS code, wherever the code is located. For example, you can trace XPRESS code in forms, views, and workflows. The resulting trace shows XPRESS output that can expose potential problems.
XPRESS tracing is disabled by default because it produces a large amount of output, which affects system performance.
See Testing Your Customized Form in Sun Identity Manager Deployment Reference for more information about tracing XPRESS functions.
Open a command window.
Change directories to config/Waveset.properties in the default Identity Manager installation directory.
Open the config/Waveset.properties file and edit the xpress.trace line to read:
xpress.trace=true |
Save the Waveset.properties file.
Restart your application server or reload the Waveset.properties file from the Identity Manager debug pages.
Replicate the XPRESS trace output to a file by adding this line to the Waveset.properties file:
xpress.traceFile=FileName.txt |
xpress.traceFileOnly=true |
When you set xpress.traceFileOnly=true in Waveset.properties, all XPRESS statement evaluations will generate trace messages to a file specified by xpress.traceFile. Otherwise, when xpress.traceFile has a value, trace messages are redirected to both the console and a file.
This section describes how to enable tracing for PasswordSync and how to configure tracing in Direct access or JMS modes.
You can use the following methods to configure tracing for Identity Manager’s PasswordSync feature:
This section describes how to configure tracing from the PasswordSync Configuration Trace tab.
For more information about installing and configuring PasswordSync, see Chapter 11, PasswordSync, in Sun Identity Manager 8.1 Business Administrator’s Guide.
The first time you run the configuration tool, the wizard does not allow you to configure tracing. Subsequently, when you run the configuration tool, the wizard displays a Trace tab where you can configure tracing.
The following figure shows the PasswordSync Configuration tool Trace tab.
From this tab, you can specify the following:
Use the Trace Level field to specify the level of detail you want PasswordSync to provide when writing to the trace log. A value of 0 turns tracing off, while a value of 4 shows full detail.
Use the Max File Size field to specify a maximum size for the log file.
When the trace file exceeds the size specified in the Max File Size (MB) field, PasswordSync starts a new trace file and appends .bk to the old trace file name. For example, if your trace level is set to 100 Mbytes, and your trace file writes to C:\logs\pwicsvc.log, when the trace file exceeds 100 Mbytes PasswordSync renames the file to C:\logs\pwicsvc.log.bk. PasswordSync then creates a new C:\logs\pwicsvc.log file where new trace file messages are written.
Use the Trace File field to specify a location for the PasswordSync trace file.
To enable additional PasswordSync configuration settings, edit the following PasswordSync registry keys using the PasswordSync configuration tool.
Using PasswordSync configuration tool is the safest method for editing PasswordSync registry keys. Editing these keys directly in the Windows Registry is discouraged.
Key Name |
Type |
Description |
---|---|---|
dumpFilebase |
REG_SZ |
Set this registry key to enable Windows to generate a dump file if the PasswordSync DLL displays an exception. You must set this registry key to the fully qualified directory path where you want to write the memory dump. For example: c:\temp Set the registry value to write the memory dump each time Identity Manager catches an exception during password processing. Note: On Windows 2000 server (any service pack), you also must install in the configured directory DbgHelp.dll, which is available from Microsoft. The minimum release version for the DbgHelp.dll file must be Version 5.1. Download the DbgHelp.dll file here: http://www.microsoft.com/whdc/DevTools/Debugging/default.mspx If DbgHelp.dll is not installed, no dump files will be generated on Windows 2000. The format for dump file names is lhpwic-YYYYMMDD-HHmm-xxxxx.dmp In this name, YYYYMMDD will be the date of the dump, HHmm is the time of the dump (24-hour clock), and xxxxx is the thread number of the application. You must manually remove dump files! Dump files range in size from 20 MB to more than 100 MB, depending on the size of the Windows Local Security Authority Subsystem (LSASS) process. Over time, systems with limited disk space could fill up if these dump files are not removed. |
installdir |
REG_SZ |
Directory where the PasswordSync application is installed. |
The PasswordSync registry keys are located in the following location:
HKEY_LOCAL_MACHINE\SOFTWARE\Waveset\Lighthouse\PasswordSync
Other keys are present in this location.
PasswordSync trace logs are the same, whether you are using a direct access mode or JMS mode configuration. However, these trace logs might only provide partial information. You must configure different classes for each configuration to collect logs on the server side, as described in the following sections.
When using PasswordSync with a direct access mode configuration, the trace logs show failures, but not all logged failures are real failures. For example, in some circumstances the view check-in takes a long time, which shows as a failure in the log. You must trace on the server side to see this information.
In Direct mode, PasswordSync talks to the servlet that generates the view to be checked into the repository. You can trace the com.waveset.rpc.GenericMessageHandler class at level 4 to view all phases of password synchronization, from receiving the password change to the response generated and returned to the servlet. Level 4 is the only level that supplies enough detail for troubleshooting.
When using PasswordSync with a JMS mode configuration, the logs only show successful or failed deliveries to the JMS server. From this point on, you must rely on server side logs. JMS tracing is a little more complex.
You can trace the com.waveset.rpc.PasswordSyncHandler class at level 4 to convert the messages generated by the PasswordSync dll into a JMS message and add those messages to the JMS queue. Limited tracing is available in this class, and only level 4 provides enough information to help with troubleshooting.
If PasswordSync successfully delivers the JMS message to the JMS queue, the tracing will not help you find the cause of a problem. The next, and final step is to trace the JMS adapter. See the Sun Identity Manager 8.1 Resources Reference for instructions.
You can trace rule-driven members caches and use the results to tune cache properties in Waveset.properties.
If you trace com.waveset.server.RuleDrivenMembersCache at Level 1, the resulting information includes the number of adds, removes, hits to the cache, and so forth. Use this information to evaluate cache sizes and decide whether tuning the cache properties in Waveset.properties is necessary.
You can use the following properties in Waveset.properties to control the rule-driven members cache:
Use ruledrivenmemberslistcache.size = value to specify the maximum number of object lists to be cached per subject. (Default is 20.)
Use ruledrivenmemberslistcache.rowlimit = value to specify the maximum total number of objects to be cached per subject. (Default is 100000.)
By default, Identity Manager evaluates the User Members Rule associated with a specified organization and creates a user members list cache containing a dynamic list of users. However, you can also create a user members list cache containing a specified user's set of dynamic member organizations for a given subject. The key to this cache is the object type concatenated with the object ID. For example, the User object type concatenated with the User#ID#Configurator object ID. The value for each key is a list of object groups for which this object is dynamically a member.
To determine whether the object being evaluated is a dynamic member, the cache evaluates the same User Members Rule per organization as that used by the list cache. If the object is a dynamic member, Identity Manager adds that object to the list and then caches the list. Identity Manager caches both empty and non-empty lists to ensure the highest cache hit rate.
For this cache, you can use these properties in Waveset.properties to control memory requirements affecting performance:
Use ruledrivenmembersobjectcache.size = value to specify the number of member object group lists to be cached per subject. The default value is 100.
Use ruledrivenmembersobjectcache.rowlimit = value to specify the maximum total number of member object groups to cache per subject. The default value is 100000.
Enabling Identity Manager tracing at Method/Class Level 2 for the following classes allows you to trace authorization flows when listing or accessing Sun Identity Manager Service Provider (Service Provider) users and when AdminRoles are dynamically assigned when Service Provider users login.
Trace com.sun.idm.idmx.view.IDMXBrowseViewer when searching for Service Provider users.
Trace com.sun.idm.idmx.view.IDMXUserViewer when creating, editing, or deleting Service Provider users.
Trace com.sun.idm.idmx.api.IDMXServerUtils when using both of the preceding classes.
Trace com.waveset.security.authn.WSSPELoginModule when you are logging in as a Service Provider user.
You configure Service Provider tracing from the Identity Manager debug pages. If necessary, review Tracing the Identity Manager Server for instructions.
If you are having problems with a reconciliation task, you can use the standard tracing facility on com.waveset.task.Reconciler to trace the Reconciler.
Use either of the following methods to enable tracing:
Open the Waveset Properties page (debug/Show_WSProp.jsp) in the Identity Manager Administrator interface. Locate the exception.trace key and change the Value to true.
Open the config/Waveset.properties file in a text editor, and change the exception.trace key value to true.
You can also enable tracing from the System Settings page and trace the following reconciliation methods, at the Method/Class trace Levels noted, to view useful debugging information.
Table 5–4 Reconciliation Methods/Classes to Trace
Trace this com.waveset.recon.Method/Class |
At this Trace Level |
To See |
---|---|---|
ReconTask$WorkerThread#reconcileAccount |
2 |
The individual account being reconciled |
ReconTask$WorkerThread#performResponse |
2 |
The individual account and user during response |
ReconUtil#deleteAccountIndex |
2 |
User information to be deleted from the account index |
UserContext#aquireRepoLock |
2 |
The user who is being locked for update |
UserContext#releaseRepoLock |
2 |
The user who is being unlocked in the repository |
ReconUtil#deleteAccountIndex |
2 |
User information to be deleted from the account index |
UserContext#aquireRepoLock |
2 |
The user who is being locked for update |
ReconTask$WorkerThread#failUserExamination |
2 |
All user examination requests that failed with the error |
ReconTask$WorkerThread#failUserResponses |
2 |
All user response requests that failed with the error |
UserContext#releaseRepoLock |
2 |
The user who is being unlocked in the repository |
ReconTask$ResourceThread#examineResource |
3 |
How many accounts read from the resource |
ReconTask$ResourceThread#queueAccountReconciles |
3 |
Information about each account read from the resource such as accountId, accountGUID, accountDisabled |
ReconTask$ResourceThread#examineLighthouse |
3 |
How many Identity Manager users claim to own an account on the reconciled resource queued |
ReconTask$WorkerThread#findClaimants |
3 |
All Identity Manager users who claim to have an account on the resource |
ReconTask$WorkerThread#confirmPossibleOwners |
3 |
A list of all confirmed owners of resource accounts |
ReconTask$WorkerThread#applyResponse |
3 |
The response list that is being applied |
AccountContext#processAttributeWorkflow |
3 |
The attribute changes and the formatted changes during the launch of the attribute change workflow |
ReconUtil#getRuleState |
3 |
Full User view with the user’s attribute during rule processing |
ReconUtil#evaluateCorrelationRule |
3 |
The value of the correlation rule state and result for examination |
ReconUtil#confirmPotentialOwners |
3 |
A list of users who have been confirmed using the confirmation rule |
ReconUtil#getIfExistsAccountIndexEntry |
3 |
To output info related to examination of the account index for a specified entry |
ReconUtil#launchWorkflow |
3 |
The task instance and task definition information when launched |
ReconUtil#indexFoundAccount |
3 |
The account and situation recorded during a create or update of the index for an account known to exist |
ReconUtil#indexMissingAccount |
3 |
The account and situation recorded during a create or update of the index for an account NOT known to exist |
ReconUtil#listAccountsIndexSaysExist |
3 |
Account information that the index says exists |
ReconTask$ResourceThreadwaitForLighthouseWorkItems# |
4 |
How many users queued and processed during the Identity Manager user examination process |
ReconTask$ResourceThread#waitForReconcileWorkItems |
4 |
How many reconciles and responses queued and processed for the specified resource |
ReconTask$WorkerThread#correlateUsers |
4 |
A list of correlated/confirmed users |
ReconTask$WorkerThread#respondOrRequeue |
4 |
The error message if there is a problem performing the previous response method for an account |
Response#perform |
4 |
The user, response, and the user’s resource info XML before and after the modifications took place |
Response#perform |
4 |
A summary of the response action on the user |
Response#createNewUserFromAccount |
4 |
Full details of the response action on the user |
ReconUtil#evaluateConfirmationRule |
4 |
The value of the confirmation rule state and result for examination |
ReconUtil#getCorrelatedUsers |
4 |
A list of correlated users matching the specified rule result |
Remember, the higher the tracing level, the larger the trace file. Also tracing all of these methods at the same time will create a very large trace file.
When you are finished troubleshooting, remember to disable tracing by setting the exception.trace key value back to false.
If you see errors while you are using the setRepo command to configure the Identity Manager repository, use the following flags to isolate and debug the problem:
-Dtrace.enabled=true -Dtrace.level.com.waveset.repository.AbstractDataStore=2 -Dtrace.level.com.waveset.repository.DefaultTypeHandler=4 // Use one of the following based on your repository type -Dtrace.level.com.waveset.repository.OracleDataStore=4 -Dtrace.level.com.waveset.repository.SqlServerDataStore=4 -Dtrace.level.com.waveset.repository.MysqlDataStore=4 -Dtrace.level.com.waveset.repository.DB2DataStore=4 |
Identity Manager sends output from the setRepo command to the default $WSHOME/config/WSTrace.log file.
This section describes methods for enabling trace for SPML Version 1.0 and SPML Version 2.0.
SPML 1.0 provides the following options for turning on trace output so you can log Identity Manager’s SPML traffic and diagnose problems.
You can use the setTrace method, provided by the SpmlClient and LighthouseClient classes, to enable tracing for SPML 1.0.
When you enable this setTrace method, the XML for the request sent by the client and the XML for the response received from the server are printed to the client console as they are sent and received.
The setTrace method takes a Boolean argument. For example:
SpmlClient client = new SpmlClient(); client.setURL("http://localhost:8080/idm/spml"); client.setTrace(true); |
You can enable tracing when initializing the org.openspml.server.SOAPRouter servlet, which is a third-party, open source class from the OpenSPML organization. This servlet controls the output of RPC traffic information for the servlet handling SPML requests.
To enable this tracing method, add the following to the WEB-INF/web.xml file:
<servlet> <servlet-name>rpcrouter2</servlet-name> <display-name>OpenSPML SOAP Router</display-name> <description>no description</description> <servlet-class> org.openspml.server.SOAPRouter </servlet-class> <init-param> <param-name>trace</param-name> <param-value>true</param-value> </init-param> ... </servlet> |
The following is sample output for an SPML 1.0 trace:
SpmlClient: sending to http://example.com:8080/idm/servlet/rpcrouter2 <spml:addRequest xmlns:spml='urn:oasis:names:tc:SPML:1:0' xmlns:dsml='urn:oasis:names:tc:DSML:2:0:core'> <spml:operationalAttributes> <dsml:attr name='session'> <dsml:value>session token</dsml:value> </dsml:attr> </spml:operationalAttributes> <spml:identifier type='urn:oasis:names:tc:SPML:1:0#GUID'> <spml:id>suetonius</spml:id> </spml:identifier> <spml:attributes> <dsml:attr name='objectclass'> <dsml:value>person</dsml:value> </dsml:attr <dsml:attr name='password' <dsml:value>password</dsml:value> </dsml:attr> <dsml:attr name='gn'> <dsml:value>Suetonius</dsml:value> </dsml:attr> <dsml:attr name='sn'> <dsml:value>Tranquillus</dsml:value> </dsml:attr> <dsml:attr name='email'> <dsml:value>twelve@example.com</dsml:value> </dsml:attr> </spml:attributes> </spml:addRequest> SpmlClient: received <?xml version='1.0' encoding='UTF-8'?> <SOAP-ENV:Envelope xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/'> <SOAP-ENV:Body> <spml:addResponse xmlns:spml='urn:oasis:names:tc:SPML:1:0' xmlns:dsml='urn:oasis:names:tc:DSML:2:0:core' result='urn:oasis:names:tc: SPML:1:0#success'> <spml:operationalAttributes> <dsml:attr name='session'> <dsml:value>session token</dsml:value> </dsml:attr> </spml:operationalAttributes> <spml:identifier type='urn:oasis:names:tc:SPML:1:0#GUID'> <spml:id>suetonius</spml:id> </spml:identifier> </spml:addResponse> /SOAP-ENV:Body> </SOAP-ENV:Envelope> |
For more information about the SOAP rpcrouter servlet, refer to your OpenSPML Toolkit documentation.
You can enable tracing for an individual SPML RPC request by passing a trace operational attribute to the RPC request on the server side.
Tracing occurs during servlet initialization, and it controls how information is output for the RPC traffic of a servlet handling SPML Version 1.0 requests. For example, the trace prints the raw XML that is sent back and forth on whatever the System.out is for that servlet (which is a function of the Application container). For example:
AddRequest ar = new AddRequest(); ar.setOperationalAttribute("trace", "true"); |
When you use the trace attribute, how the attribute affects server operation is vendor-specific. Currently, Identity Manager prints the raw request and response data to the server console, which is useful if the client application is not associated with a console window.
For more information consult your OpenSPML Toolkit product documentation.
SPML 2.0 provides the following options for turning on trace output so you can log Identity Manager’s SPML traffic and diagnose problems.
As with SPML 1.0, you can enable tracing for SPML 2.0 when initializing the org.openspml.v2.transport.RPCRouterServlet class, which controls the output of RPC traffic information for the servlet handling SPML 2.0 requests.
To enable this tracing method, add the following to the WEB-INF/web.xml file:
<servlet> <servlet-name>openspmlRouter</servlet-name> <display-name>OpenSPML SOAP Router</display-name> <description>A router of RPC traffic - nominally SPML 2.0 over SOAP</description> <servlet-class> org.openspml.v2.transport.RPCRouterServlet </servlet-class> <init-param> <param-name>trace</param-name> <param-value>true</param-value> </init-param> ... </servlet> |
The following example illustrates output from an rpcrouter servlet trace:
RPCRouterServlet: <?xml version='1.0' encoding='UTF-8'?><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"><SOAP-ENV:Header/> <SOAP-ENV:Body><lookupRequest xmlns='urn:oasis:names:tc:SPML:2:0' requestID='random name' executionMode='synchronous' returnData='everything'> <openspml:operationalNameValuePair xmlns:openspml='urn:org:openspml:v2:util:xml' name=' session'value=session token'/> <psoID ID='random name' targetID='spml2-DSML-Target'/> </lookupRequest> </SOAP-ENV:Body></SOAP-ENV:Envelope> RPCRouterServlet: response: <?xml version='1.0' encoding='UTF-8'?> <SOAP-ENV:Envelope xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/'> <SOAP-ENV:Body> <lookupResponse xmlns='urn:oasis:names:tc:SPML:2:0' status='failure' requestID='random name'error='noSuchIdentifier'> <openspml:operationalNameValuePair xmlns:openspml='urn:org:openspml:v2:util:xml' name='session' value=session token/> <errorMessage>Item User:random name was not found in the repository, it may have been deleted in another session.</errorMessage> </lookupResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
For more information see Method 2: Initializing the org.openspml.server.SOAPRouter Servlet, in the To Enable Tracing for SPML 1.0 section.
SPML 2.0 has a simple text access log that can be a useful troubleshooting tool. This log is always available and it enables you to view information, such as what kind of requests have been received, how long it took to process those requests, and whether the requests were successful without having to enable tracing.
Instructions for configuring this SPML text access log are provided in Configuring SPML Tracing in Sun Identity Manager 8.1 Web Services
If a Scheduler task is having problems, you can use the standard tracing facility on com.waveset.task.Scheduler to trace the task scheduler. The output shows detailed information about task scheduling.
Open a browser and log in to the Administrator interface.
Select Configure -> Servers.
When the Configure Servers page displays, click the server name in the Server column to edit the settings.
On the Edit Server Settings page, click the Scheduler tab.
Select the Tracing Enabled box to activate Scheduler debug tracing and write the results to stdout.
Save your changes.
In a clustered environment, tracing occurs on each instance.
See Tracing the Identity Manager Server for more information about defining and editing trace configuration objects, and about viewing trace files.
Enabling workflow tracing can help you resolve problems with workflow activities and understand the workflow process.
In a clustered environment, tracing occurs on each instance.
To debug workflows in a multiple server deployment environment, consider shutting down all but one server. If all servers are running, you cannot determine which server in the environment is executing the workflow, which causes troubleshooting problems.
Use the following steps to enable workflow tracing:
Open a browser and log in to the Identity Manager Administrator interface.
From the System Setting page, choose Configuration from the List Objects Type menu.
Click the List Objects button.
When the List Objects of type: Configuration page displays, scroll down the list of objects to locate the System Configuration object and click the edit link.
When the Checkout Object: Configuration, #ID#CONFIGURATION:SYSTEMCONFIGURATION page displays, you can edit any of the following workflow options in the SystemConfiguration object:
Typically, you enable only one option, but it is possible to enable more than one option at a time.
These attributes are not dependent on each other. You can turn on one type of trace while the other types are turned off.
Specify workflow.consoleTrace=true to redirect workflow trace messages to the application server console, which can be useful when workflows are terminating due to a fatal exception because this attribute prints more trace output than workflow.fileTrace. (Default value is false.)
Specify workflow.fileTrace=PathtoFileto redirect workflow trace messages to a file that is easy to read. This attribute does not have a value by default.
<Attribute name=’fileTrace’/>
Add a value tag to the workflow.fileTrace attribute and, using Unix-style forward slashes, enter the path to a log file. Identity Manager stores relative pathnames relative to the application server’s installation directory. For example:
On Windows. <Attribute name=’fileTrace’ value=’C:\mydir\workflow.txt’/>
On Solaris/UNIX. <Attribute name=’fileTrace’ value=’/mydir/workflow.txt’/>
Specify workflow.traceLevel=tracingLevel to specify the level of workflow tracing you want to see.
Specify workflow.Trace=true to trace workflow processing. You must restart the application server to start tracing with this option. Identity Manager stores the trace results in the task’s WavesetResult object. Use this tracing option when file system access is unavailable. (Default value is false.)
Trace messages in the task’s WavesetResult. (Default value is 1.)
Specifying workflow.Trace=true appends trace messages into one long, unformatted string that is difficult to read. Use this option only when you do not have access to the file system.
With the first two options, you might lose some of the workflow trace if a fatal exception occurs.
Save the SystemConfiguration object.
Restart your application server, or reload the SystemConfiguration object from the Identity Manager debug area.
Use one of the following methods to enable tracing for a designated workflow:
Editing the WFProcess definition. To enable trace unconditionally for a particular process, edit the XML of the TaskDefinition object by adding the trace=’console ’ attribute to the <WFProcess> element.
Editing the workflow variable. Gives you more control over the timing of tracing by using a workflow variable. The workflow engine will look for a top-level workflow variable named trace.
The following example shows how to trace a workflow variable.
<Variable name=’trace’> <cond><eq><ref>accountId</ref><s>jfaux</s></eq> <s>workflowTrace.txt</s> </cond> </Variable> |
The trace variable turns tracing on only if the workflow is operating on a user named jfaux. You could also specify trace in a form field to control tracing interactively.
In this example, the trace output is written to the workflowTrace.txt file.
You can use one of the following methods to get information about the Identity Manager version you are currently using:
Hover your cursor above the Help button in the upper right corner of the Identity Manager application window. A pop-up is displayed that contains the version number.
Open the Waveset.properties file, and check the information provided at the top of the file.
Use the Identity Manager System Properties page (/debug/SysInfo.jsp) to get information about which JVM versions, and other system software versions, you are currently using.