Introduction

ADInsight
Copyright © 2007 Mark Russinovich and Bryce Cogswell
Sysinternals - www.sysinternals.com

ADInsight is an advanced monitoring tool for Windows that shows real-time file client-side Active Directory (LDAP - Light-weight Directory Access Protocol) activity. Using ADInsight, you can troubleshoot permissions, performance, and configuration issues that affect AD-enabled applications, such as Exchange and SQL Server.

ADInsight uses DLL injection techniques to intercept calls that applications make in the Wldap32.dll library, which is the standard library underlying Active Directory APIs such ldap and ADSI. Unlike network monitoring tools, ADInsight intercepts and interprets all client-side APIs, including those that do not result in transmission to a server. ADInsight monitors any process into which it can load it’s tracing DLL, which means that it does not require administrative permissions, however, if run with administrative rights, it will also monitor system processes, including windows services.

ADInsight runs on Windows 2000, Windows XP, Windows Vista, Windows Server 2003, and Windows Server 2008.


Capturing Events

To toggle capture mode on and off, click the Capture toolbar button, choose Capture Events from the File menu, or press Ctrl+E. No data is collected when capture mode is off.

Note

By default events are captured when a new connection is made. To change the default capture mode choose Preferences from the Options menu and clear Automatically start to capture after connection.


Copying an Event

To copy a selected event to the Clipboard, chose Copy from the Edit menu or press Ctrl+C.


Finding Text

To search for an occurrence of text in the Event Pane, click the Find toolbar button, choose Find on the Edit menu, or press Ctrl+F. This action opens the Find dialog box.

Find Dialog Box

If the text you entered is found in the Event Pane, the matching event will be selected and Auto Scroll will be turned off to keep the line in the window.

  • To repeat a search down the event list press the F3 shortcut key.

  • To repeat a search up the event list press the Shift+F3 shortcut key.

Note

You can search only in columns that are visible in the Event Pane. To set the column display, choose Select Columns from the Options menu or from the context menu that appears when you right-click on an item.


Clearing the Display

To clear the Event Pane, click the Clear toolbar button or choose Clear Display from the Edit menu.

This action resets the sequence number to 0; it also resets the values displayed in the Time column if relative time is selected.


Filtering the Display

To display or hide processes whose names contain specified text substrings, or to add or exclude selected LDAP transactions, click the Filter toolbar button, choose Event Filter from the View menu, or press Ctrl+L.

This action opens the Event Filters dialog box.

Event Filters Dialog Box

  • To view only processes whose names contain specified substrings, type the text expression in the Include list.

  • To exclude processes whose names contain specified substrings, type the text expression in the Exclude list.

Using Filter Expressions

  • You can enter multiple expressions by separating each expression with a semicolon (;).

  • Use the Asterisks (*) as a wildcard character.

  • Do not include spaces in the expression unless you want the spaces to be part of the filter.

  • Filter expressions are a case insensitive.

Selecting Displayed Transactions

  • To hide selected LDAP transactions, clear the corresponding check boxes.

  • To display events not commonly used for troubleshooting and configuration select Show Advanced Events.

To reset the Include and Exclude expressions and select the default LDAP transaction check boxes, click Reset to Default.

Notes

  • Changes in the Event Filters dialog box do not affect items already in the display.

  • When you start Insight for Active Directory with a Process Filter applied from a previous session, the Event Filters dialog box will open to confirm your filter settings. To start the console without opening the Filter dialog box, add the -q parameter to your startup command.


Highlighting Events

To set display highlighting properties, choose Highlight Preferences on the Highlight menu or from the context menu that appears when you right-click on an item in the Event Pane.

This action opens the Event Highlighting dialog box.

Event Highlighting Dialog Box

  • To highlight events in the same session handle as the selected item, click Sessions.

  • To highlight events with the same event handle as the selected item, click Related Items.

  • To highlight events whose process names contain specified text substrings, click Processes and type the text expression in the Process Name Filter list. Filter expression rules apply to text in the Process Name Filter.

  • To highlight events with errors, click Error Result.

  • To highlight events with Result Times that are longer than a specified time, click Highlight Events that take longer than and type the time in seconds.

To change a highlight color, click the Color button corresponding to the highlight option. This action opens the Highlight Color dialog box.

