Compartilhar via


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

Confira também

EventActivityIdControl

EventWriteTransfer

TraceLoggingActivity

TraceLoggingWrite

Macros wrapper de log de rastreamento