ControlTraceA 函数 (evntrace.h)

  • 项目

ControlTrace 函数刷新、查询、更新或停止指定的事件跟踪会话。

语法

ULONG WMIAPI ControlTraceA(
  [in]      TRACEHANDLE             TraceHandle,
  [in]      LPCSTR                  InstanceName,
  [in, out] PEVENT_TRACE_PROPERTIES Properties,
  [in]      ULONG                   ControlCode
);

参数

[in] TraceHandle

事件跟踪会话的句柄，或 0。 如果 SessionName 为 NULL，则必须指定非零 SessionHandle。 如果 SessionName 不为 NULL，ETW 将忽略句柄。

启动新跟踪时 ，StartTrace 函数将返回此句柄。 若要获取现有跟踪的句柄，请使用 ControlTrace 根据跟踪的名称查询跟踪属性，然后从返回EVENT_TRACE_PROPERTIES数据的 Wnode.HistoricalContext 字段获取句柄。

[in] InstanceName

事件跟踪会话的名称，或 NULL。 如果 TraceHandle 为 0，则必须指定 InstanceName。

若要指定 NT 内核记录器会话，请将 InstanceName 设置为 KERNEL_LOGGER_NAME。

[in, out] Properties

指向已初始化 EVENT_TRACE_PROPERTIES 结构的指针。 在设置任何字段之前，应将此结构归零。

如果 ControlCode 指定EVENT_TRACE_CONTROL_STOP、EVENT_TRACE_CONTROL_QUERY或EVENT_TRACE_CONTROL_FLUSH，则只需设置EVENT_TRACE_PROPERTIES结构的 Wnode.BufferSize、Wnode.Guid、LoggerNameOffset 和 LogFileNameOffset 成员。 如果会话是专用会话，则还需要设置 LogFileMode。 可以使用最大会话名称 (1024 个字符) 和最大日志文件名 (1024 个字符) 长度来计算缓冲区大小和偏移量（如果未知）。

如果 ControlCode 指定 EVENT_TRACE_CONTROL_UPDATE，则输入时，成员必须指定要更新的属性的新值。 在输出中， “属性” 包含事件跟踪会话的属性和统计信息。 可以更新以下属性。

  • EnableFlags：将此成员设置为 0 以禁用所有系统提供程序。 将此设置为非零值，以指定要启用或保持启用的系统提供程序。 这可能不是零，仅适用于 系统记录器。

  • FlushTimer：如果要更改刷新缓冲区前等待的时间，请设置此成员。 如果此成员为 0，则不会更新该成员。

  • LogFileNameOffset：如果要切换到另一个日志文件或将缓冲模式跟踪刷新到新的日志文件，请设置此成员。 如果此成员为 0，则不更新文件名。 如果偏移量不为零，并且不更改日志文件名，则函数将返回错误。

  • LogFileMode：如果要打开和关闭 EVENT_TRACE_REAL_TIME_MODE ，请设置此成员。 若要关闭实时消耗时间，请将此成员设置为 0。 若要在创建记录到磁盘的会话以及实时) 传送事件的 (实时启用耗时，请将此成员设置为 EVENT_TRACE_REAL_TIME_MODE ，它将使用当前模式进行 OR。

  • MaximumBuffers：如果要更改 ETW 使用的最大缓冲区数，请设置此成员。 如果此成员为 0，则不会更新该成员。

对于专用记录器会话，只能更新 LogFileNameOffset 和 FlushTimer 成员。

如果使用新初始化 EVENT_TRACE_PROPERTIES 结构，请将结构归零，然后设置 Wnode.BufferSize、 Wnode.Guid 和 Wnode.Flags 以及要更新的值。

如果要重用EVENT_TRACE_PROPERTIES结构 (即使用之前传递给 StartTrace 或 ControlTrace) 的结构，请确保将 LogFileNameOffset 成员设置为 0，除非更改日志文件名称，并确保设置EVENT_TRACE_PROPERTIES。要WNODE_FLAG_TRACED_GUID的 Wnode.Flags。

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

[in] ControlCode

请求的控制函数。 可以指定以下值之一：

  • EVENT_TRACE_CONTROL_FLUSH：刷新会话的活动缓冲区。

    这可以与内存中会话一起使用， (以 EVENT_TRACE_BUFFERING_MODE 标志) 启动的会话，将数据从跟踪写入文件。

    通常不需要刷新基于文件或实时的会话，因为当缓冲区已满 (即当缓冲区没有空间用于下一个事件) 、跟踪会话的 FlushTimer 过期或跟踪会话关闭时，ETW 会自动刷新缓冲区。

    Windows 2000： 不支持此值。

  • EVENT_TRACE_CONTROL_QUERY：检索会话属性和统计信息。

  • EVENT_TRACE_CONTROL_STOP：停止会话。 会话句柄不再有效。

  • EVENT_TRACE_CONTROL_UPDATE：汇报会话属性。

  • EVENT_TRACE_CONTROL_INCREMENT_FILE：如果会话具有 EVENT_TRACE_FILE_MODE_NEWFILE，则更新会话以立即切换到下一个文件，而不是等待上一个文件填满。 从 Windows 10 2018 年 10 月更新 开始支持。

  • EVENT_TRACE_CONTROL_CONVERT_TO_REALTIME：将文件模式会话更改为实时会话 (启用实时传递，并禁用将事件写入 ETL 文件) 。 从 2020 年 10 月更新Windows 10开始支持。

注意

从 DllMain 刷新缓冲区或停止跟踪会话是不安全的， (可能会导致死锁) 。

返回值

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

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

  • ERROR_BAD_LENGTH

    下列情况之一存在：

    • 属性的 Wnode.BufferSize 成员指定了不正确的大小。
    • 如果) 使用，属性没有分配足够的空间来保存会话名称和日志文件名称的副本 (。

  • ERROR_INVALID_PARAMETER

    下列情况之一存在：

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

  • ERROR_BAD_PATHNAME

    另一个会话已在使用由 Properties 结构的 LogFileNameOffset 成员指定的文件名。

  • ERROR_MORE_DATA

    EVENT_TRACE_PROPERTIES缓冲区太小，无法保存会话的所有信息。 如果不需要会话的属性信息，可以忽略此错误。 如果在停止会话时收到此错误，则 ETW 在生成此错误之前已停止会话。

  • ERROR_ACCESS_DENIED

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

    Windows XP 和 Windows 2000： 任何人都可以控制跟踪会话。

  • ERROR_WMI_INSTANCE_NOT_FOUND

    给定的会话未运行。

注解

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

此函数取代 FlushTrace、 QueryTrace、 StopTrace 和 UpdateTrace 函数。

注意

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

要求

要求 值
最低受支持的客户端 Windows 2000 专业版 [桌面应用 |UWP 应用]
最低受支持的服务器 Windows 2000 Server [桌面应用 |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 和 Windows XP 上的 Advapi32.lib
DLL Windows 8.1 和 Windows Server 2012 上的 Sechost.dll;Windows 8、Windows Server 2012、Windows 7、Windows Server 2008 R2、Windows Server 2008、Windows Vista 和 Windows XP 上的 Advapi32.dll

另请参阅

EVENT_TRACE_PROPERTIES

QueryAllTraces

StartTrace