StartKernelTrace
此函数用于注册并启动内核事件跟踪会话。 还可以使用此函数为某些内核事件启用 stackwalk。
ULONG
WINAPI
StartKernelTrace(
__out PTRACEHANDLE TraceHandle,
__inout PEVENT_TRACE_PROPERTIES Properties,
__in ULONG cStackTracingEventIds
);
参数
TraceHandle [out]
存储事件跟踪会话的句柄。 如果句柄无效，则此参数设置为零。 不应将此参数与 INVALID_HANDLE_VALUE 进行比较。 如果该函数失败，则不要使用此句柄。
Properties [in, out]
存储指向 EVENT_TRACE_PROPERTIES 结构的指针。 EVENT_TRACE_PROPERTIES 用于配置会话行为的某些方面。
EVENT_TRACE_PROPERTIES 结构的第一个成员是 WNODE_HEADER 结构，此处称为“Wnode”。
必须设置以下 EVENT_TRACE_PROPERTIES.Wnode 成员才能配置内核跟踪控制。
BufferSize
此成员包含为事件跟踪会话属性分配的内存总大小（以字节为单位）。 内存大小必须包含足够的空间来存储以下数据：
EVENT_TRACE_PROPERTIES 结构。
会话名称字符串。
日志名称字符串。
对于 NT 内核记录器会话，必须将此成员设置为 SystemTraceControlGuid。 有关日志记录模式常量的详细信息，请参阅 NT 内核记录器常量。
ClientContext
此成员用于设置计算每个事件的日志记录时间戳时使用的时钟分辨率。 此成员的默认值为查询性能计数器。
可以指定以下值之一：
1：查询性能计数器 (QPC)。 QPC 提供高分辨率（100 纳秒）时间戳，但检索起来更昂贵。 如果事件速率较高或者使用者从不同的缓冲区合并事件，请使用此分辨率。 在较旧的计算机上，时间戳可能不准确，因为由于硬件错误，计数器有时会向前跳。
2：系统时间。 系统时间提供低分辨率（10 毫秒）时间戳，但检索成本相对较低。 如果事件量很大，则系统时间的分辨率可能不足以确定事件的顺序。 在这种情况下，一组事件将具有相同的时间戳，但 ETW 传递事件的顺序可能不正确。
3：CPU 周期计数器。 CPU 计数器提供最高分辨率的时间戳，并且检索的开销最小。 但 CPU 计数器不太可靠，不应在生产中使用。 例如，在某些计算机上，除了在某些状态下停止以外，计时器还会由于温度和电源变化而改变频率。 如果你的硬件不支持此时钟类型，则 ETW 将使用系统时间。 在 Windows Server 2003、Windows XP SP1 和 Windows XP 中，不支持此值。 它是在 Windows Server 2003 SP1 和 Windows XP SP2 中引入的。
标志
此成员必须包含 WNODE_FLAG_TRACED_GUID 以指示结构包含事件跟踪信息，并将信息发送到记录器。 WNODE_FLAG_TRACED_GUID 在 Evntrace.h 中定义。
还必须设置以下 EVENT_TRACE_PROPERTIES 成员：
LogFileMode
指示要在内核事件跟踪会话中使用的日志记录模式。 你可以使用此成员来指定将事件写入日志文件、实时使用者或同时写入两者。
此成员还可用于指定会话是专用记录器会话。 可以指定一种或多种模式。 有关可能模式的列表，请参阅日志记录模式常量。
注意：除非有实时使用者准备好使用这些事件，否则不要指定实时日志记录。 如果没有实时使用者，则会将事件写入播放文件。 播放文件的大小是有限制的。 如果达到此限制，则不会将任何新事件记录到日志文件或播放文件中。 日志记录功能失败，并显示 STATUS_LOG_FILE_FULL。
EnableFlags
此成员仅用于 NT 内核记录器会话。 它标识内核记录器要跟踪哪些事件。 通过使用逻辑 OR，此成员可以包含一个或多个值。 除了指定的事件外，内核记录器还会记录硬件配置事件。
除了 EVENT_TRACE_PROPERTIES 提供的跟踪控制标志以外，还提供以下跟踪控制标志：
LogFileNameOffset
此数值表示从分配给结构的内存开始到包含日志文件名称的以 null 结尾的字符串开头的偏移量。
请注意以下事项：
文件扩展名应为 .etl。
路径中的所有文件夹必须都存在。
路径可以是相对路径、绝对路径、本地路径或远程路径。
该路径不能包含环境变量，因为这些变量未展开。
启动跟踪的用户必须对该文件夹具有写入权限。
日志文件名称限制在 1024 个字符以内。
如果将 LogFileMode 设置为 EVENT_TRACE_PRIVATE_LOGGER_MODE 或 EVENT_TRACE_FILE_MODE_NEWFILE，请确保分配足够的内存以包含附加到专用记录器会话文件名的进程标识符，以及添加到使用新文件日志模式创建的日志文件的序号。
如果你不希望将事件记录到日志文件中（例如，仅指定 EVENT_TRACE_REAL_TIME_MODE），请将 LogFileNameOffset 设置为零。 如果仅指定了实时日志记录，并且还提供了具有有效日志文件名称的偏移量，则日志文件名称用于创建顺序日志文件并将事件记录到日志文件。 如果 LogFileMode 为零，并且提供了具有有效日志文件名的偏移量，则也会创建顺序日志文件。
如果要将事件记录到日志文件中，则必须为此结构分配足够的内存，以包含结构后面的日志文件名和会话名称。 日志文件名在内存中必须跟在会话名称的后面。
跟踪文件是使用默认安全描述符创建的，这意味着日志文件将具有与父目录相同的 ACL。 如果要限制对文件的访问，请使用相应的 ACL 创建父目录。
LoggerNameOffset
此成员表示从分配给结构的内存开始到包含会话名称的以 null 结尾的字符串开头的偏移量。
请注意以下事项：
会话名称的长度上限为 1024 个字符。
会话名称不区分大小写，并且必须是唯一的。
为此结构分配内存时，必须保留足够的内存以包括结构后面的会话名称和日志文件名。
会话名称在内存中必须位于日志文件名的前面。 日志文件名必须复制到偏移区。 此函数用于写入 KERNEL_LOGGER_NAME 定义的会话名称。
根据所选的日志文件的类型，可能需要设置 MaximumFileSize 成员。
注意：不需要在 LoggerNameOffset 中设置记录器名称，因为此函数始终使用 KERNEL_LOGGER_NAME 值来调用 StartKernelTrace。 此函数用于检查 Wnode.Guid 是否与 SystemTraceControlGuid 相对应；如果不对应，它将返回 ERROR_INVALID_PARAMETER。 如果 Wnode.Guid 与 KernelRundownGuid 相对应，则应指定记录器名称。 KernelRundownGuid 是用于记录事件（如现有进程信息、线程信息、每个进程加载的映像）和硬件配置（如 CPU、视频、磁盘、网卡、服务、电源、即插即用和磁盘 IDE 通道）的控件 GUID。
返回值
ERROR_SUCCESS 表示成功。
下表中描述了可能的错误值。
| 错误值 | 说明 |
|---|---|
ERROR_ALREADY_EXISTS |
系统上仅运行内核记录器的单个实例。 如果此函数尝试在另一个组件启动内核日志记录后启动，则可能会返回此错误。 |
ERROR_INVALID_FLAGS |
可能表示 Properties.EnableFlags 中存在无效的跟踪标志。 |
ERROR_OUT_OF_MEMORY |
可能表示无法为 EVENT_TRACE_PROPERTIES 分配内存。 |
如果该函数由于其他原因失败，则返回系统错误代码。
注解
如果 StackTracingEventIds 包含未在 EVENT_TRACE_PROPERTIES.EnableFlags 字段中启用或无法由内核跟踪控件解码的事件，将忽略这些标志，并且不返回错误代码。
要求：
版本：从 Windows Vista 开始提供。 此结构随 Windows Performance Analyzer 一起分发。
标头：在 KernelTraceControl.h 中声明。 包括 KernelTraceControl.h。
库：在 KernelTraceControl.dll 中声明。