Compartilhar via

Macro TraceLoggingChannel (traceloggingprovider.h)

  • Artigo

Macro wrapper traceLogging que define o canal para o evento.

A maioria dos eventos traceLogging não precisa alterar o canal padrão do evento e não deve usar TraceLoggingChannel.

Sintaxe

void TraceLoggingChannel(
  [in]  eventChannel
);

Parâmetros

[in] eventChannel

O canal no qual o evento deve ser registrado. Esse é um valor inteiro de 0 a 255.

Consulte EVENT_DESCRIPTOR para obter detalhes sobre o canal de eventos.

Retornar valor

Nenhum

Comentários

TraceLoggingChannel(eventChannel) pode ser usado como um parâmetro para uma invocação de uma macro TraceLoggingWrite . A maioria dos eventos traceLogging não precisa alterar o canal padrão do evento e não deve usar TraceLoggingChannel.

O parâmetro eventChannel deve ser uma constante de tempo de compilação de 0 a 255. Se nenhum TraceLoggingChannel(n) arg for fornecido, o canal padrão será 11 (WINEVENT_CHANNEL_TRACELOGGING), indicando que esse é um evento de TraceLogging normal. Se vários TraceLoggingChannel(n) args forem fornecidos, o valor do último TraceLoggingChannel(n) parâmetro será usado.

Os canais são usados em cenários avançados de ETW (Rastreamento de Eventos para Windows). Isso inclui gravar em consumidores de eventos definidos pelo sistema, como o Log de Eventos do Windows.

Aviso

Se o provedor for executado no Windows antes do Windows 10, não use TraceLoggingChannel. Para que um evento seja reconhecido como compatível com TraceLogging por decodificadores de eventos, ele deve ter o canal definido como o valor padrão (11) ou deve ter sido marcado como um evento TraceLogging pelo runtime do ETW durante EventWrite. Essa marcação de evento é habilitada chamando EventSetInformation para configurar o provedor como um provedor tracelogging. EventSetInformation no Windows 10 ou posterior habilita o suporte para eventos tracelogging independentemente do canal, mas versões anteriores do Windows exigem uma atualização do Windows antes de dar suporte à marcação de eventos tracelogging. Para eventos capturados em sistemas sem um EventSetInformation atualizado, o canal 11 é a única maneira de reconhecer um evento TraceLogging, portanto, eventos com outros canais podem não decodificar corretamente.

Log de Rastreamento e Log de Eventos

Na maioria dos casos, os desenvolvedores usam ETW baseado em manifesto para eventos que precisam ser registrados pelo Log de Eventos. O Log de Eventos destina-se principalmente a coletar eventos de baixo volume que provavelmente serão úteis para o administrador de um sistema. O ETW baseado em manifesto funciona bem para isso porque dá suporte a eventos cuidadosamente coletados (todos os eventos para o componente são descritos em um arquivo de manifesto) e porque ele dá suporte a cadeias de caracteres de mensagem localizáveis que podem ajudar o administrador a saber como reagir ao evento.

Embora os eventos tracelogging não tenham cadeias de caracteres de mensagem e geralmente não sejam coletados centralmente, TraceLogging ainda pode ser apropriado para alguns cenários de Log de Eventos. Por exemplo, embora os eventos que vão para os Logs do Windows (Aplicativo, Segurança, Instalação e Sistema) sempre tenham cadeias de caracteres de mensagem localizadas e sempre sejam úteis para o administrador do sistema, os eventos registrados nos Logs de Aplicativos e Serviços podem ser mais técnicos e podem registrar informações de diagnóstico. Ao gravar nos Logs de Aplicativos e Serviços, convém usar TraceLogging para simplificar o gerenciamento dos eventos registrados.

