Tracing Waveset Objects and Activities

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 Waveset objects and activities. The information is organized as follows:

• How To Configure Tracing

• How to View Trace Files

• Tracing the Waveset Server

• Tracing Adapters

• Tracing Custom Code

• Tracing Exceptions

• Tracing Forms

• Tracing Global XPRESS

• Tracing PasswordSync

• Tracing Oracle Waveset Service Provider Delegated Administration

• Tracing Reconciliation

• Tracing the setRepo Command

• Tracing SPML

• Tracing the Task Scheduler

• Tracing Workflows

• Locating Version Information

Tracing affects system performance. To ensure optimal performance, specify the minimum tracing level or turn tracing off after debugging the system.

How To Configure Tracing

This section describes how to enable and configure tracing from several locations within Waveset. Instructions are organized as follows:

• To Enable Tracing from the System Settings Page

• To Edit the Default Configuration Object

• To Create a New Trace Configuration Object

• To Configure Tracing From Individual Debug Pages

• To Enable Tracing From the Waveset Console

• To View Sensitive Data in the Trace Output

To Enable Tracing from the System Settings Page

The System Settings page is the primary Waveset 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 Waveset System Settings page:

1. Open a browser and log in to the Waveset Administrative interface.

2. Type the following URL:

   http://hostport/idm/debug

   where:

   • host is the local server on which you are running Waveset.

   • port is the number of the TCP port on which the server is listening.

3. 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.

   ---

   Note –

   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.

   Waveset supplies one configuration, called Global, by default. However, if you have multiple servers in an Waveset 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.

   ---

Next Steps

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:

• To Edit the Default Configuration Object

• To Create a New Trace Configuration Object

To Edit the Default Configuration Object

1. From the Edit Trace Configuration page, click the Trace Enabled box to enable tracing.

   ---

   Note –

   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.

   ---

2. 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.

3. 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

   ---

   Note –

   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.

   ---

4. (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.

   ---

   Note –

   • 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.

5. 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

6. Specify the maximum number of trace files to store (default is 2).

7. Specify the maximum size for each file (default is 512K).

8. 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).

9. Save your changes.

To Create a New Trace Configuration Object

Use the following steps to create a new trace configuration object:

1. 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.

2. Log in to the Waveset Administrator interface and open the System Settings page as described in To Enable Tracing from the System Settings Page.

3. On the Systems Setting page, click Show Trace List.

4. When the Waveset Trace Configuration page displays, click New.

5. 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.

6. 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.

7. Save your changes.

To Configure Tracing From Individual Debug Pages

This section describes how to enable tracing from an Waveset Debug page.

1. Open a browser and log in to the Waveset Administrative interface.

2. Type the following URL:

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

   where:

   • host is the local server on which you are running Waveset.

   • 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

To Enable Tracing From the Waveset Console

This section explains how to enable tracing from the Waveset console.

1. Set $WSHOME.

   For example, to set the variable to the default installation directory:

   set WSHOME=C:\Program Files\tomcat\webapps\idm

2. Type lh console to open the Waveset console from the bin directory.

3. 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

To View Sensitive Data in the Trace Output

By default, Waveset “sanitizes” trace information by replacing each occurrence of sensitive data with a single asterisk. Sensitive data includes any data that is inbound to encryption methods, outbound from decryption methods, and cipher-related metadata such as data lengths, padding lengths, and so forth. However, you can configure a property in the Waveset.properties file to include this information in your trace output for debugging purposes.

Use the following steps to enable sensitive cipher data in your trace logs:

1. From a command line, open the Waveset.properties file.

2. Locate the cipher.data.trace property file comments, and uncomment the following line:

   cipher.data.trace=true

3. Restart your server for this change to take effect.

How to View Trace Files

By default, Waveset 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.

Tracing the Waveset Server

Waveset 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 Waveset server can provide helpful information such as where a server is failing, having problems, or not running. You can use the Waveset Debug pages to enable package-level and method-level tracing in a running Waveset server.

