C.2 Configuring Trace

You can configure trace on a driver set, driver, or the Remote Loader. Depending on the trace level specified for a driver, trace displays driver-related events when the engine processes the events. The driver trace level affects only the driver or driver set where trace is set. If you are using the Remote Loader, the Remote Loader trace file is set directly on the Remote Loader and contains only the driver shim trace.

C.2.1 Configuring Trace Levels

You can configure trace levels in Designer or iManager. To configure the trace in iManager, ensure that you have appropriate plug-ins for your version of Identity Manager and iManager. If you are using Remote Loader with a driver, configure the driver shim trace in the Remote Loader console. For more information, see Trace File Settings in Understanding the Configuration Parameters for the Remote Loader.

The following table describes the trace settings:

Table C-1 Trace Settings

Parameter	Driver	Driver Set
Trace level	As the driver trace level increases, the amount of information displayed in Trace increases. Trace level one shows errors, but not the cause of the errors. If you want to see password synchronization information, set the trace level to five. If you select Use setting from Driver Set, the value is taken from the driver set.	As the driver trace level increases, the amount of information displayed in Trace increases. Trace level one shows errors, but not the cause of the errors. If you want to see password synchronization information, set the trace level to five.
Trace file	Specify a file name and location of where the Identity Manager information is written for the selected driver. If you select Use setting from Driver Set, the value is taken from the driver set.	Not Applicable
XSL trace level	Not Applicable	Trace displays XSL events. Set this trace level only when troubleshooting XSL style sheets. If you do not want to see XSL information, set the level to zero
Java debug port	Not Applicable	Allows developers to attach a Java debugger. Restart the Identity Vault after attaching the Java debugger.
Trace file encoding	The trace file uses the system’s default encoding. You can specify another encoding if desired.	Not Applicable
Java trace file	Not Applicable	When a value is set in this field, all Java information for the driver set is written to a file. The value for this field is the patch for that file. As long as the file is specified, Java information is written to this file. If you do not need to debug Java, leave this field blank.
Trace file size limit	Allows you to set a limit for the Java trace file. If you set the file size to unlimited, the file grows in size until there is no disk space left. NOTE:If the file size limit is specified the trace file is created in multiple files. Identity Manager automatically divides the maximum file size by ten and creates ten separate files. The combined size of these files equals the maximum trace file size. If you select Use setting from Driver Set, the value is taken from the driver set.	Allows you to set a limit for the Java trace file. If you set the file size to unlimited, the file grows in size until there is no disk space left. NOTE:If the file size limit is specified the trace file is created in multiple files. Identity Manager automatically divides the maximum file size by ten and creates ten separate files. The combined size of these files equals the maximum trace file size.
Trace name	The driver trace messages are prepended with the value entered instead of the driver name. Use if the driver name is very long.	Not Applicable

Configuring Trace Settings in Designer

You can add trace levels to each driver or to the driver set:

Driver Trace

In an open project in Designer, select the driver in the Outline view.

Open your project in Designer.
Select the driver in the Outline view.
Right-click and select Properties, then click Trace.
Set the parameters for tracing, then click OK.

See Table C-1 for more information about the driver trace parameters.If you set the parameters only on the driver, information for only that driver appears in the trace log.

Driver Set Trace

Setting the trace level on the driver set creates very long traces that are hard to read. All events from all drivers are included in one trace file. If you are troubleshooting an issue, it is best to set the trace only on the driver you are troubleshooting.

Open your project in Designer.
Select the driver set in the Outline view.
Right-click and select Properties, then click Trace.
Set the parameters for tracing, then click OK.

See Table C-1 for more information about the driver set trace parameters.

If you set the trace level on the driver set, all drivers appear in the trace logs.

Configuring Trace Settings in iManager

You can set the trace levels to each driver or to the driver set.

Driver Trace

In iManager, open the Identity Manager Administration page.
Open the properties for the driver set that contains the driver you want to configure:
1. In the Administration list, click Identity Manager Overview.
2. If the driver set is not listed on the Driver Sets tab, use the Search In field to search for and display the driver set.
3. Click the driver set to open the Driver Set Overview page.
Locate the driver icon, then click the upper right corner of the driver icon to display the Actions menu.
Click Edit properties to display the driver’s properties page.
Select the Misc tab for the driver.
Set the parameters for tracing, then click OK.