O uso de eventos traceLogging com o Log de Eventos do Windows é semelhante ao uso de eventos normais baseados em manifesto com o Log de Eventos. Você ainda precisa criar e registrar um manifesto para definir o provedor e os canais, mas não precisa definir os eventos individuais no manifesto:

  • Escreva um manifesto ETW que defina seu provedor e os canais do Log de Eventos. O provedor no manifesto deve usar o mesmo nome de provedor e guid do provedor (ID do provedor) que você usou em sua macro TRACELOGGING_DEFINE_PROVIDER . O manifesto não precisa incluir <event> nem <template> definições, pois os eventos tracelogging são autodescrevendo.
  • No processo de build do componente, use o Compilador de Mensagens (MC.exe) do SDK do Windows 10.0.22621 ou posterior para compilar o manifesto. Isso gerará os seguintes arquivos:
    • ManifestName.h: cabeçalho C/C++ que contém definições constantes. Isso definirá o ChannelSymbol e as constantes ChannelSymbol_KEYWORD que você precisará usar em seus eventos tracelogging. (Os nomes reais das constantes serão diferentes para cada canal.)
    • ManifestName.rc: script do Compilador de Recursos (RC.exe) que adiciona os dados BIN de manifesto a um arquivo binário (EXE, DLL ou SYS). Você precisará incluir esse script de recurso nos recursos de um dos arquivos binários em seu componente.
    • ManifestNameTEMP.BIN, MSG00001.bin: dados BIN de manifesto referenciados por ManifestName.rc.
  • #include o arquivo gerado ManifestName.h no código que precisa gerar eventos tracelogging. Isso definirá as constantes ChannelSymbol e ChannelSymbol_KEYWORD .
    • Se você especificou o atributo de símbolo na <channel> definição ou <importChannel> no manifesto, o nome de ChannelSymbol será o valor do atributo de símbolo . Caso contrário, ChannelSymbol será ProviderSymbol_CHANNEL_ChannelName (ou seja, ele usará o símbolo do elemento <provider> e o nome do elemento <channel> ou <importChannel> ).
    • O nome de ChannelSymbol_KEYWORD é o nome de ChannelSymbol seguido por _KEYWORD.
    • A constante ChannelSymbol_KEYWORD é gerada apenas por MC.exe 10.0.22621 ou posterior.
  • Cada evento TraceLogging que deve ir para o Log de Eventos deve usarTraceLoggingChannel(ChannelSymbol), TraceLoggingKeyword(ChannelSymbol_KEYWORD)para definir o canal e palavra-chave para o evento. Por exemplo, se o símbolo do meu canal for MY_CHANNEL, eu adicionaria TraceLoggingChannel(MY_CHANNEL), TraceLoggingKeyword(MY_CHANNEL_KEYWORD) como parâmetros à TraceLoggingWrite macro para o evento.
  • Para que o Log de Eventos reconheça seu provedor, as informações do manifesto devem ser incluídas nos recursos de um módulo (arquivo DLL, EXE ou SYS) que será instalado no sistema de destino.
  • Para que o Log de Eventos receba eventos de seu provedor, você deve registrar seu manifesto no sistema de destino usando wevtutil im ManifestFile.man /rf:PathToModuleWithResources.dll durante a instalação do componente. Você também deve cancelar o registro do manifesto usando wevtutil um ManifestFile.man durante a desinstalação do componente.

Importante

Se o provedor estiver registrado no Log de Eventos, todos os eventos gerados pelo provedor deverão ter um palavra-chave diferente de zero especificado com TraceLoggingKeyword, mesmo que o evento não se destine ao Log de Eventos. Eventos com palavra-chave 0 não podem ser filtrados com eficiência e serão entregues ao Log de Eventos apenas para serem descartados. Se o Log de Eventos estiver escutando eventos do seu provedor, qualquer evento com Palavra-chave 0 aumentará desnecessariamente a sobrecarga do Log de Eventos.

Exemplo de um evento TraceLogging para Log de Eventos:

TraceLoggingWrite(
    g_hMyProvider,
    "MyWarningEventName",
    TraceLoggingChannel(MY_CHANNEL),         // constant from the MC-generated header
    TraceLoggingKeyword(MY_CHANNEL_KEYWORD), // constant from the MC-generated header
    TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
    TraceLoggingKeyword(MyEventCategories), // Additional keywords are ok.
    TraceLoggingHResult(errorCode, "Error"));

Palavras-chave especificadas pelo usuário adicionais podem ser adicionadas a eventos, se apropriado, usando vários argumentos TraceLoggingKeyword ou especificando várias palavras-chave em um único argumento TraceLoggingKeyword , por exemplo. TraceLoggingKeyword(MY_CHANNEL_KEYWORD | MY_OTHER_KEYWORD).

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows 10 [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows Server 2012 R2
Plataforma de Destino Windows
Cabeçalho traceloggingprovider.h

Confira também

EVENT_DESCRIPTOR

TraceLoggingWrite

Macros de wrapper traceLogging