StartHeapTrace

此函数用于注册并启动一组指定 PID 的堆跟踪会话。 还可以使用此函数为某些堆事件（如分配或删除）启用堆栈遍历。

必须在调用此函数之前创建要为其启用堆跟踪的过程。 为了从计划一开始就捕获堆事件，建议进程以 CREATE_SUSPENDED 标志开始，然后是为其 PID 启用的堆跟踪，最后是恢复的进程。

堆跟踪非常详细，可以快速生成非常大的跟踪文件。 如果会话的缓冲区太小或太少，事件可能会很容易丢失。 建议限制为其启用堆跟踪的进程数，防止丢失事件。 启用堆跟踪可能会对正在跟踪的进程产生性能影响。

ULONG
WINAPI
StartHeapTrace(
    _Out_ PTRACEHANDLE TraceHandle,
    _Inout_ PEVENT_TRACE_PROPERTIES Properties,
    _In_z_ LPCWSTR wszSessionName,
    _In_reads_opt_(cPids) const ULONG Pids[],
    _In_  ULONG cPids,
    _In_reads_opt_(cStackTracingEventIds) const STACK_TRACING_EVENT_ID StackTracingEventIds[],
    _In_  ULONG cStackTracingEventIds
    );

参数

TraceHandle [out]
存储事件跟踪会话的句柄。 如果句柄无效，则此参数设置为零。 不应将此参数与 INVALID_HANDLE_VALUE 进行比较。 如果该函数失败，则不要使用此句柄。

Properties [in, out]
存储指向 EVENT_TRACE_PROPERTIES 结构的指针。 EVENT_TRACE_PROPERTIES 用于配置会话行为的某些方面。

不需要设置 Guid 成员，因为此函数始终使用其自己的值。 如果指定 GUID，则不会使用它。

wszSessionName [in]
要传递给 StartTrace 的会话名称。

Pids [in]
要对其启用堆跟踪的进程 ID 的数组。

cPids [in]
Pids 数组的大小。

cStackTracingEventIds [in]
StackTracingEventIds 数组的大小。

返回值

ERROR_SUCCESS 表示成功。

下表中描述了可能的错误值。

错误值	说明
ERROR_ALREADY_EXISTS	系统上仅运行内核记录器的单个实例。 如果此函数尝试在另一个组件启动内核日志记录后启动，则可能会返回此错误。
ERROR_INVALID_FLAGS	可能表示 Properties.EnableFlags 中存在无效的跟踪标志。
ERROR_OUT_OF_MEMORY	可能表示无法为 EVENT_TRACE_PROPERTIES 分配内存。

如果该函数由于其他原因失败，则返回系统错误代码。

备注

无

相关主题

函数

UpdateHeapTrace