macro TRACELOGGING_DEFINE_PROVIDER (traceloggingprovider.h)

Define um identificador para um provedor traceLogging.

Sintaxe

void TRACELOGGING_DEFINE_PROVIDER(
  [in]            handleVariable,
  [in]            providerName,
  [in]            providerId,
  [in, optional]  __VA_ARGS__
);

Parâmetros

[in] handleVariable

O nome a ser usado para o identificador do provedor, usando as convenções de nomenclatura do componente para variáveis globais, por exemplo MyComponentLog , ou g_hMyProvider.

[in] providerName

Um literal de cadeia de caracteres com o nome do provedor TraceLogging. Esse nome deve ser específico para sua organização e componente para que ele não entre em conflito com provedores de outros componentes. Essa cadeia de caracteres de nome será incluída em cada evento ETW gerado pelo provedor, portanto, tente usar um nome relativamente curto. Por exemplo, você pode usar um nome como "MyCompany.MyComponent" ou "MyCompany.MyOrganization.MyComponent".

Deve ser um literal de cadeia de caracteres. Não use uma variável.

[in] providerId

O GUID de controle ETW para o provedor, especificado como uma lista separada por vírgulas de 11 inteiros entre parênteses. Por exemplo, o GUID {ce5fa4ea-ab00-5402-8b76-9f76ac858fb5} seria expresso como (0xce5fa4ea,0xab00,0x5402,0x8b,0x76,0x9f,0x76,0xac,0x85,0x8f,0xb5).

Embora qualquer GUID exclusivo possa ser usado para a ID do provedor, a Microsoft recomenda usar um GUID gerado com base no nome do provedor usando o algoritmo de hash de nome ETW. Consulte abaixo para obter informações sobre como gerar a ID do provedor.

[in, optional] __VA_ARGS__

Parâmetros opcionais para o provedor. A maioria dos provedores não precisa especificar parâmetros opcionais.

Se você quiser que seu provedor seja associado a um grupo de provedores ETW, adicione a macro TraceLoggingOptionGroup para especificar o GUID do grupo do provedor. Caso contrário, não especifique nenhum __VA_ARGS__ parâmetro.

Retornar valor

Nenhum

Comentários

Um provedor traceLogging é uma conexão pela qual os eventos podem ser enviados ao ETW. A TRACELOGGING_DEFINE_PROVIDER macro define um provedor TraceLogging e cria um identificador que pode ser usado para acessá-lo. Ele também registra informações do provedor, como o nome do provedor e o GUID.

Essa macro deve ser invocada em um arquivo .c ou .cpp para definir o identificador de um provedor traceLogging. Por exemplo, se meu provedor for nomeado MyCompany.MyComponent e o GUID de controle for {ce5fa4ea-ab00-5402-8b76-9f76ac858fb5} , eu definiria o provedor adicionando o seguinte código a um dos arquivos .c ou .cpp no meu 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));

A macro acima TRACELOGGING_DEFINE_PROVIDER pode ser considerada como definindo uma g_hMyProvider constante de identificador de provedor, semelhante ao código como:

const TraceLoggingHProvider g_hMyProvider = ...;

O identificador resultante tem escopo de módulo e pode ser usado em qualquer lugar dentro do módulo EXE, DLL ou SYS no qual ele é definido. Use a macro TRACELOGGING_DECLARE_PROVIDER conforme necessário (por exemplo, em um cabeçalho) para encaminhar e declarar o identificador para que ele possa ser usado por outros arquivos .c ou .cpp em seu componente.

Quando um componente começar a ser executado, o provedor estará em um estado não registrado. Todas as tentativas de usá-lo para gerar eventos serão silenciosamente ignoradas. Antes de responder a chamadas de gravação, você precisa registrar o provedor usando TraceLoggingRegister. Isso normalmente é feito durante a inicialização do componente, por exemplo, em main, wmain, WinMain, DllMain(DLL_PROCESS_ATTACH)ou DriverEntry. No desligamento do componente, cancele o registro do provedor chamando TraceLoggingUnregister.

Nome e ID do Provedor

O ETW executa filtragem e roteamento de eventos usando a ID do provedor (também chamada de GUID do Provedor ou GUID de Controle). Por exemplo, se você tiver um provedor chamado MyCompany.MyComponent com a ID {ce5fa4ea-ab00-5402-8b76-9f76ac858fb5} do provedor, poderá iniciar um rastreamento para capturar eventos desse provedor usando um comando de rastreamento como tracelog -start MySessionName -f MySession.etl -guid #ce5fa4ea-ab00-5402-8b76-9f76ac858fb5.

Todos os provedores ETW são identificados pelo nome do provedor e pela ID do provedor. O nome e a ID precisam ser exclusivos para que não entrem em conflito com outros provedores. Além disso, o nome e a ID devem ser vinculados: depois que um nome específico é usado com uma ID específica para um provedor ETW, esse nome não deve ser usado com nenhuma outra ID e essa ID não deve ser usada com nenhum outro nome.

A ID do provedor pode ser qualquer GUID exclusivo, tal gerado usando a ferramenta do guidgen SDK ou https://uuidgen.org. No entanto, em vez de usar um GUID gerado aleatoriamente para a ID do provedor, a Microsoft recomenda gerar a ID do provedor do nome do provedor usando o algoritmo de hash de nome ETW descrito abaixo. Isso oferece vários benefícios: é mais fácil lembrar apenas o nome; a ID e o nome são vinculados automaticamente; ferramentas como tracelog, traceview, EventSource e WPR têm suporte especial para provedores que usam IDs geradas usando esse algoritmo.

Por exemplo, se você tiver um provedor chamado MyCompany.MyComponent com a ID {ce5fa4ea-ab00-5402-8b76-9f76ac858fb5} do provedor, poderá iniciar um rastreamento para capturar eventos desse provedor usando um comando de rastreamento como tracelog -start MySessionName -f MySession.etl -guid *MyCompany.MyComponent. Isso funciona porque a ID {ce5fa4ea-ab00-5402-8b76-9f76ac858fb5} do provedor foi gerada com o hash do nome MyCompany.MyComponentdo provedor, portanto, a ferramenta tracefmt considera -guid *MyCompany.MyComponent equivalente a -guid #ce5fa4ea-ab00-5402-8b76-9f76ac858fb5.

Você pode usar o PowerShell para obter a ID do provedor para um nome de provedor específico usando o algoritmo de hash de nome ETW por meio da classe EventSource :

[System.Diagnostics.Tracing.EventSource]::new("MyCompany.MyComponent").Guid

Resultados:

Guid
----
ce5fa4ea-ab00-5402-8b76-9f76ac858fb5

Em C#, o algoritmo de hash de nome ETW pode ser implementado da seguinte maneira:

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);
    }
}

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
    "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

Confira também

TRACELOGGING_DECLARE_PROVIDER

TraceLoggingWrite