Função EventActivityIdControl (evntprov.h)
Cria, consulta e define identificadores de atividade para uso em eventos ETW.
Sintaxe
ULONG EVNTAPI EventActivityIdControl(
[in] ULONG ControlCode,
[in, out] LPGUID ActivityId
);
Parâmetros
[in] ControlCode
Um código de controle que especifica a operação a ser executada.
EVENT_ACTIVITY_CTRL_GET_ID
Define o parâmetro ActivityId como o valor da ID de atividade do thread atual.
EVENT_ACTIVITY_CTRL_SET_ID
Define a ID de atividade do thread atual como o valor do parâmetro ActivityId .
EVENT_ACTIVITY_CTRL_CREATE_ID
Define o parâmetro ActivityId como o valor de uma ID de atividade exclusiva local recém-gerada.
EVENT_ACTIVITY_CTRL_GET_SET_ID
Troca os valores do parâmetro ActivityId e da ID de atividade do thread atual. (Salva o valor da ID de atividade do thread atual e define a ID de atividade do thread atual como o valor do parâmetro ActivityId e define o parâmetro ActivityId como o valor salvo.)
EVENT_ACTIVITY_CTRL_CREATE_SET_ID
Define o parâmetro ActivityId como o valor da ID de atividade do thread atual e define a ID de atividade do thread atual como o valor de uma ID de atividade localmente exclusiva recém-gerada.
[in, out] ActivityId
Um ponteiro para um buffer que contém uma ID de atividade de 128 bits. Esse buffer pode ser de leitura e/ou gravado em, dependendo do valor do parâmetro ControlCode .
Retornar valor
Retorna ERROR_SUCCESS se tiver êxito.
Comentários
Os eventos ETW gravados usando uma das APIs EventWrite conterão um campo "ID de atividade" de 128 bits e, opcionalmente, podem conter um campo "ID de atividade relacionada" de 128 bits. As ferramentas de processamento de rastreamento podem usar os valores desses campos para organizar eventos em grupos chamados atividades.
- Todos os eventos com uma ID de atividade zero ( ou seja, GUID_NULL) são considerados não fazer parte de nenhuma atividade.
- Todos os eventos que têm uma determinada ID de atividade diferente de zero são considerados parte da mesma atividade.
- Para indicar o início da atividade, o provedor deve definir Opcode como WINEVENT_OPCODE_START para o primeiro evento com uma ID de atividade diferente de zero específica (o evento de início ). Se a atividade estiver logicamente aninhada em outra atividade, o provedor deverá definir o campo ID de atividade relacionada do evento inicial como a ID da atividade pai.
- Para indicar o fim da atividade, o provedor deve definir Opcode como WINEVENT_OPCODE_STOP para o último evento com uma ID de atividade diferente de zero específica (o evento stop ).
Para que as IDs de atividade sejam úteis, as IDs de atividade recém-geradas devem ser exclusivas localmente, ou seja, a mesma ID não deve ser gerada duas vezes dentro do rastreamento.
Você pode criar IDs de atividade usando EventActivityIdControl, que gera IDs exclusivas localmente que têm a garantia de serem exclusivas em todos os processos no sistema local até que o sistema seja reinicializado. Você também pode usar um GUID (identificador global exclusivo) como uma ID de atividade. Você pode criar um GUID usando uma API como UuidCreate.
Os threads do modo de usuário têm um valor de ID de atividade de 128 bits local do thread (a ID de atividade do thread). A ID da atividade do thread é inicializada como 0 ( ou seja, GUID_NULL) quando o thread é criado. A ID da atividade do thread pode ser lida ou atualizada usando EventActivityIdControl. A ID da atividade de thread será usada como a ID da atividade para todos os eventos escritos por EventWrite e para todos os eventos escritos por EventWriteTransfer ou EventWriteEx , em que o parâmetro ActivityId é NULL.
Importante
Uma função que altera a ID de atividade de um thread deve ter cuidado para restaurar a ID de atividade original antes de sair. Caso contrário, as alterações da função na ID de atividade do thread interferirão nas atividades dos componentes que chamam a função.
Usando uma ID de atividade especificada explicitamente
Nos casos em que suas atividades não estão limitadas a um único thread ou em que você deseja evitar a possibilidade de interferência de outros componentes substituindo a ID de atividade do thread, talvez você queira especificar explicitamente as atividades de evento por meio do campo ActivityId de EventWriteTransfer ou EventWriteEx em vez de usar a ID de atividade de thread automática.
Se estiver usando manifestos e o Compilador de Mensagens para gravar eventos, as macros geradas usando MC.exe -um a ID de atividade do thread, enquanto as macros geradas por MC.exe -km dão suporte a um parâmetro de ID de atividade.
Originalmente, as -um macros só funcionavam no modo de usuário e as -km macros funcionavam apenas no modo kernel, de modo que o código do modo de usuário só podia usar a ID de atividade do thread atual. No entanto, começando com MC.exe versão 10.0.17741, as macros geradas por MC.exe -km podem ser usadas para o modo de usuário e o modo kernel, para que você possa usar MC.exe -km para gerar macros que aceitam um parâmetro de ID de atividade.
(O código gerado por MC não dá suporte à configuração da ID de atividade relacionada de um evento.)
Se estiver usando TraceLoggingProvider.h para gravar eventos, a macro TraceLoggingWrite usará a ID de atividade do thread, enquanto TraceLoggingWriteActivity aceitará parâmetros para ID de atividade e ID de atividade relacionada. Como alternativa, você pode usar as classes C++ em TraceLoggingActivity.h para suas atividades de TraceLogging.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows Vista [aplicativos da área de trabalho | Aplicativos UWP] |
| Servidor mínimo com suporte | Windows Server 2008 [aplicativos da área de trabalho | Aplicativos UWP] |
| Plataforma de Destino | Windows |
| Cabeçalho | evntprov.h |
| Biblioteca | Advapi32.lib |
| DLL | Advapi32.dll |