EnableTraceEx 函数 (evntrace.h)

项目
06/12/2024

跟踪会话控制器调用 EnableTraceEx 来配置 ETW 事件提供程序将事件记录到跟踪会话的方式。

此函数已过时。 EnableTraceEx2 函数取代此函数。

语法

ULONG WMIAPI EnableTraceEx(
  [in]           LPCGUID                  ProviderId,
  [in, optional] LPCGUID                  SourceId,
                 CONTROLTRACE_ID          TraceId,
  [in]           ULONG                    IsEnabled,
  [in]           UCHAR                    Level,
  [in]           ULONGLONG                MatchAnyKeyword,
  [in]           ULONGLONG                MatchAllKeyword,
  [in]           ULONG                    EnableProperty,
  [in, optional] PEVENT_FILTER_DESCRIPTOR EnableFilterDesc
);

参数

[in] ProviderId

提供程序 ID (控制要配置的事件提供程序的 GUID) 。

[in, optional] SourceId

可以唯一标识此配置请求的源的 GUID;如果不需要源标识，则为 NULL ， (等效于将 SourceId 设置为 &GUID_NULL) 。如果指定，则此值在调用提供程序的 EnableCallback 时用作 SourceId 参数。

注意

对 EnableTrace 的调用和对提供程序 EnableCallback 的相应调用之间并不总是有直接映射。例如，如果为尚未注册的提供程序调用 EnableTrace ，则对 EnableCallback 的调用将推迟到注册发生，如果跟踪使用者会话停止，ETW 将调用 EnableCallback ，即使没有对 EnableTrace 的相应调用。在这种情况下，将在 SourceId 设置为 GUID_NULL 的情况下调用 EnableTrace。

TraceId

[in] IsEnabled

设置为 1 以启用从提供程序接收事件或调整从提供程序接收事件时使用的设置 (例如更改级别和关键字) 。设置为 0 可禁用从提供程序接收事件。

[in] Level

一个值，该值指示你希望提供程序写入的事件的最大级别。如果事件的级别小于或等于此值，除了满足 MatchAnyKeyword 和 MatchAllKeyword 条件外，提供程序通常还会写入事件。

Microsoft 定义级别 1-5 的语义，如下所示。较低的值表示更严重的事件。 EnableLevel 的每个值都会启用指定的级别和所有更严重的级别。例如，如果指定 TRACE_LEVEL_WARNING，使用者将收到警告、错误和关键事件。

值	含义
TRACE_LEVEL_CRITICAL (1)	异常退出或终止事件
TRACE_LEVEL_ERROR (2)	严重错误事件
TRACE_LEVEL_WARNING (3)	警告事件，例如分配失败
TRACE_LEVEL_INFORMATION (4)	非错误信息事件
TRACE_LEVEL_VERBOSE (5)	详细的诊断事件

常 TRACE_LEVEL 量在 evntrace.h 中定义。等效 WINMETA_LEVEL 常量在 winmeta.h 中定义。

[in] MatchAnyKeyword

关键字的 64 位掩码，用于确定要提供程序写入的事件类别。如果事件的关键字位与此值中设置 的任何 位匹配，或者事件没有设置关键字位，除了满足 Level 和 MatchAllKeyword 条件外，提供程序通常会写入事件。

[in] MatchAllKeyword

关键字的 64 位掩码，用于限制要提供程序写入的事件。如果事件的关键字位匹配此值中设置 的所有 位，或者事件没有设置关键字位，除了满足 Level 和 MatchAnyKeyword 条件外，提供程序通常会写入事件。

此值经常设置为 0。

[in] EnableProperty

指定 ETW 运行时在从此提供程序收集事件时应启用的特殊行为的标志。若要启用特殊行为，请指定以下一个或多个标志。否则，请将 EnableProperty 设置为 0。

注意

其中一些标志指示 ETW 应在每个事件中包含额外信息。数据将写入事件的扩展数据项部分。

值	含义
EVENT_ENABLE_PROPERTY_SID	在扩展数据中包括用户的安全标识符 (SID) 。
EVENT_ENABLE_PROPERTY_TS_ID	在扩展数据中包含终端会话标识符。
EVENT_ENABLE_PROPERTY_IGNORE_KEYWORD_0	跟踪会话不应记录关键字为 0 的事件。

