Using ETW to troubleshoot LDAP connections
Event Tracing for Windows (ETW) can be a valuable troubleshooting tool for Active Directory Domain Services (AD DS). You can use ETW to trace the Lightweight Directory Access Protocol (LDAP) communications between Windows clients and LDAP servers, including AD DS domain controllers.
How to turn on ETW and start a trace
To turn on ETW
Open Registry Editor, and create the following registry subkey:
In this subkey, ProcessName is the full name of the process that you want to trace, including its extension (for example, "Svchost.exe").
(Optional) Under this subkey, create a new entry that is named PID. To use this entry, assign a process ID as a DWORD value.
If you specify a process ID, ETW traces only the instance of the application that has this process ID.
To start a tracing session
Open a Command Prompt window, and run the following command:
tracelog.exe -start <SessionName> -guid \#099614a5-5dd7-4788-8bc9-e29f43db28fc -f <FileName> -flag <TraceFlags>
The placeholders in this command represent the following values.
- <SessionName> is an arbitrary identifier that is used to label the tracing session.
You will have to refer to this session name later when you stop the tracing session.
- <FileName> specifies the log file to which events will be written.
- <TraceFlags> should be one or more of the values that are listed in the trace flags table.
How to end a tracing session and turn off Event Tracing
To stop tracing
At the command prompt, run the following command:
tracelog.exe -stop <SessionName>
In this command, <SessionName> is the same name that you used in the tracelog.exe -start command.
To turn off ETW
- In Registry Editor, delete the HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\ldap\Tracing\ProcessName subkey.
Values for trace flags
To use a flag, substitute the flag value for the <TraceFlags> placeholder in the arguments of the tracelog.exe -start command.
You can specify multiple flags by using the sum of the appropriate flag values. For example, to specify the DEBUG_SEARCH (0x00000001) and DEBUG_CACHE (0x00000010) flags, the appropriate <TraceFlags> value is 0x00000011.
|Flag name||Flag value||Flag description|
|DEBUG_SEARCH||0x00000001||Logs search requests and the parameters that are passed to those requests. Responses are not logged here. Only the search requests are logged. (Use DEBUG_SPEWSEARCH to log the responses to search requests.)|
|DEBUG_WRITE||0x00000002||Logs write requests and the parameters that are passed to those requests. Write requests include the add, delete, modify, and extended operations.|
|DEBUG_REFCNT||0x00000004||Logs reference counting data and operations for connections and requests.|
|DEBUG_HEAP||0x00000008||Logs all memory allocations and memory releases.|
|DEBUG_CACHE||0x00000010||Logs cache activity. This activity includes adds, removes, hits, misses, and so on.|
|DEBUG_SSL||0x00000020||Logs SSL information and errors.|
|DEBUG_SPEWSEARCH||0x00000040||Logs all server responses to search requests. These responses include the attributes that were requested, plus all data that was received.|
|DEBUG_SERVERDOWN||0x00000080||Logs server-down and connection errors.|
|DEBUG_CONNECT||0x00000100||Logs data that is related to establishing a connection.
Use DEBUG_CONNECTION to log other data that is related to connections.
|DEBUG_RECONNECT||0x00000200||Logs automatic reconnect activity. This activity includes reconnect attempts, failures, and related errors.|
|DEBUG_RECEIVEDATA||0x00000400||Logs activity that is related to receiving messages from the server. This activity includes events such as "waiting on the response from the server" and the response that is received from the server.|
|DEBUG_BYTES_SENT||0x00000800||Logs all data sent by the LDAP client to the server. This function is essentially packet logging, but it always logs unencrypted data. (If a packet is sent over SSL, this function logs the unencrypted packet.) This logging can be verbose. This flag is probably best used on its own or combined with DEBUG_BYTES_RECEIVED.|
|DEBUG_EOM||0x00001000||Logs events that are related to reaching the end of a message list. These events include information such as "message list cleared" and so on.|
|DEBUG_BER||0x00002000||Logs operations and errors that are related to Basic Encoding Rules (BER). These operations and errors include problems in encoding, buffer size problems, and so on.|
|DEBUG_OUTMEMORY||0x00004000||Logs failures to allocate memory. Also logs any failure to compute the required memory (for example, an overflow that occurs when computing the required buffer size).|
|DEBUG_CONTROLS||0x00008000||Logs data that relates to controls. This data includes controls that are inserted, problems that affect controls, mandatory controls on a connection, and so on.|
|DEBUG_BYTES_RECEIVED||0x00010000||Logs all data that is received by the LDAP client. This behavior is essentially packet logging, but it always logs unencrypted data. (If a packet is sent over SSL, this option logs the unencrypted packet.) This type of logging can be verbose. This flag is probably best used on its own or combined with DEBUG_BYTES_SENT.|
|DEBUG_CLDAP||0x00020000||Logs events that are specific to UDP and connectionless LDAP.|
|DEBUG_FILTER||0x00040000||Logs events and errors that are encountered when you construct a search filter.
Note This option logs client events only during filter construction. It does not log any responses from the server about a filter.
|DEBUG_BIND||0x00080000||Logs bind events and errors. This data includes negotiation information, bind success, bind failure, and so on.|
|DEBUG_NETWORK_ERRORS||0x00100000||Logs general network errors. This data includes send and receive errors.
Note If a connection is lost or the server cannot be reached, DEBUG_SERVERDOWN is the preferred tag.
|DEBUG_VERBOSE||0x00200000||Logs general messages. Use this option for any messages that tend to generate a large amount of output. For example, it logs messages such as "end of message reached," "server has not responded yet," and so on. This option is also useful for generic messages.|
|DEBUG_PARSE||0x00400000||Logs general message events and errors plus packet parsing and encoding events and errors.|
|DEBUG_REFERRALS||0x00800000||Logs data about referrals and chasing referrals.|
|DEBUG_REQUEST||0x01000000||Logs tracking of requests.|
|DEBUG_CONNECTION||0x02000000||Logs general connection data and errors.|
|DEBUG_INIT_TERM||0x04000000||Logs module initialization and cleanup (DLL Main, and so on).|
|DEBUG_API_ERRORS||0x08000000||Supports logging incorrect use of the API. For example, this option logs data if the bind operation is called two times on the same connection.|
|DEBUG_ERRORS||0x10000000||Logs general errors. Most of these errors can be categorized as module initialization errors, SSL errors, or overflow or underflow errors.|
|DEBUG_PERFORMANCE||0x20000000||Logs data about process-global LDAP activity statistics after receiving a server response for an LDAP request.|
Consider an application, App1.exe, that sets passwords for user accounts. Suppose that App1.exe produces an unexpected error. To use ETW to help diagnose this problem, you follow these steps:
In Registry Editor, create the following registry entry:
To start a tracing session, open a Command Prompt window, and run the following command:
tracelog.exe -start ldaptrace -guid \#099614a5-5dd7-4788-8bc9-e29f43db28fc -f .\ldap.etl -flag 0x80000
After this command starts, DEBUG_BIND makes sure that ETW writes tracing messages to .\ldap.etl.
Start App1.exe, and reproduce the unexpected error.
To stop the tracing session, run the following command at the command prompt:
tracelog.exe -stop ldaptrace
To prevent other users from tracing the application, delete the HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\ldap\Tracing\App1.exe registry entry.
To review the information in the trace log, run the following command at the command prompt:
tracerpt.exe .\ldap.etl -o -report
In this command, tracerpt.exe is a trace consumer tool.