Macro TraceLoggingChannel (traceloggingprovider.h)

Macro contenedora traceLogging que establece el canal para el evento.

La mayoría de los eventos traceLogging no necesitan cambiar el canal predeterminado del evento y no deben usar TraceLoggingChannel.

Sintaxis

void TraceLoggingChannel(
  [in]  eventChannel
);

Parámetros

[in] eventChannel

Canal al que se debe registrar el evento. Se trata de un valor entero comprendido entre 0 y 255.

Consulte EVENT_DESCRIPTOR para obtener más información sobre el canal de eventos.

Valor devuelto

None

Observaciones

TraceLoggingChannel(eventChannel) se puede usar como parámetro para una invocación de una macro TraceLoggingWrite . La mayoría de los eventos traceLogging no necesitan cambiar el canal predeterminado del evento y no deben usar TraceLoggingChannel.

El parámetro eventChannel debe ser una constante en tiempo de compilación de 0 a 255. Si no se proporciona ningún TraceLoggingChannel(n) argumento, el canal predeterminado es 11 (WINEVENT_CHANNEL_TRACELOGGING), lo que indica que se trata de un evento TraceLogging normal. Si se proporcionan varios TraceLoggingChannel(n) argumentos, se usará el valor del último TraceLoggingChannel(n) parámetro.

Los canales se usan en escenarios avanzados de seguimiento de eventos para Windows (ETW). Entre ellas se incluyen la escritura en consumidores de eventos definidos por el sistema, como el registro de eventos de Windows.

Advertencia

Si el proveedor se ejecutará en Windows anterior a Windows 10, no use TraceLoggingChannel. Para que un evento sea reconocido como compatible con TraceLogging por los descodificadores de eventos, debe tener el canal establecido en el valor predeterminado (11) o debe haberse marcado como un evento TraceLogging por el tiempo de ejecución de ETW durante EventWrite. Este marcado de eventos está habilitado llamando a EventSetInformation para configurar el proveedor como proveedor de TraceLogging. EventSetInformation en Windows 10 o posterior permite la compatibilidad con eventos traceLogging independientemente del canal, pero las versiones anteriores de Windows requieren una actualización de Windows antes de admitir el marcado de eventos tracelogging. En el caso de los eventos capturados en sistemas sin eventSetInformation actualizado, el canal 11 es la única manera de reconocer un evento TraceLogging, por lo que es posible que los eventos con otros canales no se descodifiquen correctamente.

Registro de seguimiento y registro de eventos

En la mayoría de los casos, los desarrolladores usan ETW basado en manifiestos para eventos que el registro de eventos debe registrar. El registro de eventos está pensado principalmente para recopilar eventos de bajo volumen que probablemente sean útiles para el administrador de un sistema. ETW basado en manifiesto funciona bien para esto porque admite eventos mantenidos cuidadosamente (todos los eventos del componente se describen en un archivo de manifiesto) y porque admite cadenas de mensajes localizables que pueden ayudar al administrador a saber cómo reaccionar al evento.

Aunque los eventos TraceLogging no tienen cadenas de mensaje y, por lo general, no están mantenidos de forma centralizada, TraceLogging todavía puede ser adecuado para algunos escenarios de registro de eventos. Por ejemplo, aunque los eventos que van a los registros de Windows (aplicación, seguridad, configuración y sistema) siempre deben tener cadenas de mensaje localizadas y siempre deben ser útiles para el administrador del sistema, los eventos registrados en los registros de aplicaciones y servicios pueden ser más técnicos y pueden registrar información de diagnóstico. Al escribir en los registros de aplicaciones y servicios, es posible que desee usar TraceLogging para simplificar la administración de los eventos registrados.