For information about these parameters, see Table C-1.

Driver Set Trace

In iManager, open the Identity Manager Administration page.
Open the properties for the driver set whose parameters you want to configure:
1. In the Administration list, click Identity Manager Overview.
2. If the driver set is not listed on the Driver Sets tab, use the Search In field to search for and display the driver set.
3. Click the driver set to open the Driver Set Overview page.
4. Click the Driver Set menu, then click Edit Driver Set properties.
Select the Misc tab for the driver set.
Set the parameters for tracing, then click OK.

For information about these parameters, see Table C-1.

Configuring a Remote Loader Trace

You can capture the events that occur on the computer running the Remote Loader service by using one of the following methods:

Remote Loader Console

Launch the Remote Loader console by clicking the Remote Loader Console icon.
Select the driver instance, then click Edit.
Provide a value for Trace Level.
Specify a location and file for the trace file.
Specify the amount of disk space that the file is allowed.
Click OK twice to save the changes.

Command Line

You can enable tracing from the command line by using the switches in the following table:

Table C-2 Command Line Tracing Switches

Switch	Secondary Name	Parameter	Description
-trace	-t	integer	Specifies the trace level. This is used only when hosting an application shim. Trace levels correspond to those used on the Identity Manager server. Example: -trace 3 or -t3
-tracefile	-tf	filename	Specifies a file to write trace messages to. Trace messages are written to the file if the trace level is greater than zero. Trace messages are written to the file even if the trace window is not open. Example: -tracefile c:\temp\trace.txt or -tf c:\temp\trace.txt
-tracefilemax	-tfm	size	Specifies the approximate maximum size that trace file data can occupy on disk. If you specify this option, there is a trace file with the name specified using the tracefile option and up to 9 additional “roll-over” files. The roll-over files are named using the base of the main trace filename plus “_n”, where n is 1 through 9. The size parameter is the number of bytes. Specify the size by using the suffixes K, M, or G for kilobytes, megabytes, or gigabytes. If the trace file data is larger than the specified maximum when the Remote Loader is started, the trace file data remains larger than the specified maximum until roll-over is completed through all 10 files. Example: -tracefilemax 1000M or -tfm 1000M

Switch

Secondary Name

Parameter

Description

-trace

-t

integer

Specifies the trace level. This is used only when hosting an application shim. Trace levels correspond to those used on the Identity Manager server.

Example: -trace 3 or -t3

-tracefile

-tf

filename

Specifies a file to write trace messages to. Trace messages are written to the file if the trace level is greater than zero. Trace messages are written to the file even if the trace window is not open.

Example:

-tracefile c:\temp\trace.txt

-tf c:\temp\trace.txt

-tracefilemax

-tfm

size

Specifies the approximate maximum size that trace file data can occupy on disk. If you specify this option, there is a trace file with the name specified using the tracefile option and up to 9 additional “roll-over” files. The roll-over files are named using the base of the main trace filename plus “_n”, where n is 1 through 9.

The size parameter is the number of bytes. Specify the size by using the suffixes K, M, or G for kilobytes, megabytes, or gigabytes.

If the trace file data is larger than the specified maximum when the Remote Loader is started, the trace file data remains larger than the specified maximum until roll-over is completed through all 10 files.

Example: -tracefilemax 1000M or -tfm 1000M

C.2.2 Understanding the Trace Messages

The trace displays status and checkpoint messages about Identity Manager processes, XDS documents, DirXML Script, and engine processing.

Status Messages

These messages contain different information depending on the level the trace is set and where it is set. For example, you can trace the Identity Manager engine for data caching, read and write events to the Identity Vault, or logic processing. On the driver side, you can trace the driver shim communication with the connected system.

The engine trace levels range from 0 to 4. Each trace level shows all the status messages of the previous levels.

Engine Trace Level	Information Provided
0	Status messages only
1	Current location in the driver logic and status messages
2	Events in XML format, current location in the driver logic and status messages
3	Driver logic execution details and the DirXML Script, events in XML format, current location in the driver logic and status messages
4	Cache-related information about the event from the Identity Vault, driver logic execution details and the DirXML Script, events in XML format, current location in the driver logic and status messages