To toggle all highlighting on and off, choose Enable Highlighting on the Highlighting menu.

Note

The Next and Prev toolbar buttons are disabled when highlighting is disabled or Error Result is not selected.


Finding Event Errors

To go to the next error in the Event Pane, click the Next toolbar button or choose Next Event Error from the context menu that appears when you right-click on an item in the Event Pane.

To go to the previous error in the Event Pane, click the Prev toolbar button or choose Previous Event Error from the context menu that appears when you right-click on an item in the Event Pane.

Note

The Next and Prev toolbar buttons are disabled when highlighting is off, when Error Result in the Event Highlighting dialog box is not selected, or when no item is selected in the Event Pane.


Viewing Related Events

To view a list of events with the same event handle as the selected item, choose View Related Events on the View menu or on the context menu that appears when you right-click on the item.

This action opens the Related Transaction Events window.

Related Transaction Events Window

Note

Columns that appear in the window correspond to the columns visible in the Event Pane. To add or remove columns, choose Select Columns from the Options menu or from the context menu that appears when you right-click on an item.


Viewing Related Session Events

To view a list of events with the same LDAP session handle as the selected item, choose View Session Events on the View menu or on the context menu that appears when you right-click on the item.

This action opens the Related Session Events window.

Related Session Events Window

Note

Columns that appear in the window correspond to the columns visible in the Event Pane. To add or remove columns, choose Select Columns from the Options menu or from the context menu that appears when you right-click on an item.


Viewing Process Information

To view information about the process making an LDAP call, choose Process Information from the context menu that appears when you right-click on an item in the Event Pane.

This action opens the Process Information window.

Process Information Window


Viewing Event Information

To view summary information about an LDAP function that appears in the Request column, double-click an item in the Event Pane or choose Event Information from the context menu that appears when you right-click.

This action opens a pop-up dialog box that displays the full name and description of the function.

To view detailed diagnostic information about the LDAP function, click the More Info hyperlink. This action opens a browser window with information from the MSDN Library Web site.


Setting Time Display Options

To toggle the Time column display between clock time and relative time, choose Clock Time from the Options menu or press Ctrl+T.

  • When clock time is selected you can toggle the Time column display to show or hide milliseconds by choosing Show Milliseconds from the Options menu.

  • You can toggle the number of decimal places displayed in the Time and Duration columns by choosing Show Simple Time from the Options menu. Simple time is displayed in the Time column only when relative time is selected.


Setting Auto Scroll

By default the display scrolls to automatically show new activity.

To toggle Auto Scroll off and on, click the Scroll toolbar button, choose Auto Scroll on the View menu or press Ctrl+A.

Note

Turning off Auto Scroll temporarily sets the History Depth to an unlimited number of lines so that new items will continue to appear in the display.


Setting History Depth

By default older lines are discarded from the event list to stay within a specified History depth. To change History depth, click the History toolbar button, choose History Depth on the View menu, or press Ctrl+H.

This action opens the Event List History Depth dialog box.

Event History Depth Dialog Box

  • Type or select a new value in the History Depth box or click Default to restore the default value of 50,000 lines.

  • Type or select 0 in the History Depth box to retain an unlimited number of lines in the display.

Note

Turning off Auto Scroll temporarily sets the History Depth to an unlimited number of lines so that new items will continue to appear in the display.


Setting the Column Display

To select the columns that appear in the display, choose Select Columns from the Options menu or from the context menu that appears when you right-click on an item in the Event Pane.

This action opens the Select Columns dialog box.

Select Columns Dialog Box

You can choose any of the following columns to appear in the Event Pane:

Sequence Number | the unique sequence number assigned to an event; gaps in sequence numbers may indicate buffer overflow resulting from heavy activity or filtering that prevents some items from appearing in the display
Time | the time that the event occurred
Process | the name of the process making the LDAP call to the Active Directory
Request | the name of the LDAP function call
Type | whether the LDAP call is synchronous or asynchronous
Session | the LDAP session handle
Event ID | the LDAP event handle
Input | the value passed from the Process to the Active Directory
Output | the value passed to the Process from the Active Directory
Result | the Result code returned by the function; Success results are not displayed unless you clear Suppress Success Status on the Options menu
Duration | the elapsed time between the call and the result

