12.1 Troubleshooting Driver Processes

Viewing driver processes is necessary to analyze unexpected behavior. To view the driver processing events, use DSTRACE. You should only use it during testing and troubleshooting the driver. Running DSTRACE while the drivers are in production increases the utilization on the Identity Manager server and can cause events to process very slowly.

12.1.1 Viewing Driver Processes

In order to see the driver processes in DSTRACE, values are added to the driver set and the driver objects. You can do this in Designer and iManager.

Adding Trace Levels in Designer

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

Driver Set

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

    Selecting the Driver Set object

  2. Right-click and select Properties, then click 5. Trace.

  3. Set the parameters for tracing, then click OK.

    Parameter

    Description

    Driver trace level

    As the driver object trace level increases, the amount of information displayed in DSTRACE increases.

    Trace level 1 shows errors, but not the cause of the errors. If you want to see password synchronization information, set the trace level to 5.

    XSL trace level

    DSTRACE 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

    Allows developers to attach a Java* debugger.

    Java trace file

    When a value is set in this field, all Java information for the driver set object is written to a file. The value for this field is the path 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.

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

Driver

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

  2. Right-click and select Properties, then click 8. Trace.

  3. Set the parameters for tracing, then click OK.

    Parameter

    Description

    Trace level

    As the driver object trace level increases, the amount of information displayed in DSTRACE increases.

    Trace level 1 shows errors, but not the cause of the errors. If you want to see password synchronization information, set the trace level to 5.

    if you select Use setting from Driver Set, the value is taken from the driver set object.

    Trace file

    Specify a filename and location for 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 object.

    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.

    If you select Use setting from Driver Set, the value is taken from the driver set object.

    Trace name

    The driver trace messages are prepended with the value entered instead of the driver name. Use this option if the driver name is very long.

    If you set the parameters only on the driver object, only information for that driver appears in the DSTRACE log.

Adding Trace Levels in iManager

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

Driver Set

  1. In iManager, select Identity Manager > Identity Manager Overview.

  2. Browse to the driver set object, then click Search.

  3. Click the driver set name.

    Selecting Driver Set object

  4. Select the Misc tab for the driver set object.

  5. Set the parameters for tracing, then click OK.

Driver

  1. In iManager, select Identity Manager > Identity Manager Overview.

  2. Browse to the driver set object where the driver object resides, then click Search.

  3. Click the upper right corner of the driver object, then click Edit properties.

  4. Select the Misc tab for the driver object.

  5. Set the parameters for tracing, then click OK.

    The option Use setting from Driver Set does not exist in iManager.

Capturing Driver Processes to a File

You can save driver processes to a file by using the parameter on the driver object or by using DSTRACE. The parameter on the driver object is the Trace file parameter, under the MISC tab.

The driver processed that are captured through DSTRACE are the processes that occur on the Identity Manager engine. If you use the Remote Loader, you need to capture a trace on the Remote Loader at the same time as you are capturing the trace on the Identity Manager engine.

The following methods helps you capture and save Identity Manager processes through DSTRACE on different platforms.

NetWare

Use dstrace.nlm to display trace messages on the system console or trace messages to a file (sys:\system\dstrace.log). Use dstrace.nlm to display the trace messages to a screen labeled DSTrace Console.

  1. Enter dstrace.nlm at the server console to load dstrace.nlm into memory.

  2. Enter dstrace screen on at the server console to allow trace messages to appear on the DSTrace Console screen.

  3. Enter dstrace file on at the server console to capture trace messages sent to the DSTrace Console to the dstrace.log file.

  4. (Optional) Enter dstrace -all at the server console to make it easier to read the trace log.

  5. Enter dstrace +dxml dstrace +dvrs at the server console to display Identity Manager events.

  6. Enter dstrace +tags dstrace +time at the server console to display message tags and time stamps.

  7. Toggle to the DSTrace Console screen and watch for the event to pass.

  8. Toggle back to the server console.

  9. Enter dstrace file off at the server console.

    This stops capturing trace messages to the log file. It also stops logging information into the file.

  10. Open the dstrace.log in a text editor and search for the event or the object you modified.

Windows

  1. Open the Control Panel > NDS Services > dstrace.dlm, then click Start to display the NDS Server Trace utility window.

  2. Click Edit > Options, then click Clear All to clear all of the default flags.

  3. Select DirXML and DirXML Drivers.

  4. Click OK.

  5. Click File > New.

  6. Specify the filename and location where you want the DSTRACE information saved, then click Open.

  7. Wait for the event to occur.

  8. Click File > Close.

    This stops the information from being written to the log file.

  9. Open the file in a text editor and search for the event or the object you modified.

UNIX

  1. Enter ndstrace to start the ndstrace utility.

  2. Enter set ndstrace=nodebug to turn off all trace flags currently set.

  3. Enter set ndstrace on to display trace messages to the console.

  4. Enter set ndstrace file on to capture trace messages to the ndstrace.log file in the directory where eDirectory is installed. By default it is /var/nds.

  5. Enter set ndstrace=+dxml to display the Identity Manager events.

  6. Enter set ndstrace=+dvrs to display the Identity Manager driver events.

  7. Wait for the event to occur.

  8. Enter set ndstrace file off to stop logging information to the file.

  9. Enter exit to quite the ndstrace utility.

  10. Open the file in a text editor. Search for the event or the object that was modified.

iMonitor

iMonitor allows you to get DSTRACE information from a Web browser. It does not matter where Identity Manager is running. The following files run iMonitor:

  • ndsimon.nlm runs on NetWare®.

  • ndsimon.dlm runs on Windows.

  • ndsimonitor runs on UNIX.

  1. Access iMonitor from http://server_ip:8008/nds.

    Port 8008 is the default.

  2. Specify a username and password with administrative rights, then click Login.

  3. Select Trace Configuration on the left side.

  4. Click Clear All.

  5. Select DirXML and DirXML Drivers.

  6. Click Trace On.

  7. Select Trace History on the left side.

  8. Click the document with the Modification Time of Current to see a live trace.

  9. Change the Refresh Interval if you want to see information more often.

  10. Select Trace Configuration on the left side, then click Trace Off to turn the tracing off.

  11. Select Trace History to view the trace history.

    The files are distinguished by their time stamp.

If you need a copy of the HTML file, the default location is:

  • NetWare: sys:\system\ndsimon\dstrace*.htm

  • Windows: Drive_letter:\novell\nds\ndsimon\dstrace\*.htm

  • UNIX: /var/nds/dstrace/*.htm

Remote Loader

You can capture the events that occur on the machine by running the Remote Loader service.

  1. Launch the Remote Loader Console by clicking the icon.

  2. Select the driver instance, then click Edit.

  3. Set the Trace Level to 3 or above.

  4. Specify a location and file for the trace file.

  5. Specify the amount of disk space that the file is allowed.

  6. Click OK, twice to save the changes.

You can also enable tracing from the command line by using the switches in table Table 12-1. For more information, see Configuring the Remote Loader in the Novell Identity Manager 3.5.1 Administration Guide.

Table 12-1 Command Line Tracing Switches

Option

Short Name

Parameter

Description

-trace

-t

integer

Specifies the trace level. This is only used 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