EVENT_TRACE_LOGFILEW structure (evntrace.h)

The EVENT_TRACE_LOGFILE structure stores information about a trace data source.

The EVENT_TRACE_LOGFILE structure is used when calling OpenTrace. The user provides an EVENT_TRACE_LOGFILE structure with information about the trace data source (either the name of an ETL file or the name of an active real-time logger session), trace processing flags, and the callback functions that will receive trace data. On success, OpenTrace fills in the remaining fields of the structure to return details about the trace data source.

When ProcessTrace processes a buffer, it invokes the user-defined BufferCallback with a EVENT_TRACE_LOGFILE structure to provide information about the event processing session and the buffer.

Syntax

typedef struct _EVENT_TRACE_LOGFILEW {
  LPWSTR                        LogFileName;
  LPWSTR                        LoggerName;
  LONGLONG                      CurrentTime;
  ULONG                         BuffersRead;
  union {
    ULONG LogFileMode;
    ULONG ProcessTraceMode;
  } DUMMYUNIONNAME;
  EVENT_TRACE                   CurrentEvent;
  TRACE_LOGFILE_HEADER          LogfileHeader;
  PEVENT_TRACE_BUFFER_CALLBACKW BufferCallback;
  ULONG                         BufferSize;
  ULONG                         Filled;
  ULONG                         EventsLost;
  union {
    PEVENT_CALLBACK        EventCallback;
    PEVENT_RECORD_CALLBACK EventRecordCallback;
  } DUMMYUNIONNAME2;
  ULONG                         IsKernelTrace;
  PVOID                         Context;
} EVENT_TRACE_LOGFILEW, *PEVENT_TRACE_LOGFILEW;

Members

LogFileName

Name of the log file being processed, or NULL if processing data from a real-time tracing session. Specify a value for this member if you are calling OpenTrace to consume data from a log file.

When calling OpenTrace, if LoggerName is non-NULL then LogFileName must be NULL.

When calling OpenTrace, the user consuming the events must have permissions to read the file.

LoggerName

Name of the real-time event tracing session, or NULL if processing data from a log file. Specify a value for this member if you are calling OpenTrace to consume data from a real-time session.

When calling OpenTrace, if LogFileName is non-NULL then LoggerName must be NULL.

You can only consume events in real time if the trace controller has set the LogFileMode member of EVENT_TRACE_PROPERTIES to include the EVENT_TRACE_REAL_TIME_MODE flag.

Only users with administrative privileges, users in the Performance Log Users group, and applications running as LocalSystem, LocalService, NetworkService can consume events in real time. To grant a restricted user the ability to consume events in real time, add them to the Performance Log Users group or call EventAccessControl.

Windows XP and Windows 2000: Anyone can consume real time events.

CurrentTime

On output, the current time, in 100-nanosecond intervals since midnight, January 1, 1601.

BuffersRead

On output, the number of buffers processed.

DUMMYUNIONNAME

DUMMYUNIONNAME.LogFileMode

Reserved. Do not use.

DUMMYUNIONNAME.ProcessTraceMode

Modes for processing events. The modes are defined in the evntcons.h header file. You can specify one or more of the following modes:

• PROCESS_TRACE_MODE_EVENT_RECORD

  Specify this mode if you want to receive events in the new EVENT_RECORD format (strongly recommended). To receive events in the new format you must specify a callback in the EventRecordCallback member. If you do not specify this mode, you will receive events in the old format through the callback specified in the EventCallback member.

  Prior to Windows Vista: Not supported.

• PROCESS_TRACE_MODE_RAW_TIMESTAMP

  By default, ProcessTrace converts the event's TimeStamp from the original raw format (system time, QPC time, or CPU cycle counter) into system time (100-nanosecond intervals since midnight, January 1, 1601).

  Specify the PROCESS_TRACE_MODE_RAW_TIMESTAMP flag if you do not want the time stamp value in the TimeStamp member of EVENT_HEADER and EVENT_TRACE_HEADER converted to system time. If this flag is specified, ProcessTrace will leave the time stamp value in the original format that the controller specified in the Wnode.ClientContext member of EVENT_TRACE_PROPERTIES.

  Prior to Windows Vista: Not supported.

• PROCESS_TRACE_MODE_REAL_TIME

  Specify this mode to receive events in real time. You must specify this mode if LoggerName is not NULL.

CurrentEvent

On output, an EVENT_TRACE structure that contains the last event processed.

LogfileHeader

On output, a TRACE_LOGFILE_HEADER structure that contains general information about the session and the computer on which the session ran.

BufferCallback

Pointer to the BufferCallback function that receives buffer-related statistics for each buffer ETW flushes. ETW calls this callback after it delivers all the events in the buffer. This callback is optional.

BufferSize

On output, contains the size of each buffer, in bytes.

Filled

On output, contains the number of bytes in the buffer that contain valid information.

EventsLost

Not used.

DUMMYUNIONNAME2

DUMMYUNIONNAME2.EventCallback

Pointer to the EventCallback function that ETW calls for each event in the buffer. This field is used only if the ProcessTraceMode field does not include the PROCESS_TRACE_MODE_EVENT_RECORD flag.

DUMMYUNIONNAME2.EventRecordCallback

Pointer to the EventRecordCallback function that ETW calls for each event in the buffer. This field is used only if the ProcessTraceMode field includes the PROCESS_TRACE_MODE_EVENT_RECORD flag.

Prior to Windows Vista: Not supported.

IsKernelTrace

On output, if this member is TRUE, the event tracing session is the NT Kernel Logger. Otherwise, it is another event tracing session.

Context

Context data that a consumer can specify when calling OpenTrace. If the consumer uses EventRecordCallback to consume events, ETW sets the UserContext member of the EVENT_RECORD structure to this value.

Prior to Windows Vista: Not supported.

Remarks

Event consumers should:

1. Initialize the memory for this structure to zero.
2. If reading from an ETL file, set LogFileName to the path to the file. Otherwise (i.e. if reading from a real-time session), set LoggerName to the name of the session and set ProcessTraceMode to PROCESS_TRACE_MODE_REAL_TIME.
3. If using EventRecordCallback (recommended), set EventRecordCallback to the address of your event record callback function, set Context to a value to be provided to your callback, and add PROCESS_TRACE_MODE_EVENT_RECORD to ProcessTraceMode. Otherwise (i.e. if using EventCallback), set EventCallback to the address of your event callback function.
4. If you need a callback after each buffer is processed, set BufferCallback to the address of your buffer callback function.
5. If you want the original raw timestamp data instead of the processed timestamp, add PROCESS_TRACE_MODE_RAW_TIMESTAMP to ProcessTraceMode.
6. Call OpenTrace. Note that if successful, OpenTrace function will fill in members of this structure with information from the trace data source.
7. Call ProcessTrace with the handle returned by OpenTrace.
   • ProcessTrace will invoke your event callback function for each event.
   • ProcessTrace will invoke your buffer callback function (if provided) after finishing each buffer and will include an instance of the EVENT_TRACE_LOGFILE structure with trace processing status information.
8. After trace processing completes, call CloseTrace to close the handle that was returned by OpenTrace.

Requirements

See also

BufferCallback

EventRecordCallback

OpenTrace