通过

使用 ETW 排查 LDAP 连接问题

  • 项目

适用于 Windows 的事件跟踪 (ETW) 可用作 Active Directory 域服务 (AD DS) 的重要故障排除工具。 可以使用 ETW 来跟踪 Windows 客户端和 LDAP 服务器（包括 AD DS 域控制器）之间的轻型目录访问协议 (LDAP) 通信。

如何打开 ETW 并启动跟踪

打开 ETW

  1. 打开注册表编辑器，并创建以下注册表子项：

    HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\ldap\Tracing\ProcessName

    在此子项中，ProcessName 是要跟踪的进程的完整名称，包含其扩展名（例如“Svchost.exe”）。

  2. （可选）在此子项下，创建名为 PID的新条目。 若要使用此条目，请分配一个进程 ID 作为 DWORD 值。

    如果指定了进程 ID，则 ETW 仅跟踪具有此进程 ID 的应用程序实例。

启动跟踪会话

  • 打开“命令提示符”窗口并运行以下命令：

    tracelog.exe -start <SessionName> -guid \#099614a5-5dd7-4788-8bc9-e29f43db28fc -f <FileName> -flag <TraceFlags>

    此命令中的占位符表示以下值。

    • <SessionName> 是用于标记跟踪会话的任意标识符。

    注意

    稍后停止跟踪会话时，必须引用此会话名称。

    • <文件名>指定要用于写入事件的日志文件。
    • <TraceFlags> 应为跟踪标志表中列出的一个或多个值。

如何结束跟踪会话并关闭事件跟踪

停止跟踪

  • 在命令提示符处运行以下命令：

    tracelog.exe -stop <SessionName>

    在此命令中，<SessionName> 是 tracelog.exe -start 命令中所使用的同一名称。

关闭 ETW

  • 在注册表编辑器中，删除 HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\ldap\Tracing\ProcessName 子项。

跟踪标志的值

要使用标志，可在 tracelog.exe -start 命令的参数中用标志值替换 <TraceFlags> 占位符。

注意

可以使用相应标志值之和来指定多个标志。 例如，若要指定 DEBUG_SEARCH (0x00000001) 和 DEBUG_CACHE (0x00000010) 标志，相应的 <TraceFlags> 值为 0x00000011。

