TRACELOGGING_DEFINE_PROVIDER macro (traceloggingprovider.h)
Define un identificador para un proveedor de TraceLogging.
Sintaxis
void TRACELOGGING_DEFINE_PROVIDER(
[in] handleVariable,
[in] providerName,
[in] providerId,
[in, optional] __VA_ARGS__
);
Parámetros
[in] handleVariable
Nombre que se va a usar para el identificador del proveedor, mediante las convenciones de nomenclatura del componente para variables globales, por ejemplo MyComponentLog , o g_hMyProvider.
[in] providerName
Literal de cadena con el nombre del proveedor TraceLogging. Este nombre debe ser específico de su organización y componente para que no entre en conflicto con proveedores de otros componentes. Esta cadena de nombre se incluirá dentro de cada evento ETW generado por el proveedor, por lo que intente usar un nombre relativamente corto. Por ejemplo, puede usar un nombre como "MyCompany.MyComponent" o "MyCompany.MyOrganization.MyComponent".
Debe ser un literal de cadena. No use una variable.
[in] providerId
Guid de control ETW para el proveedor, especificado como una lista separada por comas de 11 enteros entre paréntesis. Por ejemplo, el GUID {ce5fa4ea-ab00-5402-8b76-9f76ac858fb5} se expresaría como (0xce5fa4ea,0xab00,0x5402,0x8b,0x76,0x9f,0x76,0xac,0x85,0x8f,0xb5).
Aunque se puede usar cualquier GUID único para el identificador de proveedor, Microsoft recomienda usar un GUID generado a partir del nombre del proveedor mediante el algoritmo de hash de nombres ETW. Consulte a continuación para obtener información sobre cómo generar el identificador de proveedor.
[in, optional] __VA_ARGS__
Parámetros opcionales para el proveedor. La mayoría de los proveedores no necesitan especificar ningún parámetro opcional.
Si desea que el proveedor esté asociado a un grupo de proveedores ETW, agregue la macro TraceLoggingOptionGroup para especificar el GUID del grupo del proveedor. De lo contrario, no especifique ningún __VA_ARGS__ parámetro.
Valor devuelto
None
Observaciones
Un proveedor traceLogging es una conexión por la que se pueden enviar eventos a ETW. La TRACELOGGING_DEFINE_PROVIDER macro define un proveedor tracelogging y crea un identificador que se puede usar para acceder a él. También registra información del proveedor, como el nombre y el GUID del proveedor.
Esta macro debe invocarse en un archivo .c o .cpp para definir el identificador de un proveedor traceLogging. Por ejemplo, si mi proveedor se llama MyCompany.MyComponent y el GUID de control es {ce5fa4ea-ab00-5402-8b76-9f76ac858fb5} entonces, definiría el proveedor agregando el código siguiente a uno de los archivos .c o .cpp en mi componente:
TRACELOGGING_DEFINE_PROVIDER( // defines g_hProvider
g_hProvider, // Name of the provider handle
"MyCompany.MyComponent", // Human-readable name for the provider
// {ce5fa4ea-ab00-5402-8b76-9f76ac858fb5}
(0xce5fa4ea,0xab00,0x5402,0x8b,0x76,0x9f,0x76,0xac,0x85,0x8f,0xb5));
La macro anterior TRACELOGGING_DEFINE_PROVIDER se puede considerar como definir una g_hMyProvider constante de identificador de proveedor, similar a la de código como:
const TraceLoggingHProvider g_hMyProvider = ...;
El identificador resultante tiene ámbito de módulo y se puede usar en cualquier lugar dentro del módulo EXE, DLL o SYS en el que se define. Use la macro TRACELOGGING_DECLARE_PROVIDER según sea necesario (por ejemplo, en un encabezado) para reenviar el identificador para que otros archivos .c o .cpp puedan usarlos en el componente.
Cuando un componente comienza a ejecutarse, el proveedor estará en un estado no registrado.
Cualquier intento de usarlo para generar eventos se omitirá de forma silenciosa. Para poder responder a cualquier llamada de escritura, debe registrar el proveedor mediante TraceLoggingRegister. Esto se realiza normalmente durante el inicio del componente, por ejemplo, en main, wmain, DllMain(DLL_PROCESS_ATTACH)WinMain, o DriverEntry. En el apagado del componente, anule el registro del proveedor mediante una llamada a TraceLoggingUnregister.
Nota
El identificador de proveedor definido por TRACELOGGING_DEFINE_PROVIDER tiene como ámbito el módulo. El identificador se puede usar según sea necesario en el archivo EXE, DLL o SYS, pero no debe usarse fuera del ámbito del módulo, es decir, no debe pasarse a otros archivos DLL en el mismo proceso. Cada archivo EXE, DLL o SYS debe usar su propio identificador de proveedor y debe realizar su propio registro y registro. En las compilaciones de depuración, se desencadenará una aserción si intenta escribir mediante un identificador de proveedor desde otro módulo.
Nombre e identificador del proveedor
ETW realiza el filtrado de eventos y el enrutamiento mediante el identificador de proveedor (también denominado GUID del proveedor o GUID de control). Por ejemplo, si tiene un proveedor denominado MyCompany.MyComponent con el identificador {ce5fa4ea-ab00-5402-8b76-9f76ac858fb5} de proveedor, puede iniciar un seguimiento para capturar eventos de este proveedor mediante un comando tracelog como tracelog -start MySessionName -f MySession.etl -guid #ce5fa4ea-ab00-5402-8b76-9f76ac858fb5.
Todos los proveedores ETW se identifican mediante el nombre del proveedor y el identificador del proveedor. Tanto el nombre como el identificador deben ser únicos para que no entren en conflicto con otros proveedores. Además, el nombre y el identificador deben estar vinculados: una vez que se usa un nombre determinado con un identificador determinado para un proveedor ETW, ese nombre no debe usarse con ningún otro identificador y ese identificador no debe usarse con ningún otro nombre.
El identificador de proveedor puede ser cualquier GUID único, como uno generado mediante la guidgen herramienta sdk o https://uuidgen.org. Sin embargo, en lugar de usar un GUID generado aleatoriamente para el identificador de proveedor, Microsoft recomienda generar el identificador de proveedor a partir del nombre del proveedor mediante el algoritmo hash de nombres ETW que se describe a continuación. Esto proporciona varias ventajas: es más fácil recordar solo el nombre; el identificador y el nombre se vinculan automáticamente; las herramientas como tracelog, traceview, EventSource y WPR tienen compatibilidad especial con proveedores que usan identificadores generados mediante este algoritmo.
Por ejemplo, si tiene un proveedor denominado MyCompany.MyComponent con el identificador {ce5fa4ea-ab00-5402-8b76-9f76ac858fb5} de proveedor, puede iniciar un seguimiento para capturar eventos de este proveedor mediante un comando tracelog como tracelog -start MySessionName -f MySession.etl -guid *MyCompany.MyComponent.
Esto funciona porque el identificador {ce5fa4ea-ab00-5402-8b76-9f76ac858fb5} de proveedor se generó mediante el algoritmo hash del nombre MyCompany.MyComponentdel proveedor , por lo que la herramienta tracefmt considera -guid *MyCompany.MyComponent que es equivalente a -guid #ce5fa4ea-ab00-5402-8b76-9f76ac858fb5.
Puede usar PowerShell para obtener el identificador de proveedor de un nombre de proveedor determinado mediante el algoritmo de hash de nombres ETW a través de la clase EventSource :
[System.Diagnostics.Tracing.EventSource]::new("MyCompany.MyComponent").Guid
Resultados:
Guid
----
ce5fa4ea-ab00-5402-8b76-9f76ac858fb5
En C#, el algoritmo de hash de nombres ETW se puede implementar de la siguiente manera:
static Guid ProviderIdFromName(string name)
{
var signature = new byte[] {
0x48, 0x2C, 0x2D, 0xB2, 0xC3, 0x90, 0x47, 0xC8,
0x87, 0xF8, 0x1A, 0x15, 0xBF, 0xC1, 0x30, 0xFB };
var nameBytes = System.Text.Encoding.BigEndianUnicode.GetBytes(name.ToUpperInvariant());
using (var sha1 = new System.Security.Cryptography.SHA1Managed())
{
sha1.TransformBlock(signature, 0, signature.Length, null, 0);
sha1.TransformFinalBlock(nameBytes, 0, nameBytes.Length);
var hash = sha1.Hash;
Array.Resize(ref hash, 16);
hash[7] = (byte)((hash[7] & 0x0F) | 0x50);
return new Guid(hash);
}
}
Ejemplos
#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
"MyCompany.MyComponent", // Human-readable name for the provider
// {ce5fa4ea-ab00-5402-8b76-9f76ac858fb5}
(0xce5fa4ea,0xab00,0x5402,0x8b,0x76,0x9f,0x76,0xac,0x85,0x8f,0xb5));
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
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Windows Vista [aplicaciones de escritorio | aplicaciones para UWP] |
| Servidor mínimo compatible | Windows Server 2008 [aplicaciones de escritorio | aplicaciones para UWP] |
| Plataforma de destino | Windows |
| Encabezado | traceloggingprovider.h |