You can choose any of the following columns to appear in the Details Pane:

Parameter | the parameter names for the selected LDAP call
In/Out | whether the parameter is being sent or received by the application
Value | the value passed to or from the process making the LDAP call


Setting Other Display Options

  • To change the font size of items in the display, choose Font on the Options menu.

  • Choose Always on Top to keep the window displayed when you switch programs or windows.

  • To toggle the Request column between full and simple LDAP function names, click Show Simple Event Name on the Options menu. Examples of full and simple LDAP function names are:

Full Name | ldap_get_values_len
Simple Name | get values length

  • To toggle the display between distinguished and simple names, click Show Distinguished Name Format on the Options menu. Examples of equivalent distinguished and simple names are:

Distinguished Name | CN=RCHASE-2K3,CN=Computers,DC=OA,DC=Denver,DC=Addesinc,DC=com
Simple Name | OA.Denver.Addesinc.com\Computers\RCHASE-2K3

  • To toggle the display of LDAP filter strings in the Input column and Details Pane between simple format (i.e., prefix notation) and standard format (i.e., infix notation), click Show Simple LDAP Filters on the Options menu. Examples of equivalent simple and standard format filter strings are:

Simple Format | (( NOT((showInAdvancedViewOnly=TRUE)) AND (samAccountType=805306368)) AND ((name=rchase-2k3*) OR (sAMAccountName=rchase-2k3*)))
Standard Format | (&(&(!(showInAdvancedViewOnly=TRUE))(samAccountType=805306368)) (|(name=rchase-2k3*) (sAMAccountName=rchase-2k3*)))

  • To toggle off and on the display of Success status in the Result column, click Suppress Success Status from the Options menu.


Command-Line Options

You can use command-line parameters to set console startup options and to launch the monitoring service from a batch file or command window.

Syntax

adinsight [-q] [-o] [-log FileName] [-fi IncludeString] [-fe ExcludeString] [[-u UserName –p Password] -r ComputerName]...

Parameters

–q

Starts the console without opening the Filter dialog box. By default the Filter dialog box opens at startup if any filters are applied.

–o

Turns off event capture.

-log FileName

Writes activity to a log file without opening the console, where FileName is the name of the output file.

–fi

Specifies an Include string for the Filter. Filter expression rules apply to the IncludeString text.

–fe

Specifies an Exclude string for the Filter. Filter expression rules apply to the ExcludeString text.

-?

Displays help at the command prompt.


Saving Output

To save the contents of the Event Pane as a text file, choose Save on the File menu or press the Ctrl+S shortcut key.

To copy the selected item to the Clipboard, chose Copy from the Edit menu or press the Ctrl+C shortcut key.

Note

You can also save the contents of the Event Pane as HTML formatted reports.


Logging to a File

You can use the command-line -log option to write activity to a log file without opening the console.


Viewing Event Reports

To view a report of all items in the Event Pane, choose Events from the HTML Reports submenu of the View menu.

This action opens an HTML-formatted report in your Web browser window.

To view detailed diagnostic information about an LDAP function in the Request column, click the hyperlink. To save the contents of the report, choose Save As from the File menu of your browser window.

Note

Columns that appear in the report correspond to the columns visible in the Event Pane. To add or remove columns, choose Select Columns from the Options menu or from the context menu that appears when you right-click on an item.


Viewing Events with Details

To view a report of all items in the Event Pane with corresponding Details Panes, choose Events with Details from the HTML Reports submenu of the View menu.

This action opens an HTML-formatted report in your Web browser window.

Events with Details Report

To view detailed information about an LDAP function in the Request column, click the hyperlink. To save the contents of the report, choose Save As from the File menu of your browser window.

Note

Columns that appear in the report correspond to the columns visible in the Event Pane. To add or remove columns, choose Select Columns from the Options menu or from the context menu that appears when you right-click on an item.


Viewing Events with Time Results

To view a histogram report of LDAP calls in the Event Pane with Total Time, Longest Time, and Average Time statistics, choose Event Time Results from the HTML Reports submenu of the View menu.

This action opens an HTML-formatted report in your Web browser window.

Events with Time Results Report

