ENABLE_TRACE_PARAMETERS 结构 (evntrace.h)

ENABLE_TRACE_PARAMETERS 结构包含用于通过 EnableTraceEx2 启用提供程序的信息。

语法

typedef struct _ENABLE_TRACE_PARAMETERS {
  ULONG                    Version;
  ULONG                    EnableProperty;
  ULONG                    ControlFlags;
  GUID                     SourceId;
  PEVENT_FILTER_DESCRIPTOR EnableFilterDesc;
  ULONG                    FilterDescCount;
} ENABLE_TRACE_PARAMETERS, *PENABLE_TRACE_PARAMETERS;

成员

Version

设置为 ENABLE_TRACE_PARAMETERS_VERSION_2 (2) 。

EnableProperty

编写事件时 ETW 可以包括的可选设置。 某些设置将额外数据写入每个事件的 扩展数据项 部分。 其他设置控制哪些事件将包含在跟踪中。 若要使用这些可选设置,请指定以下一个或多个标志。 否则,将 设置为零。

  • EVENT_ENABLE_PROPERTY_IGNORE_KEYWORD_0

    筛选出事件关键字 (keyword) 为 的事件0

    在 Windows 10 版本 1507 及更高版本上受支持。 Windows 8.1和 Windows 7 上也支持通过修补程序通过 SP1 执行此操作。

  • EVENT_ENABLE_PROPERTY_PROVIDER_GROUP

    指示对 EnableTraceEx2 的此调用应启用 提供程序组 而不是单个事件提供程序。

    在 Windows 10 版本 1507 及更高版本上受支持。 Windows 8.1和 Windows 7 上也支持通过修补程序通过 SP1 执行此操作。

  • EVENT_ENABLE_PROPERTY_PROCESS_START_KEY

    在扩展数据中包含进程启动键。

    进程启动键是标识进程的序列号。 虽然进程 ID 可以在会话中重复使用,但进程启动密钥保证在当前启动会话中是唯一的。

    在 Windows 10 版本 1507 及更高版本上受支持。 Windows 8.1和 Windows 7 上也支持通过修补程序通过 SP1 执行此操作。

  • EVENT_ENABLE_PROPERTY_EVENT_KEY

    在扩展数据中包含事件键。

    事件密钥是事件实例的唯一标识符,它将在侦听此事件的多个跟踪会话中保持不变。 它可用于关联同时的跟踪会话。

    在 Windows 10 版本 1507 及更高版本上受支持。

  • EVENT_ENABLE_PROPERTY_EXCLUDE_INPRIVATE

    筛选掉标记为 InPrivate 事件或来自标记为 InPrivate 的进程的所有事件。

    InPrivate 表示事件或进程包含一些被视为私有或个人的数据。 由进程或事件将自身指定为 InPrivate 才能使它正常工作。

    在 Windows 10 版本 1507 及更高版本上受支持。

  • EVENT_ENABLE_PROPERTY_SID

    在事件的扩展数据中包含用户的安全标识符 (SID) 。

    在 Windows Vista 及更高版本上受支持。

  • EVENT_ENABLE_PROPERTY_TS_ID

    在事件的扩展数据中包含终端会话标识符。

    在 Windows Vista 及更高版本上受支持。

  • EVENT_ENABLE_PROPERTY_STACK_TRACE

    将调用堆栈跟踪添加到使用 EventWrite 编写的事件的扩展数据。

    注意

    如果总事件大小超过 64K,ETW 将删除事件。 如果提供程序正在记录最大大小接近 64K 的事件,则启用堆栈捕获可能会导致事件丢失。

    如果堆栈长于 (192) 的最大帧数,则将从堆栈底部剪切帧。

    对于使用者,事件将包括 EVENT_EXTENDED_ITEM_STACK_TRACE32EVENT_EXTENDED_ITEM_STACK_TRACE64 扩展项。 请注意,在 64 位计算机上,跟踪将包含两个 64 位堆栈,即使跟踪是由 32 位跟踪控制器启动的。

    在 Windows 7 及更高版本上受支持。

ControlFlags

保留。 设置为 0。

SourceId

一个 GUID,用于唯一标识正在启用或禁用提供程序的调用方。 如果提供程序未实现 EnableCallback,则不使用 GUID。

EnableFilterDesc

指向指向筛选器数据的 EVENT_FILTER_DESCRIPTOR 结构的数组的指针。 数组中的元素数在 FilterDescCount 成员中指定。 对于EVENT_FILTER_DESCRIPTOR结构的Type 成员指定的每个筛选器类型,只能有一个描述符。

FilterDescCount

EnableFilterDesc 成员指向的EVENT_FILTER_DESCRIPTOR数组中 ) ( 筛选器的元素数。

FilterDescCount 成员应与 EnableFilterDesc 成员指向的数组中的EVENT_FILTER_DESCRIPTOR结构数匹配。

备注

ENABLE_TRACE_PARAMETERS 结构是版本 2 结构,取代了ENABLE_TRACE_PARAMETERS_V1结构。

Windows 8.1、Windows Server 2012 R2 及更高版本:EnableTraceEx2 函数和ENABLE_TRACE_PARAMETERSEVENT_FILTER_DESCRIPTOR结构可以使用事件有效负载、范围和堆栈访问筛选器来筛选记录器会话中的特定条件。 有关事件有效负载筛选器的详细信息,请参阅 EnableTraceEx2TdhCreatePayloadFilterTdhAggregatePayloadFilters 函数以及 EVENT_FILTER_DESCRIPTORPAYLOAD_FILTER_PREDICATE 结构。

通常,在 64 位计算机上,如果不允许页面错误,则不能在某些上下文中捕获内核堆栈。 若要在 x64 上启用内核堆栈,请将 DisablePagingExecutive “内存管理”注册表值设置为 1。 注册表 DisablePagingExecutive 值位于以下注册表项下: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Memory Management。 这只能用于临时诊断目的,因为这会增加系统的内存使用量。

要求

   
最低受支持的客户端 Windows 7 [仅限桌面应用]
最低受支持的服务器 Windows Server 2008 R2 [仅限桌面应用]
标头 evntrace.h

请参阅

EVENT_FILTER_DESCRIPTOR

EVENT_FILTER_EVENT_ID

PAYLOAD_FILTER_PREDICATE

EnableTraceEx2

TdhAggregatePayloadFilters

TdhCreatePayloadFilter

TdhEnumerateProviderFilters