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

Confira também

EventWriteTransfer