To view detailed information about an LDAP function, click the hyperlink. To save the contents of the report, choose Save As from the File menu of your browser window.

Note

To display uncalled functions, choose Preferences from the Options menu and clear Suppress uncalled functions in reports.


Viewing Highlighted Events

To view a report of highlighted entries in the Event Pane, choose Highlighted Events from the HTML Reports submenu of the View menu.

This action opens an HTML-formatted report in your Web browser window.

Highlighted Events Report

To view detailed information about an LDAP function in the Request column, click the hyperlink. To save the contents of the report, choose Save As from the File menu of your browser window.

Note

Columns that appear in the report correspond to the columns visible in the Event Pane. To add or remove columns, choose Select Columns from the Options menu or from the context menu that appears when you right-click on an item.


Change Color Highlighting

You can set color highlighting properties of the display by choosing Highlight Preferences from the Highlight menu or from the context menu that appears when you right-click on an item in the Event Pane.


Display Only Selected Events

You can display or hide processes whose names contain specified text or add and exclude selected transactions by clicking the Filter Filter Toolbar Button toolbar button, choosing Event Filter on the View menu, or pressing Ctrl+L.


Log System Activity

You can use the command-line -log option to write activity to a log file without opening the console.


Save Events in the Display

You can save the contents of the Event Pane as a text file by choosing Save on the File menu or pressing Ctrl+S.

You can copy a selected item to the Clipboard by choosing Copy from the Edit menu or pressing Ctrl+C.

Note

You can also save the contents of the Event Pane as HTML formatted reports.


View Different Columns in the Display

You can select the columns that appear in the display by choosing Select Columns from the Options menu or from the context menu that appears when you right-click on an item in the Event Pane.


Reporting Bugs

If you encounter a bug please send email to markruss@microsoft.com, including the behavior you observed, the behavior you expected, and steps for reproducing the problem.


_Overview Capturing Events

You can toggle capture mode on and off by clicking the Capture Capture Toolbar Button toolbar button, choosing Capture Events from the File menu, or pressing Ctrl+E. No data is collected when capture mode is off.

More information


_Overview Clearing the Display

You can clear the display by clicking the Clear Clear Toolbar Button toolbar button or choosing Clear Display from the Edit menu.

More information


_Overview Connecting to a System

You can connect to a remote computer by typing or selecting the computer name on the toolbar and clicking Connect [image].

You can also connect to a remote computer by choosing Connect from the Computer menu or by pressing Ctrl+R. This action opens the Select Remote Computer dialog box.

To view activity on your local system, choose Connect Local from the Computer menu.

More information


_Overview Filtering the Display

You can display or hide processes whose names contain specified text, or add or exclude selected transactions, by clicking the Filter Filter Toolbar Button toolbar button, choosing Event Filter from the View menu, or pressing Ctrl+L.

This action opens the Event Filters dialog box.

More information


_Overview Finding Event Errors

To go to the next error in the Event Pane, click the Next Next Toolbar Button toolbar button or choose Next Event Error from the context menu that appears when you right-click on an item in the Event Pane.

To go to the previous error in the Event Pane, click the Prev Previous Toolbar Button toolbar button or choose Previous Event Error from the context menu that appears when you right-click on an item in the Event Pane.

More information


_Overview Finding Text

You can find an occurrence of text in the Event Pane by clicking the Find Find Toolbar Button toolbar button, choosing Find on the Edit menu, or pressing Ctrl+F.

More information


_Overview Highlighting Events

You can set display highlighting properties by choosing Highlight Preferences on the Highlight menu or from the context menu that appears when you right-click on an item in the Event Pane.

This action opens the Event Highlighting dialog box.

More information


_Overview Opening a New Window

You can open new windows to simultaneously view the activity of multiple machines.

To open a new window, click the New New Window Toolbar Button toolbar button, choose New Window on the File menu or press Ctrl+N.

After you open a new window you must connect to a system to begin capturing LDAP activity.

More information


_Overview Setting Auto Scroll

You can toggle Auto Scroll off and on by clicking the Scroll Scroll Toolbar Button toolbar button, choosing Auto Scroll on the View menu, or pressing Ctrl+A.

More information


_Overview Setting History Depth

By default older lines are discarded from the event list to stay within a specified History depth.

