Início rápido do TraceLogging C/C++

A seção a seguir descreve as etapas básicas necessárias para adicionar TraceLogging ao código de modo de usuário C/C++.

Pré-requisitos

• Microsoft Visual Studio 2013 ou posterior.
• O Windows 10 Software Development Kit (SDK) é necessário para escrever um provedor de modo de usuário.
• O Windows Driver Kit (WDK) para Windows 10 é necessário para escrever um provedor de modo kernel.

Para coletar e decodificar eventos desses exemplos, você precisará iniciar um rastreamento usando uma ferramenta como tracelog ou traceview, executar o exemplo, parar o rastreamento usando uma ferramenta como tracelog ou traceview e decodificar o rastreamento usando uma ferramenta de decodificação como tracefmt ou traceview. Por exemplo, se meu provedor foi definido usando GUID {0205c616-cf97-5c11-9756-56a2cee02ca7}, eu poderia exibir os eventos desses exemplos usando ferramentas do SDK do Windows tracelog e tracefmt da seguinte maneira:

• tracelog -start MyTraceSession -f MyTraceFile.etl -guid #0205c616-cf97-5c11-9756-56a2cee02ca7
• Execute o exemplo.
• tracelog -stop MyTraceSession
• tracefmt -o MyTraceFile.txt MyTraceFile.etl
• notepad MyTraceFile.txt

SimpleTraceLoggingExample.h

Este cabeçalho de exemplo inclui as APIs TraceLogging e forward declara o identificador do provedor que será usado para registrar eventos. Qualquer classe que deseje usar o TraceLogging incluirá esse cabeçalho e poderá iniciar o log.

#pragma once

#include <windows.h> // Definitions required by TraceLoggingProvider.h
#include <TraceLoggingProvider.h> // The C/C++ TraceLogging API

// Forward-declare the g_hMyComponentProvider variable that you will use for tracing in this component
TRACELOGGING_DECLARE_PROVIDER(g_hMyComponentProvider);

O arquivo de cabeçalho inclui TraceLoggingProvider.h que define a API C/C++ TraceLogging. Você deve incluir windows.h primeiro porque ele define constantes usadas por TraceLoggingProvider.h.

O arquivo de cabeçalho forward declara o identificador do provedor g_hMyComponentProvider que você passará para as APIs TraceLogging para registrar eventos. Esse identificador precisa estar acessível a qualquer código que deseje usar o TraceLogging.

TRACELOGGING_DECLARE_PROVIDER é uma macro que cria um identificador de extern const TraceLoggingHProvider usando o nome que você fornece, que no exemplo acima é g_hMyComponentProvider. Você alocará a variável de identificador do provedor real em um arquivo de código.

SimpleTraceLoggingExample.cpp

O exemplo a seguir registra o provedor, registra um evento e cancela o registro do provedor.

#include "SimpleTraceLoggingExample.h"

// Define a handle to a TraceLogging provider
TRACELOGGING_DEFINE_PROVIDER(
    g_hMyComponentProvider,
    "SimpleTraceLoggingProvider",
    // {0205c616-cf97-5c11-9756-56a2cee02ca7}
    (0x0205c616,0xcf97,0x5c11,0x97,0x56,0x56,0xa2,0xce,0xe0,0x2c,0xa7));

void main()
{

    char sampleValue[] = "Sample value";

    // Register the provider
    TraceLoggingRegister(g_hMyComponentProvider);

    // Log an event
    TraceLoggingWrite(g_hMyComponentProvider, // handle to my provider
        "HelloWorldTestEvent",              // Event Name that should uniquely identify your event.
        TraceLoggingValue(sampleValue, "TestMessage")); // Field for your event in the form of (value, field name).

    // Stop TraceLogging and unregister the provider
    TraceLoggingUnregister(g_hMyComponentProvider);
}

O exemplo acima inclui SimpleTraceLoggingExample.h que contém a variável de provedor global que seu código usará para registrar eventos.

A macro TRACELOGGING_DEFINE_PROVIDER aloca armazenamento e define a variável de identificador do provedor. O nome da variável que você fornece a essa macro deve corresponder ao nome usado na macro TRACELOGGING_DECLARE_PROVIDER no arquivo de cabeçalho.

Registrar o identificador do provedor

Antes de poder usar o identificador do provedor para registrar eventos, você deve chamar TraceLoggingRegister para registrar o identificador do provedor. Isso geralmente é feito em main() ou DLLMain(), mas pode ser feito a qualquer momento, desde que anteceda qualquer tentativa de registrar um evento. Se você registrar um evento antes de registrar o identificador do provedor, nenhum erro ocorrerá, mas o evento não será registrado. O código a seguir do exemplo acima registra o identificador do provedor.

// Define the GUID to use in TraceLoggingProviderRegister
TRACELOGGING_DEFINE_PROVIDER(
    g_hMyComponentProvider,
    "SimpleTraceLoggingProvider",
    // {0205c616-cf97-5c11-9756-56a2cee02ca7}
    (0x0205c616,0xcf97,0x5c11,0x97,0x56,0x56,0xa2,0xce,0xe0,0x2c,0xa7));