[in, optional] EnableFilterDesc

指向筛选器数据的 EVENT_FILTER_DESCRIPTOR 结构。提供程序使用此来筛选数据，以防止将不符合筛选条件的事件写入会话。提供程序确定数据的布局以及它如何将筛选器应用于事件的数据。一个会话只能将一个筛选器传递给提供程序。

会话可以调用 TdhEnumerateProviderFilters 函数来查找提供程序已注册支持的筛选器。

返回值

如果函数成功，则返回值ERROR_SUCCESS。

如果函数失败，则返回值为系统错误代码之一。下面是一些常见错误及其原因。

ERROR_INVALID_PARAMETER

下列情况之一存在：
- ProviderId 为 NULL。
- TraceHandle 为 NULL。
ERROR_INVALID_FUNCTION

如果未注册提供程序，则无法更新级别。
ERROR_NO_SYSTEM_RESOURCES

超出了可以启用提供程序的跟踪会话数。
ERROR_ACCESS_DENIED

只有具有管理权限的用户、组中的用户 Performance Log Users 以及作为 LocalSystem、 LocalService或 NetworkService 运行的服务才能启用跨进程会话的事件提供程序。若要授予受限用户启用事件提供程序的能力，请将这些用户添加到 Performance Log Users 组或请参阅 EventAccessControl。

Windows XP 和 Windows 2000： 任何人都可以启用事件提供程序。

注解

事件跟踪控制器调用此函数来配置将事件写入会话的事件提供程序。例如，控制器可以调用此函数以开始从提供程序收集事件、调整从提供程序收集的事件的级别或关键字，或停止从提供程序收集事件。

此函数已过时。对于其他功能，新代码应使用 EnableTraceEx2。

在大多数情况下，对 EnableTraceEx 的调用可以转换为 EnableTraceEx2 ，如下所示：

// Obsolete:
Status =
EnableTraceEx(
    ProviderId,
    NULL,           // SourceId
    TraceHandle,
    IsEnabled,
    Level,
    MatchAnyKeyword,
    MatchAllKeyword,
    0,              // EnableProperty
    NULL);          // EnableFilterDesc

// Updated equivalent code:
Status = EnableTraceEx2(
    TraceHandle,
    ProviderId,
    IsEnabled,
    Level,
    MatchAnyKeyword,
    MatchAllKeyword,
    0,              // Timeout
    NULL);          // EnableParameters

在更复杂的方案中，对 EnableTraceEx 的调用可以转换为 EnableTraceEx2 ，如下所示：

// Obsolete:
Status =
EnableTraceEx(
    ProviderId,
    SourceId,
    TraceHandle,
    IsEnabled,
    Level,
    MatchAnyKeyword,
    MatchAllKeyword,
    EnableProperty,
    EnableFilterDesc);

// Updated equivalent code:
ENABLE_TRACE_PARAMETERS EnableParameters = {
    ENABLE_TRACE_PARAMETERS_VERSION_2,
    EnableProperty,
    0,                 // ControlFlags
    SourceId ? *SourceId : GUID_NULL,
    EnableFilterDesc,
    EnableFilterDesc ? 1 : 0 };
Status = EnableTraceEx2(
    TraceHandle,
    ProviderId,
    IsEnabled,
    Level,
    MatchAnyKeyword,
    MatchAllKeyword,
    0,                 // Timeout
    &EnableParameters);

有关为会话配置提供程序的语义的其他详细信息，请参阅 EnableTraceEx2 的文档。

要求

要求	值
最低受支持的客户端	Windows Vista [桌面应用 \| UWP 应用]
最低受支持的服务器	Windows Server 2008 [桌面应用 \| UWP 应用]
目标平台	Windows
标头	evntrace.h
Library	Advapi32.lib
DLL	Advapi32.dll

另请参阅

StartTrace

EnableTraceEx2

通过

EnableTraceEx 函数 (evntrace.h)

语法

参数

返回值

注解

要求

另请参阅

反馈

其他资源