EVENT_TRACE_LOGFILE structure

The EVENT_TRACE_LOGFILE structure specifies how the consumer wants to read events (from a log file or in real-time) and the callbacks that will receive the events.

When ETW flushes a buffer, this structure contains information about the event tracing session and the buffer that ETW flushed.

Syntax

typedef struct _EVENT_TRACE_LOGFILE {
  LPTSTR                       LogFileName;
  LPTSTR                       LoggerName;
  LONGLONG                     CurrentTime;
  ULONG                        BuffersRead;
  union {
    ULONG LogFileMode;
    ULONG ProcessTraceMode;
  };
  EVENT_TRACE                  CurrentEvent;
  TRACE_LOGFILE_HEADER         LogfileHeader;
  PEVENT_TRACE_BUFFER_CALLBACK BufferCallback;
  ULONG                        BufferSize;
  ULONG                        Filled;
  ULONG                        EventsLost;
  union {
    PEVENT_CALLBACK        EventCallback;
    PEVENT_RECORD_CALLBACK EventRecordCallback;
  };
  ULONG                        IsKernelTrace;
  PVOID                        Context;
} EVENT_TRACE_LOGFILE, *PEVENT_TRACE_LOGFILE;

Members

LogFileName

Name of the log file used by the event tracing session. Specify a value for this member if you are consuming from a log file. This member must be NULL if LoggerName is specified.

You must know the log file name the controller specified. If the controller logged events to a private session (the controller set the LogFileMode member of EVENT_TRACE_PROPERTIES to EVENT_TRACE_PRIVATE_LOGGER_MODE), the file name must include the process identifier that ETW appended to the log file name. For example, if the controller named the log file xyz.etl and the process identifier is 123, ETW uses xyz.etl_123 as the file name.

If the controller set the LogFileMode member of EVENT_TRACE_PROPERTIES to EVENT_TRACE_FILE_MODE_NEWFILE, the log file name must include the sequential serial number used to create each new log file.

The user consuming the events must have permissions to read the file.

LoggerName

Name of the event tracing session. Specify a value for this member if you want to consume events in real time. This member must be NULL if LogFileName is specified.

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

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.

LogFileMode

Reserved. Do not use.

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:

Value	Meaning
PROCESS_TRACE_MODE_EVENT_RECORD	Specify this mode if you want to receive events in the new EVENT_RECORD format. To receive events in the new format you must specify a callback in the EventRecordCallback member. If you do not specify this mode, you 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	Specify this mode if you do not want the time stamp value in the TimeStamp member of EVENT_HEADER and EVENT_TRACE_HEADER converted to system time (leaves the time stamp value in the resolution 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.

EventCallback

Pointer to the EventCallback function that ETW calls for each event in the buffer.

Specify this callback if you are consuming events from a provider that used one of the TraceEvent functions to log events.

EventRecordCallback

Pointer to the EventRecordCallback function that ETW calls for each event in the buffer.

Specify this callback if you are consuming events from a provider that used one of the EventWrite functions to log events.

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

Be sure to initialize the memory for this structure to zero before setting any members.

Consumers pass this structure to the OpenTrace function.

When ETW flushes a buffer, it passes the structure to the consumer's BufferCallback function.

Requirements

See also

BufferCallback

OpenTrace