Configure Waveset to trace at this advanced level only if instructed by Oracle Support.

Tracing Adapters

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:

• General Notes About Tracing Adapters

• Instrumenting Code with Trace Points

• Other Tracing Guidelines

General Notes About Tracing Adapters

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 Active Sync adapter. Instructions are provided in the Waveset 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 Oracle Waveset 8.1.1 Resources Reference.

• The following tasks were moved from the adapter to the task package in Identity Manager version 8.0. You must update the paths if you have tracing enabled for any of these tasks, or if you have customized task definitions referencing these packages.

  Old Package Name	New Package Name
  com.waveset.adapter.ADSyncFailoverTask	com.waveset.task.ADSyncFailoverTask
  com.waveset.adapter.ADSyncRecoveryCollectorTask	com.waveset.task.ADSyncRecoveryCollectorTask
  com.waveset.adapter.SARunner	com.waveset.task.SARunner
  com.waveset.adapter.SourceAdapterTask	com.waveset.task.SourceAdapterTask

Instrumenting Code with Trace Points

The Waveset 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.

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 Waveset 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.

  ---

  Note –

  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.

• Using Entry and Exit Trace Points

• Using Information Trace Points

• Using Exception Trace Points

• Using Trace Point Templates

Using Entry and Exit Trace Points

Consider these guidelines before adding entry and exit trace points to your code:

• Use Trace.Level1 entry or exit trace points for all Waveset 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 Waveset 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();

Example 5–1 Entry Trace Point Example

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());
}

Example 5–2 Exit Trace Point Example

_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()); 
}

Using Information Trace Points

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();

Example 5–3 Information Trace Point Example

_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); 
}

Using Exception Trace Points

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. Waveset 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 Waveset 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();

Example 5–4 Exception Trace Point Example

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

Using trace point templates can help you provide consistent and useful trace points in Waveset resource adapters. Waveset 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.

Other Tracing Guidelines

This section describes some additional tracing guidelines, including the following:

• Tracing Inner Classes

• Tracing Static Initializers

Tracing Inner Classes

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.

Example 5–5 Example of Using a CLASS Variable in Inner Classes

private final static String CLASS = 
com.waveset.adapter.SomeResourceAdapter$AdapterInnerClass;

Tracing Static Initializers

In general, do not use the trace facility in static initializers. Waveset 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.

Tracing Auditor

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.

To Enable Tracing:

1. Open a browser and log in to the Administrator interface.

2. Select Configure -> Servers.

3. When the Configure Servers page displays, click the server name in the Server column to edit the settings.

4. On the Edit Server Settings page, click the Scheduler tab.

5. Select the Tracing Enabled box to activate Scheduler debug tracing and write the results to stdout.

6. Save your changes.

Tracing Custom Code

You can use the Waveset 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 Javadoc for more information about these facilities and classes.

Be aware that the com.sun.idm.logging.trace facilities were not available prior to the Waveset Version 6.0 SP1 release. For earlier versions of Waveset, you must use the com.waveset.util.Trace class instead.

Tracing Exceptions

Exception logs are stack traces that you can view from the Waveset 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 Waveset 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.

  

Waveset 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.

Tracing Forms

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 Waveset 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.

Waveset 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

• Tracing Global XPRESS

• Testing Your Customized Form in Oracle Waveset 8.1.1 Deployment Reference

Tracing Global XPRESS

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 Oracle Waveset 8.1.1 Deployment Reference for more information about tracing XPRESS functions.

To Enable Global XPRESS Tracing:

1. Open a command window.

2. Change directories to config/Waveset.properties in the default Waveset installation directory.

3. Open the config/Waveset.properties file and edit the xpress.trace line to read:

   xpress.trace=true

4. Save the Waveset.properties file.

5. Restart your application server or reload the Waveset.properties file from the Waveset debug pages.

6. 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.

Tracing PasswordSync

This section describes how to enable tracing for PasswordSync and how to configure tracing in Direct access or JMS modes.

To Enable Trace for PasswordSync