An Identity Manager engine trace set at level 3 and above shows all the steps performed by the engine while processing an event. It contains four basic types of messages.

Status	Description
success	Operation or event was successful
warning	Operation or event was partially successful
error	Operation or event failed
fatal	A fatal error occurred. The driver should be shut down
retry	Application server was unavailable. Send this event or operation later

Below are some sample status messages with a break-down of their structure:

Sample Success Status Message

[12/05/17 07:12:03.609]: SampleDriver ST:
DirXML Log Event -------------------
Driver: \LAB-TREE\Identity Managerorg\Driverset\SampleDriver
Channel: Subscriber
Object: \LAB-TREE\Identity Managerorg\users\sampleuser
Status: Success

The first line contains timestamp, the driver’s name, and the channel of the driver. ST specifies Subscriber channel.
The second line: “DirXML Log Event ——————-” is standard and can be used to search for status messages in a trace.
The third line lists the driver’s object location in the Identity Vault, using slash format for the dn of the driver.
The fourth line indicates the channel on which the event occurred. It is Subscriber in this example.
The fifth line indicates the object in the Identity Vault affected by the event, using slash format for the dn of the user.
The sixth line has a message describing the error. In most cases, the message is accompanied with an error code and/or a Java stack.

Sample Error Status Message

[12/05/17 07:13:01.790]: SampleDriver SST:
DirXML Log Event -------------------
Driver: \LAB-TREE\idmorg\Driverset\SampleDriver
Channel: Subscriber
Status: Error
Message: Code(-9075) Shutting down because DirXML engine evaluation period has expired

The first line contains timestamp, the driver’s name, and the channel of the driver. SST specifies Subscriber Service channel.
The second line: “DirXML Log Event ——————-” is standard and can be used to search for status messages in a trace.
The third line lists the driver’s object location in the Identity Vault, using slash format for the dn of the driver.
The fourth line indicates the channel on which the event occurred. It is Subscriber in this example.
The fifth line indicates that an error has occurred.
The sixth line contains a message describing the error. In most cases, the message is accompanied by an error code and may be followed by a Java stack.

For each processed event, Identity Manager generates a DirXML log event audit message in the trace. It sends the status messages to Publisher or Subscriber status log attributes and the auditing solution if the system is configured to send events to them. This message may appear before or after the XML in the trace.

Most of the engine troubleshooting such as driver startup and driver logic issues can be performed at level 3. The trace captured from a driver shim shows additional information. The driver shim trace levels range from 0 to 10, where the type and amount of information provided for the driver shim varies for each driver. For more information, see the specific driver implementation guide on the Identity Manager Drivers Documentation Website.For example, the default trace file on a connected Linux and UNIX system is located at /usr/local/nxdrv/logs/trace.log. A large amount of debugging information can be written to this file. The trace level setting in /etc/nxdrv.conf is used to control what is written to the file.

Checkpoint Messages

These are single line messages that indicate the stage of a process that is being executed. For example, a message that points where the engine is while executing the driver’s logic or interacting with the Identity Vault. For example,

[12/05/17 07:12:03.790]: SampleDriver ST: Start transaction.

The following table lists some of the checkpoint messages and their meaning:

