traceloggingprovider.h header

TraceLogging is a system for logging self-describing events that can be decoded without a manifest. On Windows, TraceLogging is used to generate Event Tracing for Windows (ETW) events.

The TraceLoggingProvider.h header in the Windows SDK has macros and inline functions to generate TraceLogging-encoded ETW events for kernel and user-mode code using C or C++.

Note

TraceLoggingProvider.h requires compile-time constant values for event attributes such as provider name, event name, and field names. To minimize runtime overhead, TraceLoggingProvider.h builds its data structures at compile-time and stores the information in read-only memory. If you need to generate runtime-dynamic events, you will need to use a different TraceLogging implementation such as TraceLoggingDynamic.

Quick Start

• In a .c or .cpp file, use the TRACELOGGING_DEFINE_PROVIDER macro to declare a global provider handle. The provider handle represents your component's connection to ETW.
• At component startup (e.g. in main, wmain, DllMain, or DriverEntry), use the TraceLoggingRegister function to open your component's connection to ETW.
• At component shutdown, use the TraceLoggingUnregister function to close your component's connection to ETW.
• During component execution, use the TraceLoggingWrite macro to generate TraceLogging-encoded ETW events.
• As needed, use the TRACELOGGING_DECLARE_PROVIDER macro in headers to forward-declare the provider handle so it can be used in other parts of your component.
• Use tools like WPR, tracelog, or traceview to collect traces.
• Use tools like WPA, tracefmt, or traceview to decode and view traces.

Example

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

For more information, see:

• TraceLogging
• TraceLogging wrapper macros
• TraceLoggingWrite
• TRACELOGGING_DECLARE_PROVIDER
• TRACELOGGING_DEFINE_PROVIDER

traceloggingprovider.h contains the following programming interfaces:

Functions

TRACELOGGING_DECLARE_PROVIDER Forward-declares a handle for a TraceLogging provider.
TRACELOGGING_DEFINE_PROVIDER Defines a handle for a TraceLogging provider.
TRACELOGGING_DEFINE_PROVIDER_STORAGE Reserves static storage for a TraceLogging provider handle that will be defined by the user. Prefer TRACELOGGING_DEFINE_PROVIDER over this macro.
TraceLoggingBinary TraceLogging wrapper macro that adds a field with binary data to the event.
TraceLoggingChannel TraceLogging wrapper macro that sets the channel for the event.
TraceLoggingCustom TraceLogging wrapper macro that adds a field that was packed using a custom serializer to the event.
TraceLoggingCustomAttribute TraceLogging wrapper macro that adds custom information about the event into the PDB.
TraceLoggingDescription TraceLogging wrapper macro that sets the description for the event.
TraceLoggingEventTag TraceLogging wrapper macro that sets the event tag for the event.
TraceLoggingKeyword TraceLogging wrapper macro that sets the keyword for the event.
TraceLoggingLevel TraceLogging wrapper macro that sets the level for the event
TraceLoggingOpcode TraceLogging wrapper macro that sets the opcode for the event
TraceLoggingOptionGroup TraceLogging macro for use in TRACELOGGING_DEFINE_PROVIDER to specify a provider group.
TraceLoggingProviderEnabled TraceLogging macro to determine whether a any trace consumer is listening for an event from this provider.
TraceLoggingProviderId Gets the provider ID of a TraceLogging provider.
TraceLoggingRegister Registers a TraceLogging provider so that it can be used to log events.
TraceLoggingRegisterEx Registers a TraceLogging provider so that it can be used to log events, specifying an ETW enable callback.
TraceLoggingSetInformation Configures a TraceLogging provider by calling EventSetInformation.
TraceLoggingSocketAddress TraceLogging wrapper macro that adds a field with a socket address to the event.
TraceLoggingStruct TraceLogging wrapper macro that adds a field that contains other fields to the event.
TraceLoggingUnregister Unregisters a TraceLogging provider.
TraceLoggingValue TraceLogging wrapper macro for C++ that adds a field with an automatically-deduced type to the event.
TraceLoggingWrite Emits a TraceLogging event.
TraceLoggingWriteActivity Emits a TraceLogging event with specified activity IDs.