Compartir a través de

Inicio rápido de C/C++ de registro de seguimiento

  • Artículo

En la sección siguiente se describen los pasos básicos necesarios para agregar TraceLogging al código en modo de usuario de C/C++.

Requisitos previos

  • Microsoft Visual Studio 2013 o posterior.
  • Windows 10 Kit de desarrollo de software (SDK) es necesario para escribir un proveedor en modo de usuario.
  • El Kit de controladores de Windows (WDK) para Windows 10 es necesario para escribir un proveedor de modo kernel.

Importante

Para evitar errores del enlazador para funciones , EventWriteTransfero EventUnregister sin resolverEventRegister, vincule con advapi32.lib al compilar estos ejemplos.

Para recopilar y descodificar eventos de estos ejemplos, deberá iniciar un seguimiento mediante una herramienta como tracelog o traceview, ejecutar el ejemplo, detener el seguimiento mediante una herramienta como tracelog o traceview, y descodificar el seguimiento mediante una herramienta de descodificación como tracefmt o traceview. Por ejemplo, si mi proveedor se definió mediante GUID {0205c616-cf97-5c11-9756-56a2cee02ca7}, podría ver los eventos de estos ejemplos mediante el seguimiento de las herramientas de Windows SDK y tracefmt de la siguiente manera:

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

SimpleTraceLoggingExample.h

Este encabezado de ejemplo incluye las API de registro de seguimiento y reenvía declara el identificador del proveedor que se usará para registrar eventos. Cualquier clase que desee usar TraceLogging incluirá este encabezado y, a continuación, podrá iniciar el registro.

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

El archivo de encabezado incluye TraceLoggingProvider.h que define la API traceLogging de C/C++. Debe incluir windows.h primero porque define constantes usadas por TraceLoggingProvider.h.

El archivo de encabezado reenvía declara el identificador g_hMyComponentProvider del proveedor que pasará a las API de registro de seguimiento para registrar eventos. Este identificador debe ser accesible para cualquier código que desee usar TraceLogging.

TRACELOGGING_DECLARE_PROVIDER es una macro que crea un extern const TraceLoggingHProvider identificador con el nombre que se proporciona, que en el ejemplo anterior es g_hMyComponentProvider. Asignará la variable de identificador del proveedor real en un archivo de código.

SimpleTraceLoggingExample.cpp

En el ejemplo siguiente se registra el proveedor, se registra un evento y se anula el registro del proveedor.

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

En el ejemplo anterior se incluye SimpleTraceLoggingExample.h, que contiene la variable de proveedor global que el código usará para registrar eventos.

La macro TRACELOGGING_DEFINE_PROVIDER asigna almacenamiento y define la variable de identificador del proveedor. El nombre de variable que proporcione a esta macro debe coincidir con el nombre que usó en la macro TRACELOGGING_DECLARE_PROVIDER en el archivo de encabezado.

Registro del identificador del proveedor

Para poder usar el identificador del proveedor para registrar eventos, debe llamar a TraceLoggingRegister para registrar el identificador del proveedor. Normalmente, esto se realiza en main() o DLLMain(), pero se puede hacer en cualquier momento, siempre y cuando precede a cualquier intento de registrar un evento. Si registra un evento antes de registrar el identificador del proveedor, no se producirá ningún error, pero el evento no se registrará. El código siguiente del ejemplo anterior registra el identificador del proveedor.

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

Registrar un evento de registro de seguimiento

Una vez registrado el proveedor, el código siguiente registra un evento sencillo.

    // 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).

La macro TraceLoggingWrite acepta hasta nueve argumentos. El nombre del evento se almacena en formato UTF-8. No debe usar caracteres incrustados '\0' en el nombre del evento ni en los nombres de campo. No hay ningún otro límite en los caracteres permitidos, aunque algunos descodificadores de eventos o procesadores de eventos pueden tener sus propias limitaciones.