标志名称 标志值 标志说明
DEBUG_SEARCH 0x00000001 记录搜索请求和传递给这些请求的参数。 其中不记录响应。 仅记录搜索请求。 （使用 DEBUG_SPEWSEARCH 记录对搜索请求的响应。）
DEBUG_WRITE 0x00000002 记录写入请求和传递给这些请求的参数。 写入请求包括添加、删除、修改和扩展操作。
DEBUG_REFCNT 0x00000004 记录连接和请求的引用计数数据和操作。
DEBUG_HEAP 0x00000008 记录所有内存分配和内存释放。
DEBUG_CACHE 0x00000010 记录缓存活动。 该活动包括添加、删除、命中、未命中等。
DEBUG_SSL 0x00000020 记录 SSL 信息和错误。
DEBUG_SPEWSEARCH 0x00000040 记录服务器对搜索请求的所有响应。 这些响应包括请求的属性，以及接收的所有数据。
DEBUG_SERVERDOWN 0x00000080 记录服务器关闭和连接错误。
DEBUG_CONNECT 0x00000100 记录与建立连接相关的数据。
使用 DEBUG_CONNECTION 记录与连接相关的其他数据。
DEBUG_RECONNECT 0x00000200 记录自动重新连接活动。 此活动包括重新连接尝试、失败和相关错误。
DEBUG_RECEIVEDATA 0x00000400 记录与从服务器接收消息相关的活动。 此活动包括“正在等待来自服务器的响应”和从服务器接收到的响应等事件。
DEBUG_BYTES_SENT 0x00000800 记录 LDAP 客户端发送到服务器的所有数据。 此函数本质上是数据包日志记录，只是仅记录未加密的数据。 （如果通过 SSL 发送了数据包，此函数会记录未加密的数据包。）此日志记录可能会很详细。 此标志可能最适合独立使用或与 DEBUG_BYTES_RECEIVED 结合使用。
DEBUG_EOM 0x00001000 记录与“已达消息列表末尾”相关的事件。 这些事件包括“已清理消息列表”等信息。
DEBUG_BER 0x00002000 记录与基本编码规则 (BER) 相关的操作和错误。 这些操作和错误包括编码问题、缓冲区大小问题等。
DEBUG_OUTMEMORY 0x00004000 记录内存分配失败。 还记录计算所需内存时的任何失败（例如，计算所需缓冲区大小时发生的溢出）。
DEBUG_CONTROLS 0x00008000 记录与控件相关的数据。 此数据包括插入的控件、影响控件的问题、连接中的强制性控件等。
DEBUG_BYTES_RECEIVED 0x00010000 记录 LDAP 客户端接收的所有数据。 此行为本质上是数据包日志记录，只是仅记录未加密的数据。 （如果通过 SSL 发送了数据包，此选项会记录未加密的数据包。）此类型的日志记录可能会很详细。 此标志可能最适合独立使用或与 DEBUG_BYTES_SENT 结合使用。
DEBUG_CLDAP 0x00020000 记录特定于 UDP 和无连接的 LDAP 的事件。
DEBUG_FILTER 0x00040000 记录构造搜索筛选器时遇到的事件和错误。
注意：此选项仅记录筛选器构造期间的客户端事件。 它不记录来自服务器的任何有关筛选器的响应。
DEBUG_BIND 0x00080000 日志绑定事件和错误。 此数据包括协商信息、绑定成功、绑定失败等。
DEBUG_NETWORK_ERRORS 0x00100000 记录一般网络错误。 此数据包括发送和接收错误。
注意：如果连接丢失或无法访问服务器，DEBUG_SERVERDOWN 是首选标记。
DEBUG_VERBOSE 0x00200000 记录常规消息。 对于很可能生成大量输出的任何消息，请使用此选项。 例如，它会记录类似“已达消息结尾”、“服务器尚未响应”等消息。 此选项也适用于泛型消息。
DEBUG_PARSE 0x00400000 记录常规消息事件和错误以及数据包分析和编码事件和错误。
DEBUG_REFERRALS 0x00800000 记录有关引荐和追查引荐的数据。
DEBUG_REQUEST 0x01000000 记录对请求的跟踪。
DEBUG_CONNECTION 0x02000000 记录常规连接数据和错误。
DEBUG_INIT_TERM 0x04000000 记录模块初始化和清理（DLL Main 等）。
DEBUG_API_ERRORS 0x08000000 支持记录 API 的不当使用。 例如，如果在同一连接上两次调用绑定操作，此选项会记录相关数据。
DEBUG_ERRORS 0x10000000 记录一般错误。 其中大多数错误可归类为模块初始化错误、SSL 错误或溢出或下溢错误。
DEBUG_PERFORMANCE 0x20000000 在收到 LDAP 请求的服务器响应后，记录有关进程全局 LDAP 活动统计信息的数据。

示例

试想有这么一个应用程序 App1.exe，它为用户帐户设置密码。 假设 App1.exe 发生意外错误。 若要使用 ETW 帮助诊断此问题，请执行以下步骤：

  1. 在注册表编辑器中，创建以下注册表项：

    HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\ldap\Tracing\App1.exe

  2. 若要启动跟踪会话，请打开命令提示符窗口，并运行以下命令：

    tracelog.exe -start ldaptrace -guid \#099614a5-5dd7-4788-8bc9-e29f43db28fc -f .\ldap.etl -flag 0x80000

    此命令启动后，DEBUG_BIND 可确保 ETW 将跟踪消息写入 .\ldap.etl。

  3. 启动 App1.exe，并重现意外错误。

  4. 若要停止跟踪会话，请在命令提示符下运行以下命令：

     tracelog.exe -stop ldaptrace

  5. 若要防止其他用户跟踪应用程序，请删除 HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\ldap\Tracing\App1.exe 注册表项。

  6. 若要查看跟踪日志中的信息，请在命令提示符处运行以下命令：

     tracerpt.exe .\ldap.etl -o -report

    注意

    在此命令中，tracerpt.exe 是跟踪使用者工具。