StartTraceA 函数 (evntrace.h)

  • 项目

StartTrace 函数注册并启动事件跟踪会话。

重要

跨进程事件跟踪会话是一种有限的系统资源。 开发人员应避免在客户计算机上启动事件跟踪会话。 当需要事件跟踪会话时，应将其限制在尽可能小的范围内：尽可能少使用会话，如果可能，请使用进程内会话 (EVENT_TRACE_PRIVATE_LOGGER_MODE | EVENT_TRACE_PRIVATE_IN_PROC) ，仅在方案需要收集时才启动跟踪，在方案完成后立即停止跟踪，限制会话使用的内存量， 和 使用严格的事件筛选器，这样就不会收集不必要的事件。

语法

ULONG WMIAPI StartTraceA(
  [out]     PTRACEHANDLE            TraceHandle,
  [in]      LPCSTR                  InstanceName,
  [in, out] PEVENT_TRACE_PROPERTIES Properties
);

参数

[out] TraceHandle

接收事件跟踪会话的句柄，以便后续使用 ControlTrace 等 API。

如果该函数失败，则不要使用此句柄。 不要将会话句柄与INVALID_HANDLE_VALUE进行比较。 如果句柄无效，则会话句柄为 0。

[in] InstanceName

包含事件跟踪会话名称的 Null 终止字符串。 会话名称限制为 1，024 个字符，不区分大小写，并且必须是唯一的。

重要

为会话使用描述性名称，以便可以从会话名称确定会话的所有权和使用情况。 请勿使用 GUID 或其他非确定性或非描述性值。 不要追加随机数字以使会话名称唯一。 ETW 会话是有限的资源，因此组件不应启动多个会话。 如果组件启动时组件的会话已在运行，则组件应清理孤立会话，而不是创建第二个会话。

此函数将你提供的会话名称复制到“属性”的 LoggerNameOffset 成员指向的偏移量。

[in, out] Properties

指向指定会话行为的 EVENT_TRACE_PROPERTIES 结构的指针。 以下是要设置的结构的关键成员：

  • Wnode.BufferSize
  • Wnode.Guid
  • Wnode.ClientContext
  • Wnode.Flags
  • LogFileMode
  • LogFileNameOffset
  • LoggerNameOffset

根据选择创建的日志文件的类型，可能还需要为 MaximumFileSize 指定一个值。 有关设置 Properties 参数和会话行为的详细信息，请参阅备注部分。

从 Windows 10 版本 1703 开始：为了在跨进程方案中获得更好的性能，现在可以在启动系统范围的专用记录器时将筛选传递到 StartTrace。 需要传入新的 EVENT_TRACE_PROPERTIES_V2 结构，以包含筛选信息。 有关更多详细信息，请参阅 配置和启动专用记录器会话 。

返回值

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

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

  • ERROR_BAD_LENGTH

    下列情况之一存在：

    • 属性的 Wnode.BufferSize 成员指定了不正确的大小。
    • 属性 没有分配足够的空间来保存 InstanceName 的副本。

  • ERROR_INVALID_PARAMETER

    下列情况之一存在：

    • 属性 为 NULL。
    • TraceHandle 为 NULL。
    • Properties 的 LogFileNameOffset 成员无效。
    • Properties 的 LoggerNameOffset 成员无效。
    • Properties 的 LogFileMode 成员指定无效标志的组合。
    • Wnode.Guid 成员是 SystemTraceControlGuid，但 InstanceName 参数不是KERNEL_LOGGER_NAME。

  • ERROR_ALREADY_EXISTS

    同名或 GUID 的会话已在运行。

  • ERROR_BAD_PATHNAME

    由于以下原因之一，可能会收到此错误：

    • 另一个会话已在使用由 Properties 结构的 LogFileNameOffset 成员指定的文件名。
    • LogFileMode 和 LogFileNameOffset 均为零。

  • ERROR_DISK_FULL

    驱动器上没有足够的可用空间用于日志文件。 如果出现以下情况，则会发生此情况：

    • MaximumFileSize 为非零值，日志文件没有可用的 MaximumFileSize 字节
    • 驱动器是系统驱动器，没有额外的 200 MB 可用
    • MaximumFileSize 为零，没有额外的 200 MB 可用

    选择具有更多空间的驱动器，或减小 MaximumFileSize (中指定的大小（如果使用) ）。

  • ERROR_ACCESS_DENIED

    只有具有管理权限的用户、性能日志用户组中的用户以及作为 LocalSystem、LocalService、NetworkService 运行的服务才能控制事件跟踪会话。 若要授予受限用户控制跟踪会话的能力，请将这些用户添加到“性能日志用户”组。 只有具有管理权限和以 LocalSystem 身份运行的服务的用户才能控制 NT 内核记录器会话。

    如果用户是“性能日志用户”组的成员，则他们可能没有在指定文件夹中创建日志文件的权限。

  • ERROR_NO_SYSTEM_RESOURCES

    下列情况之一存在：

    • 日志记录会话使用 EVENT_TRACE_SYSTEM_LOGGER_MODE 标志，系统记录器的最大数目 (8) 已达到。

    • 已达到系统上的最大日志记录会话数。 在日志记录会话停止之前，无法创建新的记录器。 在大多数系统上，日志记录会话的最大数目为 64。

      可以通过编辑 处的 REG_DWORD 键 HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\WMI@EtwMaxLoggers来更改系统的最大日志记录会话数。 允许的值为 32 到 256（含）。 任何更改都需要重新启动才能生效。

      请注意，记录器使用系统资源。 如果填充了这些槽，增加系统上的记录器数量将会导致性能损失。 存在此限制以防止过度使用系统资源。

      重要

      只有系统管理员手动调整限制才能启用特定方案。 程序或驱动程序不得自动修改 EtwMaxLoggers 设置。

      在Windows 10版本 1709 之前，这是非专用记录器的固定上限（包含 64 个记录器）。