Message	Meaning
Start transaction.	The Subscriber channel reads an Identity Vault event from Identity Manager engine’s event cache to process it.
No event transformation policies.	The driver’s logic does not have any event transformation policies to be processed.
Applying event transformation policies.	The logic contained in the driver’s event transformation policies will be executed after this message.
No object matching policies.	The driver’s logic does not have any object matching policies to be processed.
Applying object matching policies.	The logic contained in the driver’s object matching policies will be executed after this message.
No object creation policies.	The driver’s logic does not have any object creation policies to be processed.
Applying object creation policies.	The logic contained in the driver’s object creation policies will be executed after this message.
No object placement policies.	The driver’s logic does not have any object placement policies to be processed.
Applying object placement policies.	The logic contained in the driver’s object placement policies will be executed after this message.
No schema mapping policies to output.	The driver’s logic does not have any schema mapping policies to be processed when sending information to the connected system.
Applying schema mapping policies to output.	The logic contained in the driver’s schema mapping policies will be executed after this message.
No schema mapping policies to input.	The driver’s logic does not have any schema mapping policies to be processed when receiving information from the connected system.
Applying schema mapping policies to input.	The logic contained in the driver’s schema mapping policies will be executed after this message.
No command transformation policies.	The driver’s logic does not have any command transformation policies to be processed.
Applying command transformation policies.	The logic contained in the driver’s command transformation policies will be executed after this message.
No output transformation policies.	The driver’s logic does not have any output transformation policies to be processed.
Applying output transformation policies.	The logic contained in the driver’s output transformation policies will be executed after this message.
No input transformation policies.	The driver’s logic does not have any input transformation policies to be processed.
Applying input transformation policies.	The logic contained in the driver’s input transformation policies will be executed after this message.
Pumping XDS to the Identity Vault.	An event or query in XML format will be executed on the Identity Vault, and an XML document will be returned with either a status or a query result.
Stripping operation data from input document	Excludes the XML fragment that has <operation-data> as root from the XML document that is being sent to the driver shim.
Restoring operation data to output document	Reinserts the XML fragment that has <operation-data> as root in the response XML document from the driver shim. This XML fragment was saved before the XML document was sent to the driver shim.
End transaction.	The event initiated on the previous Start transaction is finished. Any status messages related to the event will be displayed before this message.
Receiving DOM document from application.	An event that occurred on the connected application is received on the Publisher channel.
Applying XSLT policy.	The StyleSheet (XSLT code) located at this point on the driver was executed on the event’s XML document.
Filtering out notification-only attributes.	Removes the attributes flagged as Notify in the driver’s filter for the channel being processed.
Fixing up association references.	Converts the values of the Identity Vault attributes with dn or path syntax (object references) to the name of the associated object on the connected system.
Resolving association references.	Converts the values of attributes with dn or path syntax (object references) from the associated connected system object to the equivalent Identity Vault object.
Applying publisher filter.	Allows the attributes or classes flagged as Synchronize on the Publisher channel filter to pass. If attributes or classes are flagged as Ignore, they are excluded from the current event. Additionally, attributes or classes that are not listed in the filter are excluded.

Policy Execution Messages

The trace displays messages that specify which operation is being evaluated against the driver’s logic. It specifies the policy, rule name, and the results of the evaluated rule’s conditions and actions. For example,

[12/05/17 07:54:02.250]: SampleDriver PT: Applying to add #1.

The following table lists some sample policy execution messages and their meaning:

Message	Meaning
Applying policy: %+C%14CEducation_Loan %-C.	The Identity Manager engine executes the logic contained in the policy named Education_Loan. The name of the policy is always within the delimiters %+C%14C and %-C, and matches the name of a policy in the driver’s logic.
Applying to operation #1.	The policy logic is applied to the operation listed. In this message, you will see one of the following strings: add add-association check-object-password check-password delete get-named-password init-params instance modify modify-association modify-password move password query query-schema remove-association rename schema-def status sync The number after the # sign is the position of that event within the <input> or <output> document, with number 1 being the first position.
Evaluating selection criteria for rule ‘Rule_Allow’.	Indicates that the conditions coded in the Rule_Allow rule are being evaluated. The name of the rule is contained within single quotes, and will match the name of a rule in your driver’s logic.
(if-operation equal “add”) = TRUE.	Specifies that the engine is evaluating if-operation equal “add” DirXML Script code. The value after equal to (=) specifies the outcome of evaluating the code, which can be TRUE or FALSE. This code is the result of the logic entered in the driver through Policy Builder (iManager or Designer). For more information about If operation, see If in NetIQ Identity Manager - Using Designer to Create Policies.
Rule rejected.	Specifies that the rule is rejected because the rule’s conditions were not completely met. Therefore, this rule’s actions will not be executed.
Rule selected.	Specifies that the rule’s conditions are met, so the rule’s actions will be executed.
Applying rule ‘Rule_Allow’.	Specifies that the actions included in the Rule_Allow rule will be executed. The name of the rule will always be within single quotes, and will match the name of a rule in your driver’s logic.
Action: do-strip-opattr(“nspmDistributionPass word”).	Indicates that the action after the colon sign (:) will be executed. To understand the details of this action, see NetIQ Identity Manager - Using Designer to Create Policies.

Below are sample Identity Manager engine trace messages logged at level 3 along with a brief explanation for each message.