void main()
{
    char sampleValue[] = "Sample value";

    // Register the provider
    TraceLoggingRegister(g_hMyComponentProvider);

Registar um evento de Tracelogging

Depois que o provedor é registrado, o código a seguir registra um evento simples.

    // Log an event
    TraceLoggingWrite(g_hMyComponentProvider, // handle to my provider
        "HelloWorldTestEvent",              // Event Name that should uniquely identify your event.
        TraceLoggingValue(sampleValue, "TestMessage")); // Field for your event in the form of (value, field name).

A macroTraceLoggingWrite aceita até noventa e nove argumentos. O nome do evento é armazenado no formato UTF-8. Você não deve usar caracteres '\0' incorporados no nome do evento ou nos nomes dos campos. Não há outros limites para caracteres permitidos, embora alguns decodificadores de eventos ou processadores de eventos possam ter suas próprias limitações.

Cada argumento após o nome do evento deve ser encapsulado dentro de um TraceLogging Wrapper Macro. Se você estiver usando C++, poderá usar a macro wrapper TraceLoggingValue para deduzir automaticamente o tipo do argumento. Se você estiver escrevendo em C ou se quiser mais controle sobre o tipo de campo, você deve usar macros de campo específicas do tipo, como TraceLoggingInt32, TraceLoggingUnicodeString, TraceLoggingString, etc.

Além de registar eventos únicos, pode também agrupar eventos por atividade usando as macros TraceLoggingWriteActivity ou TraceLoggingWriteStart/TraceLoggingWriteStop encontradas em TraceLoggingActivity.h. As atividades correlacionam eventos e são úteis para cenários que têm um início e um fim. Por exemplo, você pode usar uma atividade para medir um cenário que começa com a inicialização de um aplicativo, inclui o tempo necessário para que a tela inicial fique disponível e termine quando a tela inicial do aplicativo se torna visível.

As atividades capturam eventos individuais e aninham outras atividades que ocorrem entre o início e o fim dessa atividade. As atividades têm alcance por processo e devem ser passadas de thread para thread para corretamente aninhar eventos multithread.

O escopo de um identificador de provedor é limitado ao módulo (arquivo DLL, EXE ou SYS) no qual ele é definido. A alça não deve ser passada para outras DLLs. Se uma macro TraceLoggingWrite for invocada em A.DLL usando um identificador de provedor definido em B.DLL, isso pode causar problemas. A maneira mais segura e eficiente de atender a esse requisito é sempre referenciar diretamente o identificador do provedor global e nunca passar o identificador do provedor como um parâmetro.

Cancelar o registro do provedor

Antes de descarregar o componente, você deve cancelar o registro do provedor TraceLogging. Isso é especialmente importante para DLLs e drivers. Uma falha é provável se uma DLL ou um driver for descarregado sem cancelar o registro do provedor.

O código a seguir cancela o registro do provedor:

// Stop TraceLogging and unregister the provider
TraceLoggingUnregister(g_hMyComponentProvider);

Compatibilidade

Dependendo de sua configuração, TraceLoggingProvider.h pode ser compatível com versões anteriores (o programa resultante será executado no Windows Vista ou posterior), ou pode ser otimizado para versões posteriores do sistema operacional. TraceLoggingProvider.h usa WINVER (modo de usuário) e NTDDI_VERSION (modo kernel) para determinar se ele deve ser compatível com versões anteriores do sistema operacional ou ser otimizado para versões mais recentes do sistema operacional.

Para o modo de usuário, se você incluir <windows.h> antes de definir o WINVER, <windows.h> definirá o WINVER para a versão padrão do sistema operacional de destino do SDK. Se WINVER estiver definido como 0x602 ou superior, TraceLoggingProvider.h otimiza seu comportamento para o Windows 8 ou posterior e seu aplicativo não será executado em versões anteriores do Windows. Se você precisar que seu programa seja executado no Vista ou Windows 7, certifique-se de definir WINVER para o valor apropriado antes de incluir <windows.h>.

Da mesma forma, se você incluir <wdm.h> antes de definir NTDDI_VERSION, <wdm.h> definirá NTDDI_VERSION como um valor padrão. Se NTDDI_VERSION estiver definido como 0x06040000 ou superior, TraceLoggingProvider.h otimiza seu comportamento para o Windows 10 e seu driver não funcionará em versões anteriores do Windows.

Esse comportamento pode ser controlado configurando TLG_HAVE_EVENT_SET_INFORMATION antes de incluir TraceLoggingProvider.h. Consulte os comentários no cabeçalho do TraceLoggingProvider.h para obter detalhes sobre a macro TLG_HAVE_EVENT_SET_INFORMATION.

Resumo e próximas etapas

Para ver como capturar e exibir dados TraceLogging usando as Ferramentas de Desempenho do Windows (WPT), consulte Gravar e exibir eventos TraceLogging.

Consulte C/C++ Tracelogging Examples para obter mais exemplos de C++ TraceLogging.