备注

事件跟踪控制器调用此函数。

会话将保持活动状态，直到会话停止、计算机重启、发生 I/O 错误或达到非循环日志的最大文件大小。 若要停止事件跟踪会话，请调用 ControlTrace 函数并将 ControlCode 参数设置为 EVENT_TRACE_CONTROL_STOP。

不能使用) 指定的 Properties.Wnode.Guid 同一会话 GUID (启动多个会话。 在大多数情况下，将设置为 Properties.Wnode.Guid 全零 (即 GUID_NULL) ，以允许 ETW 系统为会话生成新的 GUID。

若要指定专用记录器会话，请将“属性”的 Wnode.Guid 成员设置为提供程序的控制 GUID，而不是专用记录器会话的控件 GUID。 在调用 StartTrace 之前，提供程序必须已注册 GUID。

不使用此函数启动全局记录器会话， (弃用) 。 有关启动全局记录器会话的详细信息，请参阅 配置和启动全局记录器会话。

系统记录器

要使记录器成为系统记录器并从 SystemTraceProvider 或其他 系统提供程序接收事件，必须满足以下任何条件：

  • Properties 成员 LogFileMode 包括首选) (EVENT_TRACE_SYSTEM_LOGGER_MODE标志。
  • 属性成员 Wnode.Guid 设置为 SystemTraceControlGuid 或 GlobalLoggerGuid (已弃用 - 不应用于新代码，因为它将与其他也尝试使用这些 GUID 的组件冲突) 。
  • InstanceName 设置为 KERNEL_LOGGER_NAME (已弃用 - 不应用于新代码，因为它将与尝试) 使用此名称的其他组件冲突。

注意

 系统记录器必须设置 EVENT_TRACE_PROPERTIES 结构的 EnableFlags 成员，以指示哪些 SystemTraceProvider 事件应包含在跟踪中。

由于系统记录器接收特殊的内核事件，因此它们受到其他限制：

  • 同一系统上活动的系统记录器不能超过 8 个。
  • 无法在 Windows Server 容器中创建系统记录器。
  • 系统记录器不能使用 EVENT_TRACE_USE_PAGED_MEMORY 标志。
  • 在Windows 10版本 1703 之前，任何系统记录器都可以同时使用不超过 2 个不同的时钟类型。 例如，如果一个活动系统记录器使用“CPU 周期计数器”时钟类型，而另一个活动系统记录器使用“查询性能计数器”时钟类型，则任何尝试使用“系统时间”时钟类型启动系统记录器都将失败，因为它需要激活第三种时钟类型。 由于此限制，Microsoft 强烈建议系统记录器不要使用“系统时间”时钟类型。
  • 从 Windows 10 版本 1703 开始，时钟类型限制已删除。 系统记录器现在可以同时使用这三种时钟类型。

若要指定 NT 内核记录器会话 (弃用) ，请将 InstanceName 设置为 KERNEL_LOGGER_NAME，将“属性”的 Wnode.Guid 成员设置为 SystemTraceControlGuid。 如果未将 GUID 指定为 SystemTraceControlGuid，ETW 将替代 GUID 值并将其设置为 SystemTraceControlGuid。

示例

有关使用 StartTrace 的示例，请参阅 配置和启动事件跟踪会话。

注意

evntrace.h 标头将 StartTrace 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将非特定编码别名的使用与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。 有关详细信息，请参阅 函数原型的约定。

要求

   
最低受支持的客户端 Windows Vista [桌面应用 |UWP 应用]
最低受支持的服务器 Windows Server 2008 [桌面应用 |UWP 应用]
目标平台 Windows
标头 evntrace.h
Library Windows 8.1 上的 Sechost.lib 和 Windows Server 2012 R2;Windows 8、Windows Server 2012、Windows 7、Windows Server 2008 R2、Windows Server 2008、Windows Vista 上的 Advapi32.lib
DLL Windows 8.1 和 Windows Server 2012 R2 上的Sechost.dll;Windows 8、Windows Server 2012、Windows 7、Windows Server 2008 R2、Windows Server 2008、Windows Vista 上的Advapi32.dll

请参阅

ControlTrace

EVENT_TRACE_PROPERTIES