TraceEventInstance function (evntrace.h)

Article
05/24/2022

A RegisterTraceGuids-based ("Classic") event provider uses the TraceEventInstance function to send a structured event to an event tracing session with an instance identifier.

The event uses an instance identifier to associate the event with a transaction. This function may also be used to trace hierarchical relationships between related events.

Syntax

ULONG WMIAPI TraceEventInstance(
  [in] TRACELOGGER_HANDLE     TraceHandle,
  [in] PEVENT_INSTANCE_HEADER EventTrace,
  [in] PEVENT_INSTANCE_INFO   InstInfo,
  [in] PEVENT_INSTANCE_INFO   ParentInstInfo
);

Parameters

[in] TraceHandle

Handle to the event tracing session that records the event instance. The provider obtains the handle when it calls the GetTraceLoggerHandle function in its ControlCallback implementation.

[in] EventTrace

Pointer to an EVENT_INSTANCE_HEADER structure. Event-specific data is optionally appended to the structure. The largest event you can log is 64K. You must specify values for the following members of the EVENT_INSTANCE_HEADER structure.

Size
Flags
RegHandle

Depending on the complexity of the information your provider provides, you should also consider specifying values for the following members.

Class.Type
Class.Level

To trace hierarchical relationships between related events, also set the ParentRegHandle member.

[in] InstInfo

Pointer to an EVENT_INSTANCE_INFO structure, which contains the registration handle for this event trace class and the instance identifier. Use the CreateTraceInstanceId function to initialize the structure.

[in] ParentInstInfo

Pointer to an EVENT_INSTANCE_INFO structure, which contains the registration handle for the parent event trace class and its instance identifier. Use the CreateTraceInstanceId function to initialize the structure. Set to NULL if you are not tracing a hierarchical relationship.

Return value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is one of the system error codes. The following are some common errors and their causes.

ERROR_INVALID_FLAGS

The Flags member of the EVENT_INSTANCE_HEADER does not contain WNODE_FLAG_TRACED_GUID.
ERROR_OUTOFMEMORY

There was insufficient memory to complete the function call. The causes for this error code are described in the following Remarks section.
ERROR_INVALID_PARAMETER

One of the following is true:
- EventTrace is NULL.
- pInstInfo is NULL.
- The members of pInstInfo are NULL.
- TraceHandle is NULL.
- The Size member of the EVENT_INSTANCE_HEADER is incorrect.
ERROR_INVALID_HANDLE

TraceHandle is not valid or specifies the NT Kernel Logger session handle.
ERROR_NOT_ENOUGH_MEMORY

The session ran out of free buffers to write to. This can occur during high event rates because the disk subsystem is overloaded or the number of buffers is too small. Rather than blocking until more buffers become available, TraceEvent discards the event.

Windows 2000 and Windows XP: Not supported.
ERROR_OUTOFMEMORY

The event is discarded because, although the buffer pool has not reached its maximum size, there is insufficient available memory to allocate an additional buffer and there is no buffer available to receive the event.
ERROR_MORE_DATA

Data from a single event cannot span multiple buffers. A trace event is limited to the size of the event tracing session's buffer minus the size of the EVENT_INSTANCE_HEADER structure.

Remarks

MOF-based ETW providers call this function.

Note

Most developers will not call this function. This API supports MOF-based ETW, but MOF-based ETW is deprecated in favor of manifest-based ETW. In addition, most MOF-based providers use wrapper functions generated by MC.exe instead of directly calling ETW APIs.

Before the provider can call this function, the provider

Must call the RegisterTraceGuids function to register itself and the event trace class.
Must call the CreateTraceInstanceId function to create an instance identifier for the registered event trace class.
Must be enabled. A controller calls the EnableTrace function to enable a provider.

The event is either written to a log file, sent to event trace consumers in real time, or both. The LogFileMode member of the EVENT_TRACE_PROPERTIES structure passed to the StartTrace defines where the event is sent.

The trace events are written in the order in which they occur.

To trace unrelated events, use the TraceEvent function.

Windows XP: Does not work correctly.

Examples

For an example of generating related sets of events using CreateTraceInstanceId and TraceEventInstance, see Tracing Event Instances.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	evntrace.h
Library	Advapi32.lib
DLL	Advapi32.dll

Share via