You can change the History depth by clicking the History History Toolbar Button toolbar button, choosing History Depth on the View menu, or pressing Ctrl+H.

This action opens the Event List History Depth dialog box.

More information


_Overview Setting the Column Display

You can select the columns that appear in the display by choosing Select Columns from the Options menu or from the context menu that appears when you right-click on an item in the Event Pane.

This action opens the Select Columns dialog box.

More information


_Overview Viewing Event Information

You can view summary information about an LDAP function that appears in the Request column by double-clicking an item in the Event Pane or choosing Event Information from the context menu that appears when you right-click.

This action opens a pop-up dialog box that displays the full name and description of the function.

More information


_Popup Asynchronous

When a client calls an asynchronous function, it does not need to wait for the operation to complete to perform other tasks. Asynchronous functions return a unique message ID and a result code indicating if the request was successfully sent to the server.


_Popup Clock Time

Clock time is the time of day that an event occurred.

To display clock time, select Clock Time on the Options menu.


_Popup Filter Expression Rules

Filter Expression Rules

  • You can type multiple expressions by separating each expression with a semicolon (;).

  • Use the asterisk (*) as a wildcard character.

  • Do not include spaces in the expression unless you want the spaces to be part of the filter.

  • Filter expressions are a case-insensitive.


_Popup More Info Link

Click the More Info hyperlink to view detailed diagnostic information about the LDAP function. This action opens a browser window with information from the MSDN Library Web site.

More information


_Popup Relative Time

Relative time is the difference between the time of an event and the time of the first event in the display.

To display relative time, clear Clock Time on the Options menu.


_Popup Synchronous

When a client calls a synchronous function, it waits for the operation to complete before executing any subsequent code. Synchronous functions return Success if successful and an error code if not.


Accessing Help

To access help in Insight for Active Directory, press F1 or click Help on the Help menu.


Always Start with Specified Connections

You can start Insight for Active Directory with connections already established to specified machines by adding the -r parameter and associated options to your startup command.


Connecting to a System

By default Insight for Active Directory starts without connecting to a system. You must connect to a system to display LDAP activity.

To view activity on your local system, choose Connect Local from the Computer menu.

To connect to a remote system, choose Connect from the Computer menu or press Ctrl+R. This action opens the Select Remote Computer dialog box.

Select Remote Computer Dialog Box

  • Type or select a computer name in the Computer box or click the Browse button to browse for a remote machine.

  • To connect using another account, click Connect as and type the name and password of an account with Administrator rights on the remote computer.

  • To connect using a specified port, click Connect to Running Service using Port and type the port number.

Notes

  • You can also connect to a remote machine by typing or selecting the system name on the toolbar and clicking the Connect [image] button.

  • To hide or display a tray icon Tray Icon on systems running the monitoring service, change the TCP/IP port number or administrative share name, choose Preferences from the Options menu.

  • You can start Insight for Active Directory with connections already established to machines you specify by adding the -r parameter and associated options to your startup command.

Confirming Your Connection

When you connect to a previously unconnected computer you must confirm that you wish to activate a server or workstation license.

License Confirmation Message Box

Click OK to activate a new license or Cancel to cancel the connection.

Notes

  • If you activate a new licensed connection you cannot undo the operation.

  • To view the number of available connections and a list of previously activated connections, choose License Management on the Help menu.


Connect Without File and Printer Sharing

You can view remote system activity on networks with File and Printer Sharing disabled by running the adinsight executable with the -c option on systems to be monitored.


Disconnecting

To disconnect from a system choose Disconnect from the Computer menu.

Note

You can later reconnect to a system by choosing Connect or Connect Local from the Computer menu, or by typing or selecting a system name on the toolbar and clicking the Connect [image] button.


_Popup Event Handle

The event handle denotes related LDAP events within a particular session.


Getting Technical Support

To access the Winternals Knowledge Base, view Frequently Asked Questions, or download updates visit our support web site at www.winternals.com/support.

You may request help by email for issues not covered in the Online Help or Support Knowledge Base. Please visit www.winternals.com/support/getsupport.asp or send email to support@winternals.com.

Customers who have purchased Product Assurance may receive phone support by calling 512-330-9861. Before contacting support, please determine if the problem is reproducible. If so, record the steps necessary to reproduce it.

