StartHeapTrace

Essa função registra e inicia uma sessão de rastreamento de heap para um conjunto de PIDs especificados. Você também pode habilitar o andamento da pilha para determinados eventos de heap, como alocação ou exclusão, usando essa função.

O processo para o qual o rastreamento de heap deve ser habilitado deve ser criado antes de chamar essa função. Para capturar eventos de heap desde o início do programa, é aconselhável que o processo seja iniciado com o sinalizador CREATE_SUSPENDED e, em seguida, o rastreamento de heap habilitado para seu PID e, em seguida, o processo seja retomado.

O rastreamento de heap é muito detalhado e pode gerar rapidamente um arquivo de rastreamento muito grande. Os eventos poderão ser perdidos facilmente se os buffers da sessão forem muito pequenos ou muito poucos. É recomendável que o número de processos para os quais o rastreamento de heap esteja habilitado seja limitado para não perder eventos. Habilitar o rastreamento de heap pode ter um impacto no desempenho do processo que está sendo rastreado.

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
    );

Parâmetros

TraceHandle [out]
Armazena um identificador em uma sessão de rastreamento de eventos. Esse parâmetro será definido como zero se o identificador não for válido. Esse parâmetro não deve ser comparado a INVALID_HANDLE_VALUE. Não use esse identificador se a função falhar.

Propriedades [in, out]
Armazena um ponteiro para uma estrutura EVENT_TRACE_PROPERTIES . EVENT_TRACE_PROPERTIES configura determinados aspectos do comportamento da sessão.

Não é necessário definir o membro Guid porque essa função sempre usa o próprio valor. Se você especificar um GUID, ele não será usado.

wszSessionName [in]
O nome da sessão a ser passada para StartTrace.

Pids [in]
Uma matriz de IDs de processo para habilitar o rastreamento de heap.

cPids [in]
O tamanho da matriz Pids.

cStackTracingEventIds [in]
O tamanho da matriz StackTracingEventIds.

Valor Retornado

ERROR_SUCCESS indica êxito.

Possíveis valores de erro são descritos na tabela a seguir.

Valor do erro	Descrição
ERROR_ALREADY_EXISTS	Somente uma única instância do agente de kernel é executada no sistema. Se essa função tentar iniciar depois que outro componente tiver iniciado o registro em log do kernel, esse erro possivelmente será retornado.
ERROR_INVALID_FLAGS	Possivelmente indica que há sinalizadores de rastreamento inválidos em Properties.EnableFlags.
ERROR_OUT_OF_MEMORY	Possivelmente indica falha ao alocar memória para EVENT_TRACE_PROPERTIES.

Se a função falhar por um motivo diferente daqueles listados, um código de erro do sistema será retornado.

Comentários

Nenhum

Tópicos relacionados

Funções

UpdateHeapTrace