Compartilhar via

Macro TraceLoggingWrite (traceloggingprovider.h)

  • Artigo

Emite um evento TraceLogging.

Sintaxe

void TraceLoggingWrite(
  [in]            hProvider,
  [in]            eventName,
  [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 caracteres inseridos '\0' .

[in, optional] __VA_ARGS__

Até 99 parâmetros adicionais para configurar ou adicionar campos ao evento. Cada parâmetro deve ser uma das macros do Wrapper TraceLogging, 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 TraceLoggingWrite se expande para o código necessário para gravar um evento no ETW por meio do identificador de provedor especificado.

  • TraceLoggingWrite verifica se o provedor especificado está registrado. Se o provedor não estiver registrado, TraceLoggingWrite não fará nada.
  • TraceLoggingWrite verifica se algum consumidor está escutando o evento, como se estivesse chamando TraceLoggingProviderEnabled. Se nenhum consumidor estiver escutando o evento, TraceLoggingWrite não fará nada.
  • Caso contrário, TraceLoggingWrite 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 .
  • No modo de usuário, a ID de atividade do evento virá da ID de atividade implícita do thread. No modo kernel, a ID de atividade do evento será GUID_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.
  • A 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, sempre atribua 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:

TraceLoggingWrite(
    g_hProvider,
    "MyEvent1",
    TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
    TraceLoggingKeyword(MyNetworkingKeyword),
    TraceLoggingString(operationName), // Adds an "operationName" field.
    TraceLoggingHResult(hr, "NetStatus")); // Adds a "NetStatus" field.

Uma invocação de TraceLoggingWrite(hProvider, "EventName", args...) pode ser considerada como expansão para código como o seguinte:

if (TraceLoggingProviderEnabled(hProvider, eventLevel, eventKeyword))
{
    static const metadata = { GetMetadataFromArgs(args...) };
    EVENT_DATA_DESCRIPTOR data[N] = { GetDataFromArgs(args...) };
    EventWriteTransfer(etwHandle, metadata.desc, NULL, NULL, N, data);
}

Observação

Cada macro TraceLoggingWrite verifica automaticamente TraceLoggingProviderEnabled para que o evento seja gravado somente 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 de heap. Isso ocorre quando a macro TraceLoggingWrite se expande para uma linha com mais tempo do que o compilador dá suporte. Se isso acontecer, você precisará simplificar o evento.

A macro TraceLoggingWrite 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. TraceLoggingWrite removerá silenciosamente qualquer evento 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.

Exemplos

#include <windows.h> // or <wdm.h> for kernel-mode.
#include <winmeta.h> // For event level definitions.
#include <TraceLoggingProvider.h>

TRACELOGGING_DEFINE_PROVIDER( // defines g_hProvider
    g_hProvider,  // Name of the provider handle
    "MyProvider", // Human-readable name of the provider
    // ETW Control GUID: {b3864c38-4273-58c5-545b-8b3608343471}
    (0xb3864c38,0x4273,0x58c5,0x54,0x5b,0x8b,0x36,0x08,0x34,0x34,0x71));

int main(int argc, char* argv[]) // or DriverEntry for kernel-mode.
{
    TraceLoggingRegister(g_hProvider);

    TraceLoggingWrite(
        g_hProvider,
        "MyEvent1",
        TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
        TraceLoggingKeyword(MyEventCategories), // Provider-defined categories
        TraceLoggingString(argv[0], "arg0"), // field name is "arg0"
        TraceLoggingInt32(argc)); // field name is implicitly "argc"

    TraceLoggingUnregister(g_hProvider);
    return 0;
}

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

EventWriteTransfer

TraceLoggingWriteActivity

TraceLogging Wrapper Macros