You can use the following methods to configure tracing for Waveset’s PasswordSync feature:

• Using the PasswordSync Configuration Tool

• Editing the Registry Keys

Using the PasswordSync Configuration Tool

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 Oracle Waveset 8.1.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.

Figure 5–2 Trace Tab in the PasswordSync Configuration Tool

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.

Editing the Registry Keys

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.

The PasswordSync registry keys are located in the following location:

HKEY_LOCAL_MACHINE\SOFTWARE\Sun Microsystems\Sun Identity Manager\Passwordsync

Other keys are present in this location.

To Collect Logs for the Different Modes

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.

Tracing in Direct Mode

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.

Tracing in JMS Mode

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 can provide 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 Oracle Waveset 8.1.1 Resources Reference for instructions.

Tracing Rule-Driven Members Caches

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, Waveset 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, Waveset adds that object to the list and then caches the list. Waveset 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.

Tracing Oracle Waveset Service Provider Delegated Administration

Enabling Waveset tracing at Method/Class Level 2 for the following classes allows you to trace authorization flows when listing or accessing Oracle Waveset 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 Waveset debug pages. If necessary, review Tracing the Waveset Server for instructions.

Tracing Reconciliation

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 Waveset 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.

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.

Tracing the setRepo Command

If you see errors while you are using the setRepo command to configure the Waveset 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

Waveset sends output from the setRepo command to the default $WSHOME/config/WSTrace.log file.

Tracing SPML

This section describes methods for enabling trace for SPML Version 1.0 and SPML Version 2.0.

To Enable Tracing for SPML 1.0

SPML 1.0 contains the following options for turning on trace output so you can log Waveset’s SPML traffic and diagnose problems.

Method 1: Enable the setTrace Method

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);

Method 2: Initializing the org.openspml.server.SOAPRouter Servlet

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.

Method 3: Pass the trace Operational Attribute

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, Waveset 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.

To Enable Tracing for SPML 2.0

SPML 2.0 contains the following options for turning on trace output so you can log Waveset’s SPML traffic and diagnose problems.

Method 1: Using the org.openspml.v2.transport.RPCRouterServlet Servlet

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.

Method 2: Using the SPML Access Log

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 Oracle Waveset 8.1.1 Web Services

Tracing the Task Scheduler

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.

To Enable Tracing:

1. Open a browser and log in to the Administrator interface.

2. Select Configure -> Servers.

3. When the Configure Servers page displays, click the server name in the Server column to edit the settings.

4. On the Edit Server Settings page, click the Scheduler tab.

5. Select the Tracing Enabled box to activate Scheduler debug tracing and write the results to stdout.

6. Save your changes.

   ---

   Note –

   • In a clustered environment, tracing occurs on each instance.

   • See Tracing the Waveset Server for more information about defining and editing trace configuration objects, and about viewing trace files.

   ---

Tracing Workflows

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.

To Enable Tracing for Workflows

Use the following steps to enable workflow tracing:

To Enable Workflow Tracing:

1. Open a browser and log in to the Waveset Administrator interface.

2. From the System Setting page, choose Configuration from the List Objects Type menu.

3. Click the List Objects button.

4. 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.

5. When the Checkout Object: Configuration, #ID#CONFIGURATION:SYSTEMCONFIGURATION page displays, you can edit any of the following workflow options in the SystemConfiguration object:

   ---

   Note –

   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. Waveset 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. Waveset 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.

   ---

   Note –

   With the first two options, you might lose some of the workflow trace if a fatal exception occurs.

   ---

6. Save the SystemConfiguration object.

7. Restart your application server, or reload the SystemConfiguration object from the Waveset debug area.

To Enable Tracing for a Designated Workflow

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.

Example 5–6 Tracing 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.

Locating Version Information

You can use one of the following methods to get information about the Waveset version you are currently using:

• Hover your cursor above the Help button in the upper right corner of the Waveset 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 Waveset System Properties page (/debug/SysInfo.jsp) to get information about which JVM versions, and other system software versions, you are currently using.