Event Tracing for Windows(ETW) - 配置并开始事件跟踪的会话 译(7)

Configuring and Starting an Event Tracing Session

原文链接
作者：Microsoft
译者：塔塔塔塔塔

配置Session，使用EVENT_TRACE_PROPERTIES结构体指定Session的属性。为EVENT_TRACE_PROPERTIES结构体分配的内存必须足够大，以包含结构下的的Session和日志文件名。

指定Session的属性后，调用StartTrace函数以启动Session。如果该函数成功，则SessionHandle参数将包含Session的句柄，而LoggerNameOffset属性将包含Session名称的偏移量。

想要启用Providers将事件记录到Session，调用EnableTrace函数启用Classic Providers，调用EnableTraceEx功能启用Manifest Providers，供应商。若要启用要在Windows 8.1，Windows Server 2012 R2和更高版本上的特定条件下将Event记录到Session 的Provider，请调用EnableTraceEx2函数。

此外，您还可以通过调用TraceSetInformation函数来跟踪Event的其他信息。TraceSetInformation将其他跟踪信息放入Event的扩展数据部分，并且可以包括诸如跟踪版本信息或当前在系统上注册了哪些Provider之类的信息。有关更多信息，请参见Retrieving Additional Event Tracing Data。

最多八个Session可以启用和接收来自同一个Manifest Providers的Event。只能一个Session可以启用Classic Provider。如果多个Session尝试启用Classic Provider，则当第二个SessionB启用Classic Provider时，第一个SessionA将停止接收Event。例如，如果SessionA启用了Classic Provider1，然后SessionB启用了Classic Provider1，则只有SessionB会从Classic Provider1接收事件。

您可以使用这三个功能中的任何一个来启用Provider，但是如果您使用EnableTrace来启用 Manifest Provider，则可能会失去一些功能，因为您将无法提供MatchAllKeyword值，无法指定事件中要包含的扩展数据项，或提供Provider定义的过滤器数据。有关更多信息，请参见每个功能的“备注”部分。

在Windows 8.1，Windows Server 2012 R2和更高版本上，使用Event payload，scope, and stack walk filters 需要通过使用EnableTraceEx2函数通过ENABLE_TRACE_PARAMETERS和EVENT_FILTER_DESCRIPTOR结构体，在Logger Session中进行特定条件筛选，有关Event payload 的更多信息，请参见TdhCreatePayloadFilter和TdhAggregatePayloadFilters函数以及ENABLE_TRACE_PARAMETERS，EVENT_FILTER_DESCRIPTOR和PAYLOAD_FILTER_PREDICATE结构体。

确定Level和Keywords用于启用Manifest Provider，请使用以下命令之一：

• Logman query provider-name
• Wevtutil gp provider-name

这些命令仅列出级别和关键字，Provider必须记录潜在控制器的所有过滤器数据要求。

列举出Manifest Provider，请使用Wevtutil ep。

对于Classic Provider，Provider应自行记录并向potential controllers提供严重等级或启用其支持的标志。如果提供者希望由任何Controller启用，则Provider应接受0作为严重等级并启用标志，并将0解释为执行默认日志记录的请求（无论如何）。

您可以在Provider注册自己之前或之后启用Provider。启用Provider后，ETW将调用Provider的回调函数。如果未注册Provider，则ETW在注册自身后将调用Provider的回调函数。

可以使用EnableTrace函数停用Provider（停止将Event记录到会话中）或更新日志记录级别 或启用Provider的标志。使用EnableTraceEx函数，您可以禁用Provider或更新级别，关键字，扩展数据和过滤器数据。每次调用EnableTrace或EnableTraceEx函数时，ETW都会调用Provider的回调函数。在会话禁用Provider之前，该Provider将保持对Sesion的启用状态。

要在收集Event后停止Session，调用ControlTrace函数并传递EVENT_TRACE_CONTROL_STOP作为控制代码。若要指定要停止的Session，可以从之前StartTrace函数返回的Session 句柄调，或者将先前启用的Session的名称传递给该函数。在停止Session之前，请确保停用所有 Provider。如果在停用Provider之前停止了Session，则ETW将禁用 Provider并尝试调用Provider的控制回调函数。如果启动Session的应用程序结束前没有禁用Provider或不调用ControlTrace函数的情况下，Provider将保持启用状态。

如果ControlTrace函数成功，则将更新会话属性到最终的属性值并运行事件跟踪会话的统计信息。

有关启动事件跟踪会话的示例，请参见以下内容：

Example that Creates a Session and Enables a Manifest-based Provider 启用Manifest Provider，停用Manifest Provider，然后停止该Session。