Message	Meaning
[12/05/17 08:29:22.625]: Active Directory ST: Applying policy: %+C%14C'Transform NMAS attribute to password elements'%-C.	Specifies that the engine is processing a policy called Transform NMAS attribute to password elements.
[12/05/17 08:29:22.625]: Active Directory ST: Applying to modify #1.	Specifies that the engine is executing a modify object operation.
[12/05/17 08:29:22.625]: Active Directory ST: Evaluating selection criteria for rule 'Convert adds of the nspmDistributionPassword attribute to password elements'.	Specifies that the engine is processing Convert adds of the nspmDistributionPassword attribute to password elements rule.
[12/05/17 08:29:22.625]: Active Directory ST: (if-operation equal "add") = FALSE.	Specifies the condition contained in the rule has evaluated to FALSE.
[12/05/17 08:29:22.625]: Active Directory ST: Rule rejected.	Indicates that not all necessary conditions for the rule were met, so the rule will not be processed.
[12/05/17 08:29:22.625]: Active Directory ST: Evaluating selection criteria for rule 'Block modifies for failed password publish operations if reset password is false'.	Indicates that the rule being processed is Block modifies for failed password publish operations if reset password is false.
[12/05/17 08:29:22.640]: Active Directory ST: (if-global-variable 'reset-externalpassword-on-failure' equal "false") = FALSE.	Specifies the condition contained in the rule has evaluated to FALSE.
[12/05/17 08:29:22.640]: Active Directory ST: Rule rejected.	Indicates that not all necessary conditions for the rule were met, so the rule will not be processed.
[12/05/17 08:29:22.640]: Active Directory ST: Evaluating selection criteria for rule 'Convert modifies of a nspmDistributionPassword attribute to a modify password operation'.	Specifies that the rule being processed is Convert modifies of a nspmDistributionPassword attribute to a modify password operation.
[12/05/17 08:29:22.640]: Active Directory ST: (if-operation equal "modify") = TRUE.	Specifies the condition contained in the rule has evaluated to TRUE.
[12/05/17 08:29:22.640]: Active Directory ST: Rule selected.	Indicates that all necessary conditions for the rule were met, so the rule will be processed.
[12/05/17 08:29:22.640]: Active Directory ST: Applying rule 'Convert modifies of a nspmDistributionPassword attribute to a modify password operation'.	Specifies that the actions included in the Convert modifies of a nspmDistributionPassword attribute to a modify password operation rule will be executed.
[12/05/17 08:29:22.640]: Active Directory ST: Action: do-set-dest-password(token-xpath("modify-attr[@attr-name='nspmDistributionPassword']//add-value//value")).	Specifies the action that will be taken as part of executing the Convert modifies of a nspmDistributionPassword attribute to a modify password operation rule.
[12/05/17 08:29:22.656]: Active Directory ST: arg-string(token-xpath("modify-attr[@attrname='nspmDistributionPassword']//add-value//value"))	Specifies the action that will be taken as part of executing the Convert modifies of a nspmDistributionPassword attribute to a modify password operation rule.
[12/05/17 08:29:22.656]: Active Directory ST: token-xpath("modify-attr[@attrname='nspmDistributionPassword']//add-value//value")	Specifies the action that will be taken as part of executing the Convert modifies of a nspmDistributionPassword attribute to a modify password operation rule.
[12/05/17 08:29:22.656]: Active Directory ST: Token Value: "-- suppressed --".	Specifies the action that will be taken as part of executing the Convert modifies of a nspmDistributionPassword attribute to a modify password operation rule.
[12/05/17 08:29:22.656]: Active Directory ST: Arg Value: "-- suppressed --".	Specifies the action that will be taken as part of executing the Convert modifies of a nspmDistributionPassword attribute to a modify password operation rule.
[12/05/17 08:29:22.656]: Active Directory ST: Action: do-strip-opattr("nspmDistributionPassword").	Specifies the action that will be taken as part of executing the Convert modifies of a nspmDistributionPassword attribute to a modify password operation rule.
[12/05/17 08:29:22.656]: Active Directory ST: Action: do-set-xml-attr("eventid","../modify-password","pwd-subscribe").	Specifies the action that will be taken as part of executing the Convert modifies of a nspmDistributionPassword attribute to a modify password operation rule.
[12/05/17 08:29:22.656]: Active Directory ST: arg-string("pwd-subscribe")	Specifies the action that will be taken as part of executing the Convert modifies of a nspmDistributionPassword attribute to a modify password operation rule.
[12/05/17 08:29:22.656]: Active Directory ST: token-text("pwd-subscribe")	Specifies the action that will be taken as part of executing the Convert modifies of a nspmDistributionPassword attribute to a modify password operation rule.
[12/05/17 08:29:22.671]: Active Directory ST: Arg Value: "pwd-subscribe".	Specifies the action that will be taken as part of executing the Convert modifies of a nspmDistributionPassword attribute to a modify password operation rule.