El uso de eventos traceLogging con el registro de eventos de Windows es similar al uso de eventos normales basados en manifiestos con registro de eventos. Todavía tiene que crear y registrar un manifiesto para definir el proveedor y los canales, pero no es necesario definir los eventos individuales en el manifiesto:

  • Escriba un manifiesto ETW que defina el proveedor y los canales del registro de eventos. El proveedor del manifiesto debe usar el mismo nombre de proveedor y guid del proveedor (id. de proveedor) que usó en la macro de TRACELOGGING_DEFINE_PROVIDER . El manifiesto no necesita incluir <event> ni <template> definiciones, ya que los eventos TraceLogging se describen automáticamente.
  • En el proceso de compilación del componente, use el compilador de mensajes (MC.exe) de Windows SDK 10.0.22621 o posterior para compilar el manifiesto. Esto generará los siguientes archivos:
    • ManifestName.h: encabezado de C/C++ que contiene definiciones de constantes. Esto definirá channelSymbol y las constantes ChannelSymbol_KEYWORD que deberá usar en los eventos tracelogging. (Los nombres reales de las constantes serán diferentes para cada canal).
    • ManifestName.rc: script del compilador de recursos (RC.exe) que agrega los datos bin del manifiesto a un archivo binario (EXE, DLL o SYS). Tendrá que incluir este script de recursos en los recursos de uno de los archivos binarios del componente.
    • ManifestNameTEMP.BIN, MSG00001.bin: datos bin de manifiesto a los que hace ManifestName.rcreferencia .
  • #include el archivo generado ManifestName.h en el código que necesita generar eventos traceLogging. Esto definirá las constantes ChannelSymbol y ChannelSymbol_KEYWORD .
    • Si especificó el atributo de símbolo en la <channel> definición o <importChannel> en el manifiesto, el nombre de ChannelSymbol será el valor del atributo de símbolo . De lo contrario, ChannelSymbol será ProviderSymbol_CHANNEL_ChannelName (es decir, usará el símbolo del <provider> elemento y el nombre del <channel> elemento o <importChannel> ).
    • El nombre de ChannelSymbol_KEYWORD es el nombre de ChannelSymbol seguido de _KEYWORD.
    • La constante ChannelSymbol_KEYWORD solo se genera en MC.exe 10.0.22621 o posterior.
  • Cada evento TraceLogging que vaya al registro de eventos debe usarTraceLoggingChannel(ChannelSymbol), TraceLoggingKeyword(ChannelSymbol_KEYWORD) para establecer el canal y la palabra clave para el evento. Por ejemplo, si el símbolo de mi canal es MY_CHANNEL, agregaría TraceLoggingChannel(MY_CHANNEL), TraceLoggingKeyword(MY_CHANNEL_KEYWORD) como parámetros a la TraceLoggingWrite macro para el evento.
  • Para que el registro de eventos reconozca a su proveedor, la información del manifiesto debe incluirse en los recursos de un módulo (archivo DLL, EXE o SYS) que se instalará en el sistema de destino.
  • Para que el registro de eventos reciba eventos del proveedor, debe registrar el manifiesto en el sistema de destino mediante wevtutil im ManifestFile.man /rf:PathToModuleWithResources.dll durante la instalación del componente. También debe anular el registro del manifiesto mediante wevtutil um ManifestFile.man durante la desinstalación de componentes.

Importante

Si el proveedor está registrado con el registro de eventos, todos los eventos generados por el proveedor deben tener una palabra clave distinta de cero especificada con TraceLoggingKeyword, incluso si el evento no está pensado para el registro de eventos. Los eventos con la palabra clave 0 no se pueden filtrar de forma eficaz y solo se entregarán al registro de eventos para que se descarten. Si el registro de eventos escucha eventos de su proveedor, cualquier evento con la palabra clave 0 aumentará innecesariamente la sobrecarga del registro de eventos.

Ejemplo de un evento TraceLogging para el registro 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"));

Las palabras clave adicionales especificadas por el usuario se pueden agregar a eventos si procede, ya sea mediante varios argumentos TraceLoggingKeyword o especificando varias palabras clave en un único argumento TraceLoggingKeyword , por ejemplo TraceLoggingKeyword(MY_CHANNEL_KEYWORD | MY_OTHER_KEYWORD), .

Requisitos

Requisito Value
Cliente mínimo compatible Windows 10 [solo aplicaciones de escritorio]
Servidor mínimo compatible Windows Server 2012 R2
Plataforma de destino Windows
Encabezado traceloggingprovider.h

Consulte también

EVENT_DESCRIPTOR

TraceLoggingWrite

Macros contenedoras de TraceLogging