In addition, please have the following information ready:

  • Your Insight for Active Directory license number and version number

  • The Windows version (including Service Pack) of the system where the issue occurred

  • Memory size, disk types, and file system types


Installing Insight for Active Directory

You should install Insight for Active Directory on the computer that you will use to display and log Active Directory LDAP activity.

To install Insight for Active Directory, insert the Installation CD into the CD-ROM drive and follow the instructions on each screen. The Installation Wizard will guide you through the process.


Licensing

Unless otherwise stated in your license agreement, Insight for Active Directory is licensed by the number of Server and Workstation connections that you can activate from your console computer.

To view your license information choose License Management from the Help menu. It is the responsibility of the License Administrator to insure that the product is not distributed or installed in such a way that the number of licensed nodes is exceeded.

The first time that you run Insight for Active Directory you will be asked to enter your Activation Key. Your Activation Key is a text file that identifies the products that you have licensed, the number of server and workstation connections available, and the name of the company and individual for whom the license was issued.

If you have not yet been issued an Activation Key, please email Winternals Customer Service with your license number.

If you have already obtained your Activation Key, paste the information into the text box, or click Browse to browse for the file containing your key. Once you enter your Activation Key you will not be required to enter a key again unless you wish to add licensed connections.

Managing Licenses

You can view the number of available connections and a list of previously activated connections by choosing License Management on the Help menu.

This action opens the License Management dialog box.

License Management Dialog Box

Adding Licensed Connections

To add additional licensed connections using new license keys purchased from Winternals Software, click Add new licenses. This action opens the Licensing dialog box.

Licensing Dialog Box

Click Browse to browse for the location of your Activation Key, or copy and paste your key into the space provided. When the text box displays a valid license key you can press Activate to activate the license.


Monitor Logon Activity

You can monitor a system's logon activity by starting the monitoring service before logon, either by connecting to the system from another machine or by starting the monitoring service via the command line in a logon script.

You can monitor local logon activity by starting with the -log option in a logon script.


Requirements

Insight for Active Directory works on Windows 2000 and higher .


_Popup Session Handle

The session handle is a pointer to a data type representing the LDAP session. The session handle is created by an LDAP initialize request and passed to subsequent calls pertaining to the session.


Setting Program Preferences

To change the default capture mode when making a new connection, display a tray icon [image] on computers running the monitoring service, change the TCP/IP port number or administrative share name, or display uncalled functions in Events with Time Results reports, choose Preferences from the Options menu.

This action opens the Preferences dialog box.


Starting Insight for Active Directory

To begin using Insight for Active Directory, choose the Insight for Active Directory shortcut Insight Icon from the Start menu.

You will be prompted to enter your Activation Key if you have not already done so. Click Browse to browse for the location of your Activation Key, or copy and paste your key into the space provided. When the text box displays a valid license key you can press Activate to activate the license.

Licensing Dialog Box

Purchasers receive Activation Keys by email at the time that orders are processed. If you did not receive your Activation Key, contact Winternals Customer Service with your license number or company and purchaser information.

After you enter your Activation Key, you will be prompted to connect to a system to begin viewing LDAP activity.

Select Do not show this message again if you do not want to view the message the next time that you start the program.

Note

You can start Insight for Active Directory with connections already established to machines you specify by adding the -r parameter and associated options to your startup command.


Troubleshoot Logon Issues

You can view and troubleshoot a system's logon activity by starting the monitoring service before logon, either by connecting to the system from another machine or by starting the monitoring service with a logon script command.

You can monitor the logon activity of your local system by starting Insight for Active Directory with the -log option in a logon script.


View Activity on Multiple Domain Controllers

You can simultaneously view the activity of several systems, including multiple domain controllers, by opening new windows and connecting to a different system in each window.


View the Activity of Multiple Systems

You can simultaneously view the activity of additional machines by opening new windows and connecting to the systems.


Working With Multiple Windows

You can open new windows to simultaneously view the activity of multiple machines.

To open a new window, click the New New Window Toolbar Button toolbar button, choose New Window from the File menu or press Ctrl+N.

After you open a new window you must connect to a system to begin capturing LDAP activity.

Note

You can display the activity of a particular computer in only one window.