Sample Trace Settings for Drivers

The following table describes sample driver trace settings and the information logged with those settings:

Identity Manager Driver	Engine Trace Level	Shim Trace Level	Description
Active Directory	3	3	Helps to troubleshoot when users do not synchronize. Note the username, location, and the system from the trace. Helps to troubleshoot when users synchronize in a single direction. You must perform the following actions to resolve the issue: Check the driver filters Check the placement policies in the appropriate channel Shim trace level 5 shows details about password synchronization.
Delimited Text	3	3	Helps to troubleshoot when users are not created in the Identity Vault. You must perform the following actions to resolve the issue: Check if the input directory exists and is properly entered in the driver configuration Check the filesystem rights and quotas on input directory and files Input CSV file is used to create the users Helps to troubleshoot when the driver does not write output files. You must perform the following actions to resolve the issue: Check if the output directory exists and is properly entered in the driver configuration Check the file system rights and quotas on output directory
eDirectory	3		The eDirectory driver works in pairs. The driver does not support Remote Loader. To troubleshoot any issues, ensure the following prerequisites are met: For the driver exports, ensure that you get both eDirectory driver exports. Ensure that both eDirectory drivers are imported in your Designer project.
Entitlements Service	5		This driver enables or disables entitlements on objects. To troubleshoot any issues, ensure that the following prerequisites are met: LDAP export of the entitlement policies is used in the driver set containing the driver This driver changes only the DirXML-EntitlementRef attribute on a user. Ensure that you obtain appropriate traces on the other drivers being affected by this change.
GroupWise	3	5	Helps to troubleshoot any issues when mail accounts are not created in GroupWise.
ID Provider			This is a service driver with which external clients can be accessed. Traces can be enabled in the driver and client parameters other than the regular Identity Manager tracing. The following information helps to analyze the cause of error and troubleshoot the driver: Document the issue in detail Obtain the ID driver export Get the LDAP export of the ID policy objects Obtain the XSLT / Java call made to the ID Provider service
JDBC	3	3	The following information helps to analyze the cause of error and troubleshoot the driver: Database name, vendor and patch level Operating System and patch level where the database is running Whether it is a supported Identity Manager/database combination Driver connection mode Schema of the target database A shim trace level of 5 shows information about SQL commands that are executed by the driver shim. Additional debugging information is shown with level 7.
JMS	3	3	Helps to troubleshoot any issues when messages are not sent or received from the JMS queue or application.
LDAP	3	5	Helps to troubleshoot any issue when users are not synchronizing between systems.
Linux and UNIX Settings	10		Helps to troubleshoot any issue when attributes are not added to the newly created users.
Linux and UNIX Bi-directional	3	4	Helps to troubleshoot any issues when a user is not created on the platform, or data is not correctly synchronizing after the user is created.
Loopback	3		Helps to troubleshoot any issues.
Lotus Notes	3	5	Helps to troubleshoot any issue.
Manual Task Service	5		Helps to troubleshoot any issue.
PeopleSoft 5.2	3	5	Helps to troubleshoot any issue other than the connectivity issue.
Salesforce	3	5	Helps to troubleshoot any issues.
SAP HR	3	5	Helps to troubleshoot issues when objects are not synchronized to SAP.
SAP User Management	3	5	Helps to troubleshoot any issue other than the connectivity issue.
SOAP	3	5	Helps to troubleshoot connectivity issues with the SOAP system. Engine trace level 3 helps to troubleshoot any issues.
WorkOrder	3	5	Helps to troubleshoot any issues.