Macro TraceLoggingWriteActivity (traceloggingprovider.h)
Emite um evento TraceLogging com IDs de atividade especificadas.
Sintaxe
void TraceLoggingWriteActivity(
[in] hProvider,
[in] eventName,
[in, optional] pActivityId,
[in, optional] pRelatedActivityId,
[in, optional] __VA_ARGS__
);
Parâmetros
[in] hProvider
O identificador do provedor TraceLogging a ser usado para gravar o evento.
[in] eventName
Um nome curto e exclusivo a ser usado para identificar o evento. Isso deve ser um literal de cadeia de caracteres e não uma variável. Ele não pode ter nenhum caractere inserido '\0' .
[in, optional] pActivityId
A ID de atividade do evento ou NULL para usar o padrão.
[in, optional] pRelatedActivityId
A ID da atividade relacionada para o evento ou NULL para nenhuma ID de atividade relacionada.
[in, optional] __VA_ARGS__
Até 99 parâmetros adicionais para configurar ou adicionar campos ao evento. Cada parâmetro deve ser uma das macros tracelogging wrapper, como TraceLoggingLevel, TraceLoggingKeyword ou TraceLoggingValue.
Importante
ProviderId, Level e Keyword são os principais meios para filtrar eventos. Outros tipos de filtragem são possíveis, mas têm uma sobrecarga muito maior. Sempre atribua um nível diferente de zero e palavra-chave a cada evento.
Valor retornado
Nenhum
Comentários
Cada invocação da macro TraceLoggingWriteActivity se expande para o código necessário para gravar um evento no ETW por meio do identificador do provedor especificado.
- TraceLoggingWriteActivity verifica se o provedor especificado está registrado. Se o provedor não estiver registrado, TraceLoggingWriteActivity não fará nada.
- TraceLoggingWriteActivity verifica se algum consumidor está escutando o evento, como se estivesse chamando TraceLoggingProviderEnabled. Se nenhum consumidor estiver escutando o evento, TraceLoggingWriteActivity não fará nada.
- Caso contrário, TraceLoggingWriteActivity avaliará as expressões de runtime especificadas nos argumentos, salvará os resultados, empacotará os dados necessários em um evento e chamará EventWriteTransfer para enviar o evento ao ETW.
O evento gerado será construído da seguinte maneira:
- A ID do provedor do evento, o nome do provedor e o grupo de provedores virão do parâmetro hProvider .
- O nome do evento virá do parâmetro eventName .
- A ID de atividade do evento virá do parâmetro pActivityId . Se pActivityId for NULL, os eventos de modo de usuário usarão a ID de atividade implícita do thread e os eventos do modo kernel usarão GUID_NULL.
- A ID da atividade relacionada do evento virá do parâmetro pRelatedActivityId . Se pRelatedActivityId for NULL, o evento não terá uma ID de atividade relacionada.
- O nível do evento virá do argumento TraceLoggingLevel . Se nenhum argumento TraceLoggingLevel estiver presente, o nível do evento será 5 (WINEVENT_LEVEL_VERBOSE). Se mais de um argumento TraceLoggingLevel estiver presente, o último argumento será usado. Para habilitar a filtragem de eventos eficaz, atribua sempre um nível significativo diferente de zero a cada evento.
- O palavra-chave do evento virá do argumento TraceLoggingKeyword. Se nenhum argumento TraceLoggingKeyword estiver presente, o palavra-chave do evento será 0 (NONE). Se mais de um argumento TraceLoggingKeyword estiver presente, os valores serão OR'ed juntos. Para habilitar a filtragem de eventos eficaz, atribua sempre uma palavra-chave significativa diferente de zero a cada evento.
- Outros atributos de evento podem ser definidos por argumentos como TraceLoggingOpcode, TraceLoggingDescription, TraceLoggingEventTag ou TraceLoggingChannel.
- Os campos de evento podem ser agrupados usando TraceLoggingStruct.
- Os campos de evento são adicionados por argumentos de campo como TraceLoggingValue, TraceLoggingInt32, TraceLoggingHResult, TraceLoggingString etc. Consulte TraceLogging Wrapper Macros para obter detalhes.
Por exemplo:
TraceLoggingWriteActivity(
g_hProvider,
"MyEvent1",
&myActivityGuid,
NULL, // no related activity ID
TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
TraceLoggingKeyword(MyNetworkingKeyword), // Provider-defined categories
TraceLoggingHResult(hr, "NetStatus")); // Adds a "NetStatus" field.
Uma invocação de TraceLoggingWriteActivity(hProvider, "EventName", aid, rid, args...) pode ser considerada como expandindo para código como a seguinte:
if (TraceLoggingProviderEnabled(hProvider, eventLevel, eventKeyword))
{
static const metadata = { GetMetadataFromArgs(args...) };
EVENT_DATA_DESCRIPTOR data[N] = { GetDataFromArgs(args...) };
EventWriteTransfer(etwHandle, metadata.desc, aid, rid, N, data);
}
Observação
Cada macro TraceLoggingWriteActivity verifica automaticamente TraceLoggingProviderEnabled para que o evento só seja gravado se um consumidor estiver escutando eventos do provedor. Como resultado, geralmente é desnecessário chamar diretamente TraceLoggingProviderEnabled. Todas as expressões de runtime em args... serão avaliadas se e somente se o evento estiver habilitado. As expressões de runtime não serão avaliadas mais de uma vez.
Se estiver gerando eventos complexos, você poderá receber um erro do compilador indicando que a linha é muito longa ou que o compilador está sem espaço no heap. Isso ocorre quando a macro TraceLoggingWriteActivity se expande para uma linha mais longa do que o compilador. Se isso acontecer, você precisará simplificar seu evento.
A macro TraceLoggingWriteActivity usa uma matriz de EVENT_DATA_DESCRIPTOR para transferir dados para o ETW. O número máximo de descritores aceitos pelo ETW é 128. Como cada parâmetro pode exigir o uso de 0, 1 ou 2 descritores, é possível atingir o limite do descritor de dados (128) antes de atingir o limite de argumento (99).
Importante
Tente evitar eventos grandes. O ETW foi projetado principalmente para lidar com pequenos eventos. TraceLoggingWriteActivity removerá silenciosamente qualquer evento que seja muito grande. O tamanho do evento baseia-se no total de cabeçalhos do evento (adicionados pelo runtime do ETW), metadados (ou seja, nome do provedor, nome do evento, nomes de campo, tipos de campo) e dados (valores de campo). Se o tamanho total do evento for maior que 65535 ou se a sessão do consumidor estiver usando um tamanho de buffer menor que o tamanho do evento, o evento não será registrado.
Uma chamada para TraceLoggingWrite é a mesma que uma chamada para TraceLoggingWriteActivity com NULL para os parâmetros pActivityId e pRelatedActivityId . Use TraceLoggingWriteActivity se precisar especificar IDs de atividade para um evento.
Consulte EventWriteTransfer para obter informações sobre a semântica dos parâmetros ActivityId e RelatedActivityId .
Consulte EventActivityIdControl para obter informações sobre como escrever atividades no ETW.
Consulte TraceLoggingActivity para classes C++ que ajudam a gerenciar atividades de ETW do TraceLogging.
Requisitos
| 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 | traceloggingprovider.h |
| Biblioteca | Advapi32.lib |