Cada argumento que sigue al nombre del evento debe ajustarse dentro de una macro contenedora de seguimiento. Si usa C++, puede usar la TraceLoggingValue macro contenedora para deducir automáticamente el tipo del argumento. Si está escribiendo en C o si desea tener más control sobre el tipo de campo, debe usar macros de campo específicas del tipo, como TraceLoggingInt32, TraceLoggingUnicodeString, TraceLoggingString, etc.

Además de registrar eventos únicos, también puede agrupar eventos por actividad mediante las macros TraceLoggingWriteActivity o TraceLoggingWriteStart/TraceLoggingWriteStop que se encuentran en TraceLoggingActivity.h. Las actividades correlacionan eventos y son útiles para escenarios que tienen un principio y un final. Por ejemplo, puede usar una actividad para medir un escenario que comienza con el inicio de una aplicación, incluye el tiempo que tarda la pantalla de presentación en estar disponible y termina cuando la pantalla inicial de la aplicación se vuelve visible.

Las actividades capturan eventos únicos y anidan otras actividades que se producen entre el inicio y el final de esa actividad. Las actividades tienen ámbito por proceso y deben pasarse de subproceso a subproceso para anidar correctamente eventos multiproceso.

El ámbito de un identificador de proveedor se limita al módulo (archivo DLL, EXE o SYS) en el que se define. El identificador no se debe pasar a otros archivos DLL. Si se invoca una macro TraceLoggingWrite en A.DLL mediante un identificador de proveedor definido en B.DLL, puede causar problemas. La manera más segura y eficaz de cumplir este requisito es hacer referencia directamente al identificador del proveedor global y nunca pasar el identificador del proveedor como parámetro.

Anulación del registro del proveedor

Antes de que el componente se descargue, debe anular el registro del proveedor traceLogging. Esto es especialmente importante para los archivos DLL y los controladores. Es probable que se produzca un bloqueo si un archivo DLL o un controlador se descarga sin anular el registro del proveedor.

El código siguiente anula el registro del proveedor:

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

Compatibilidad

Dependiendo de su configuración, TraceLoggingProvider.h puede ser compatible con versiones anteriores (el programa resultante se ejecutará enWindows Vista o posterior), o puede optimizarse para versiones posteriores del sistema operativo. TraceLoggingProvider.h usa WINVER (modo de usuario) y NTDDI_VERSION (modo kernel) para determinar si debe ser compatible con versiones anteriores del sistema operativo o optimizarse para versiones más recientes del sistema operativo.

Para el modo de usuario, si incluye <windows.h> antes de establecer WINVER, <windows.h> establece WINVER en la versión predeterminada del sistema operativo de destino del SDK. Si WINVER está establecido en 0x602 o superior, TraceLoggingProvider.h optimiza su comportamiento para Windows 8 o posterior y la aplicación no se ejecutará en versiones anteriores de Windows. Si necesita que el programa se ejecute en Vista o Windows 7, asegúrese de establecer WINVER en el valor adecuado antes de incluir <windows.h>.

Del mismo modo, si incluye <wdm.h> antes de establecer NTDDI_VERSION, <wdm.h> establece NTDDI_VERSION en un valor predeterminado. Si NTDDI_VERSION se establece en 0x06040000 o superior, TraceLoggingProvider.h optimiza su comportamiento para Windows 10 y el controlador no funcionará en versiones anteriores de Windows.

Este comportamiento se puede controlar estableciendo TLG_HAVE_EVENT_SET_INFORMATION antes de incluir TraceLoggingProvider.h. Consulte los comentarios del TraceLoggingProvider.h encabezado para obtener más información sobre la TLG_HAVE_EVENT_SET_INFORMATION macro.

Resumen y pasos siguientes

Para ver cómo capturar y ver los datos de registro de seguimiento mediante las Herramientas de rendimiento de Windows (WPT), vea Registrar y mostrar eventos de registro de seguimiento.

Consulte Ejemplos de seguimiento de C/C++ para obtener más ejemplos de registro de seguimiento de C++.