TraceLoggingRegister function (traceloggingprovider.h)

Article
06/10/2022

Registers a TraceLogging provider so that it can be used to log events. The registration is valid until the provider is unregistered or the process exits.

Syntax

TLG_STATUS TraceLoggingRegister(
  TraceLoggingHProvider hProvider
);

Parameters

hProvider

The handle of the TraceLogging provider to register. The handle must not already be registered.

Return value

If you call this function from user-mode code, the function returns an HRESULT. Use the SUCCEEDED() macro to determine whether the function succeeds.

If you call this function from kernel-mode code, the function returns an NTSTATUS. Use the NT_SUCCESS() macro to determine whether the function succeeds.

Note

The error code returned by TraceLoggingRegister is primarily intended for use in debugging and diagnostic scenarios. Most production code should continue to run even if an ETW provider failed to register, so release builds should usually ignore the error code returned by TraceLoggingRegister.

Remarks

When a component starts running, any TraceLogging provider handle in the component will be in an unregistered state and any attempts to use the provider's handle to generate events will be silently ignored. Before the provider can write any events, you need to register the provider using TraceLoggingRegister. You will typically do this during component startup, e.g. in main, wmain, WinMain, DllMain(DLL_PROCESS_ATTACH), or DriverEntry. At component shutdown, unregister the provider by calling TraceLoggingUnregister.

Do not call TraceLoggingRegister on a provider handle that is already registered. You can unregister a handle and then register it again if necessary, though repeatedly registering and unregistering the handle can cause performance issues and should be avoided (i.e. do not register, write a few events, and then unregister; instead, register once at component startup and unregister at component shutdown).

TraceLoggingRegister is not thread-safe with regards to other calls to TraceLoggingRegister or TraceLoggingUnregister on the same handle. Do not call TraceLoggingRegister if it is possible that another thread might call TraceLoggingRegister or TraceLoggingUnregister on the same handle at the same time.

If TraceLoggingRegister fails, the provider handle will remain unregistered and all uses of the provider handle will be safe no-ops. In particular, it is a safe no-op to call TraceLoggingWrite or TraceLoggingUnregister with an unregistered provider handle.

Important

If your DLL or driver calls TraceLoggingRegister on a provider handle, it must call TraceLoggingUnregister on that provider handle before the DLL or driver unloads. If a DLL unloads without calling TraceLoggingUnregister, the process may subsequently crash. If a driver unloads without calling TraceLoggingUnregister, the system may subsequently crash. The TraceLoggingRegister function establishes an ETW configuration callback, and TraceLoggingUnregister cancels the callback. If the callback is not cancelled and the module unloads, a crash will occur the next time ETW tries to invoke the callback.

Warning

If your driver calls TraceLoggingRegister and then encounters an error during DriverEntry, it must call TraceLoggingUnregister before returning the error from DriverEntry. Normal driver cleanup routines will not be called if the driver returns an error from DriverEntry, and failure to call TraceLoggingUnregister will cause the system to crash.

TraceLoggingRegister does the following:

Calls EventRegister to open the connection to ETW.
If EventRegister succeeds, calls TraceLoggingSetInformation with InformationClass EventProviderSetTraits to configure the provider for TraceLogging support.

A call to TraceLoggingRegister is the same as a call to TraceLoggingRegisterEx with NULL for the callback and context parameters. Use TraceLoggingRegisterEx if you need to receive an ETW Enable Callback when sessions enable or disable your provider.

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps \| UWP apps]
Minimum supported server	Windows Server 2008 [desktop apps \| UWP apps]
Header	traceloggingprovider.h
Library	Advapi32.lib