etw

package
v1.10.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 31, 2023 License: Apache-2.0 Imports: 7 Imported by: 0

Documentation

Rendered for windows/amd64

Index

Constants

View Source 
const (
	// KernelLoggerSession represents the default session name for NT kernel logger
	KernelLoggerSession = "NT Kernel Logger"
	// KernelLoggerRundownSession is the session name for the kernel rundown logger
	KernelLoggerRundownSession = "Kernel Rundown Logger"
	// KernelAuditAPICallsSession represents the session name for the kernel audit API logger
	KernelAuditAPICallsSession = "Kernel Audit API Calls Logger"
	// AntimalwareEngineSession is the session name for the Antimalware Engine logger
	AntimalwareEngineSession = "Antimalware Engine Logger"
	// WnodeTraceFlagGUID indicates that the structure contains event tracing information
	WnodeTraceFlagGUID = 0x00020000
	// ProcessTraceModeRealtime denotes that there will be a real-time consumers for events forwarded from the providers
	ProcessTraceModeRealtime = 0x00000100
	// ProcessTraceModeEventRecord is the mode that enables the "event record" format for kernel events
	ProcessTraceModeEventRecord = 0x10000000
)
View Source 
const (
	// TraceSystemTraceEnableFlagsInfo controls system logger event flags
	TraceSystemTraceEnableFlagsInfo = uint8(4)
)

Variables

View Source 
var AntimalwareEngineGUID = syscall.GUID{Data1: 0x0a002690, Data2: 0x3839, Data3: 0x4e3a, Data4: [8]byte{0xb3, 0xb6, 0x96, 0xd8, 0xdf, 0x86, 0x8d, 0x99}}

AntimalwareEngineGUID represents the GUID for the Microsoft Antimalware Engine provider

View Source 
var KernelAuditAPICallsGUID = syscall.GUID{Data1: 0xe02a841c, Data2: 0x75a3, Data3: 0x4fa7, Data4: [8]byte{0xaf, 0xc8, 0xae, 0x09, 0xcf, 0x9b, 0x7f, 0x23}}

KernelAuditAPICallsGUID represents the GUID for the kernel audit API provider

View Source 
var KernelRundownGUID = syscall.GUID{Data1: 0x3b9c9951, Data2: 0x3480, Data3: 0x4220, Data4: [8]byte{0x93, 0x77, 0x9c, 0x8e, 0x51, 0x84, 0xf5, 0xcd}}

KernelRundownGUID is the GUID for the kernel rundown logger

View Source 
var KernelTraceControlGUID = syscall.GUID{Data1: 0x9e814aad, Data2: 0x3204, Data3: 0x11d2, Data4: [8]byte{0x9a, 0x82, 0x00, 0x60, 0x08, 0xa8, 0x69, 0x39}}

KernelTraceControlGUID is the GUID for the kernel system logger

Functions

func CloseTrace 

func CloseTrace(handle TraceHandle) error

CloseTrace closes a trace. If you call this function before ProcessTrace returns, the CloseTrace function returns ErrorCtxClosePending. The ErrorCtxClosePending code indicates that the CloseTrace function call was successful; the ProcessTrace function will stop processing events after it processes all events in its buffers.

func ControlTrace 

func ControlTrace(handle TraceHandle, name string, props *EventTraceProperties, operation TraceOperation) error

ControlTrace performs various operation on the specified event tracing session, such as updating, flushing or stopping the session.

func EnableTrace 

func EnableTrace(guid syscall.GUID, handle TraceHandle, keyword uint32) error

EnableTrace influences the behaviour of the specified event trace provider.

func ProcessTrace 

func ProcessTrace(handle TraceHandle) error

ProcessTrace function delivers events from one or more event tracing sessions to the consumer. Function sorts the events chronologically and delivers all events generated between StartTime and EndTime. The ProcessTrace function blocks the thread until it delivers all events, the BufferCallback function returns false, or you call CloseTrace.

func SetTraceInformation 

func SetTraceInformation(handle TraceHandle, infoClass uint8, traceFlags []EventTraceFlags) error

SetTraceInformation enables or disables event tracing session settings for the specified information class.

Types

type BufferContext 

type BufferContext struct {
	// ProcessorIndex is an union type that contains among other fields the number of the CPU on which
	// the provider process was running.
	ProcessorIndex [2]byte
	// LoggerID identifies of the session that logged the event.
	LoggerID uint16
}

BufferContext provides context information about the event.

type EventDescriptor 

type EventDescriptor struct {
	// ID represents event identifier.
	ID uint16
	// Version indicates a revision to the event definition.
	Version uint8
	// Channel is the audience for the event (e.g. administrator or developer).
	Channel uint8
	// Level is the severity or level of detail included in the event.
	Level uint8
	// Opcode is step in a sequence of operations being performed within the `Task` field. For MOF-defined events,
	// the `Opcode` member contains the event type value.
	Opcode uint8
	// Task represents a larger unit of work within an application or component.
	Task uint16
	// Keyword A bitmask that specifies a logical group of related events. Each bit corresponds to one group. An event may belong to one or more groups.
	// The keyword can contain one or more provider-defined keywords, standard keywords, or both.
	Keyword uint64
}

EventDescriptor contains metadata that defines the event.

type EventHeader 

type EventHeader struct {
	// Size represents the size of the event, in bytes.
	Size uint16
	// HeaderType is reserved.
	HeaderType uint16
	// Flags provides information about the event such as the type of session it was logged to and if
	// the event contains extended data.
	Flags uint16
	// EventProperty indicates the source to use for parsing the event data.
	EventProperty uint16
	// ThreadID identifies the thread that generated the event.
	ThreadID uint32
	// ProcessID identifies the process that generated the event.
	ProcessID uint32
	// Timestamps contains the time that the event occurred.
	Timestamp uint64
	// ProviderID is the GUID that uniquely identifies the provider that logged the event.
	ProviderID syscall.GUID
	// EventDescriptor defines the information about the event such as the event identifier and severity level.
	EventDescriptor EventDescriptor
	// ProcessorTime is the union type that defines elapsed execution time for kernel-mode and user-mode instructions
	// in CPU units.
	ProcessorTime [8]byte
	// ActivityID is the identifier that relates two events.
	ActivityID syscall.GUID
}

EventHeader defines information about the event.

type EventHeaderExtendedDataItem 

type EventHeaderExtendedDataItem struct {
	// Reserverd1 is a reserved field.
	Reserved1 uint16
	// ExtType defines the type of extended data.
	ExtType uint16
	Linkage
	// DataSize is the size in bytes, of the extended data
	DataSize uint16
	// DataPtr is the pointer to extended data.
	DataPtr uint64
}

EventHeaderExtendedDataItem defines the extended data that ETW collects as part of the event data.

type EventRecord 

type EventRecord struct {
	// Header represents information about the event such as the time stamp for when it was written.
	Header EventHeader
	// BufferContext defines information such as the session that logged the event.
	BufferContext BufferContext
	// ExtendedDataCount is the number of extended data structures in the `ExtendedData` field.
	ExtendedDataCount uint16
	// BufferLen represents the size, in bytes, of the event data buffer
	BufferLen uint16
	// ExtendedData designates extended data items that ETW collects. The extended data includes some items, such as the security
	// identifier (SID) of the user that logged the event.
	ExtendedData *EventHeaderExtendedDataItem
	// Buffer represents raw event data that's parsed via TDH API.
	Buffer uintptr
	// UserContext is a pointer to custom user data passed in `EventTraceLogfile` structure.
	UserContext uintptr
}

EventRecord defines the layout of an event that ETW delivers.

type EventTrace 

type EventTrace struct {
	// Header contains standard event tracing metadata.
	Header EventTraceHeader
	// InstanceID represents the instance identifier.
	InstanceID uint32
	// ParentInstanceID represents instance identifer for a parent event.
	ParentInstanceID uint32
	// ParentGUID is the class GUID of the parent event.
	ParentGUID syscall.GUID
	// MofData is the pointer to the beginning of the event-specific data for this event.
	MofData uintptr
	// MofLength represents the number of bytes to which `MofData` points.
	MofLength uint32
	// Context is an union type:
	// union {
	//	ULONG              ClientContext;
	//	ETW_BUFFER_CONTEXT BufferContext;
	// };
	// `ClientContext` field is reserved. `BufferContext` Provides information about the event such as the session identifier
	// and processor number of the CPU on which the provider process ran.
	Context [2]byte
}

EventTrace stores event information that is delivered to an event trace consumer.

type EventTraceFlags 

type EventTraceFlags uint32

EventTraceFlags is the type alias for kernel trace events 

const (
	// ALPC flag activates ALPC events
	ALPC EventTraceFlags = 0x00100000
	// Cswitch flag enables context switch events
	Cswitch EventTraceFlags = 0x00000010
	// DbgPrint flag enables stack walk information
	DbgPrint EventTraceFlags = 0x00040000
	// DiskFileIO flag enables file system events
	DiskFileIO EventTraceFlags = 0x00000200
	// DiskIO flag enables disk I/O events
	DiskIO EventTraceFlags = 0x00000100
	// DiskIOInit flag enables start/end disk I/O events
	DiskIOInit EventTraceFlags = 0x00000400
	// Dispatcher flag activates dispatcher events
	Dispatcher EventTraceFlags = 0x00000800
	// DPC flag enables Deferred Procedure Call events
	DPC EventTraceFlags = 0x00000020
	// Driver flag enables driver events
	Driver EventTraceFlags = 0x00800000
	// FileIO enables file I/O events.
	FileIO EventTraceFlags = 0x02000000
	// FileIOInit flag enables file start/end events.
	FileIOInit EventTraceFlags = 0x04000000
	// ImageLoad flag enables image events.
	ImageLoad EventTraceFlags = 0x00000004
	// Handle flag enables handle events.
	Handle EventTraceFlags = 0x80000040
	// IRQ flag enables IRQ events.
	IRQ EventTraceFlags = 0x00000040
	// Job flag enables job events.
	Job EventTraceFlags = 0x00080000
	// NetTCPIP flag enables network events.
	NetTCPIP EventTraceFlags = 0x00010000
	// Process flag enables process events.
	Process EventTraceFlags = 0x00000001
	// Registry flag enable registry events.
	Registry EventTraceFlags = 0x00020000
	// Syscall flag enables syscall enter/exit events.
	Syscall EventTraceFlags = 0x00000080
	// Thread flag enables thread events.
	Thread EventTraceFlags = 0x00000002
)

func (EventTraceFlags) String 

func (f EventTraceFlags) String() string

String returns the string representation of enabled event trace flags.

type EventTraceHeader 

type EventTraceHeader struct {
	// Size represents the total number of bytes of the event. It includes the size of the header structure,
	// plus the size of any event-specific data appended to the header.
	Size uint16
	// FieldTypeFlags is an union field represented as follow:
	//  union {
	//	USHORT FieldTypeFlags;
	//	struct {
	//	  UCHAR HeaderType;
	//	  UCHAR MarkerFlags;
	//	};
	// };
	// All memebers of this union are reserved for internal use.
	FieldTypeFlags [2]byte
	// Versions in an union field with the following declaration:
	// union {
	//	ULONG  Version;
	//	struct {
	//	  UCHAR  Type;
	//	  UCHAR  Level;
	//	  USHORT Version;
	//	} Class;
	//  };
	// `Type` field indicates the general purpose type of this event (e.g. data collection end/start, checkpoint, etc.)
	// `Level` designates the severity of the generated event and the `Version` tells the consumer which MOF class to use to
	// decipher the event data.
	Version [4]byte
	// ThreadID identifes the thread that generated this event.
	ThreadID uint32
	// ProcessID identifes the process that generated this event.
	ProcessID uint32
	// Timestamp contains the time that the event occurred.
	Timestamp uint64
	// GUID is an union:
	// union {
	//	GUID      Guid;
	//	ULONGLONG GuidPtr;
	// };
	// `Guid` identifies a category of events. `GuidPtr` is the pointer to an event trace class GUID.
	GUID [16]byte
	// ProcessorTime is another union type:
	// union {
	//	struct {
	//		ULONG ClientContext;
	//		ULONG Flags;
	//	  };
	//	  struct {
	//		ULONG KernelTime;
	//		ULONG UserTime;
	//	  };
	//	  ULONG64 ProcessorTime;
	// };
	// `ClientContext` is reserved, while `Flags` must be set to `WnodeFlagTracedGuid`. The rest of the members
	// specify elapsed execution time for kernel and user mode instructions respectively.
	ProcessorTime [8]byte
}

EventTraceHeader contains standard event tracing information common to all events.

type EventTraceLogfile 

type EventTraceLogfile struct {
	// LogFileName is the name of the log file used by the event tracing session.
	LogFileName *uint16
	// LoggerName is the name of the event tracing session. Only applicable when consuming events in real time.
	LoggerName *uint16
	// CurrentTime on output, the current time, in 100-nanosecond intervals since midnight, January 1, 1601.
	CurrentTime int64
	// BuffersRead represents the number of buffers processed.
	BuffersRead uint32
	// LogFileMode is union type the dictates the processing mode for events.
	LogFileMode [4]byte
	// CurrentEvents contains the last event processed.
	CurrentEvent EventTrace
	// LogfileHeader represents global information about the tracing session.
	LogfileHeader TraceLogfileHeader
	// BufferCallback is a pointer to the function that receives buffer-related statistics for each buffer ETW flushes.
	// ETW calls this callback after it delivers all the events in the buffer.
	BufferCallback uintptr
	// BufferSize contains the size of each buffer, in bytes.
	BufferSize uint32
	// Filled contains the number of bytes in the buffer that contain valid information.
	Filled uint32
	// EventsLost is an unused field.
	EventsLost uint32
	// EventCallback is the union field that contains pointers to callback functions that ETW calls for each buffer.
	EventCallback [8]byte
	// IsKernelTrace specifies whether the event tracing session is the NT kernel logger.
	IsKernelTrace uint32
	// Context is data that a consumer can specify when calling `OpenTrace` function.
	Context uintptr
}

EventTraceLogfile 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.

type EventTraceProperties 

type EventTraceProperties struct {
	// Wnode structure requires `BufferSize`, `Flags` and `GUID` members to be initialized.
	Wnode WnodeHeader
	// BufferSize represents the amount of memory allocated for each event tracing session buffer, in kilobytes.
	// The maximum buffer size is 1 MB. ETW uses the size of physical memory to calculate this value.
	// If an application expects a relatively low event rate, the buffer size should be set to the memory page size.
	// To get the page memory size, you can invoke GetSystemInfo() function.
	// If the event rate is expected to be relatively high, the application should specify a larger buffer size,
	// and should increase the maximum number of buffers.
	//
	// The buffer size affects the rate at which buffers fill and must be flushed. Although a small buffer size requires
	// less memory, it increases the rate at which buffers must be flushed.
	BufferSize uint32
	// MinimumBuffers specifies the minimum number of buffers allocated for the event tracing session's buffer pool.
	// The minimum number of buffers that you can specify is two buffers per processor. For example, on a single processor machine,
	// the minimum number of buffers is two.
	MinimumBuffers uint32
	// MaximumBuffers is the maximum number of buffers allocated for the event tracing session's buffer pool. Typically, this value is
	// the minimum number of buffers plus twenty. ETW uses the buffer size and the size of physical memory to calculate this value.
	MaximumBuffers uint32
	// MaximumFileSize is the maximum size of the file used to log events, in megabytes.
	MaximumFileSize uint32
	// LogFileMode determines the logging modes for the event tracing session. You use this member to specify that you want events written to a
	// log file, a real-time consumer, or both. In real-time logging mode, if no consumers are available, events will be written
	// to disk, and when a consumers begins processing real-time events, the events in the playback file are consumed first.
	LogFileMode uint32
	// FlushTimer specifies how often, in seconds, the trace buffers are forcibly flushed. The minimum flush time is 1 second.
	// This forced flush is in addition to the automatic flush that occurs whenever a buffer is full and when the trace session
	// stops. If zero, ETW flushes buffers as soon as they become full. If nonzero, ETW flushes all buffers that contain events
	// based on the timer value. Typically, you want to flush buffers only when they become full. Forcing the buffers to flush
	// (either by setting this member to a nonzero value or by calling `FlushTrace`) can increase the file size of the log file
	// with unfilled buffer space.
	//
	// If the consumer is consuming events in real time, you may want to set this member to a nonzero value if the event rate is
	// low to force events to be delivered before the buffer is full.
	// For the case of a realtime logger, a value of zero (the default value) means that the flush time will be set to 1 second.
	// A realtime logger is when LogFileMode is set to `EventTraceRealTimeMode`.
	FlushTimer uint32
	// EnableFlags specifies which kernel events are delievered to the consumer when NT Kernel logger session is started.
	// For example, registry events, process, disk IO and so on.
	EnableFlags EventTraceFlags
	// AgeLimit is not used.
	AgeLimit int32
	// NumberOfBuffers indicates the number of buffers allocated for the event tracing session's buffer pool.
	NumberOfBuffers uint32
	// FreeBuffers indicates the number of buffers that are allocated but unused in the event tracing session's buffer pool.
	FreeBuffers uint32
	// EventsLost counts the number of events that were not recorded.
	EventsLost uint32
	// BuffersWritten counts the number of buffers written.
	BuffersWritten uint32
	// LogBuffersLost determines the number of buffers that could not be written to the log file.
	LogBuffersLost uint32
	// RealTimeBuffersLost represents the number of buffers that could not be delivered in real-time to the consumer.
	RealTimeBuffersLost uint32
	// LoggerThreadID is the thread identifier for the event tracing session.
	LoggerThreadID uintptr
	// LogFileNameOffset is the offset from the start of the structure's allocated memory to beginning of the null-terminated
	// string that contains the log file name.
	LogFileNameOffset uint32
	// LoggerNameOffset is the offset from the start of the structure's allocated memory to beginning of the null-terminated
	// string that contains the session name. The session name is limited to 1024 characters. The session name is case-insensitive
	// and must be unique.
	LoggerNameOffset uint32
}

EventTraceProperties contains information about an event tracing session. Each time a new session is created, or an existing session is about to be modified, this structure is used to describe session properties.

type Linkage 

type Linkage struct {
	Linkage   uint16
	Resreved2 uint16
}

Linkage is the inner struct for EventHeaderExtendedDataItem.

type TraceHandle 

type TraceHandle uintptr

TraceHandle is an alias for trace handle type

func OpenTrace 

func OpenTrace(ktrace EventTraceLogfile) TraceHandle

OpenTrace opens a real-time trace session or log file for consuming.

func StartTrace 

func StartTrace(name string, props *EventTraceProperties) (TraceHandle, error)

StartTrace registers and starts an event tracing session for the specified provider. The trace assumes there will be a real-time event consumer responsible for collecting and processing events. If the function succeeds, it returns the handle to the tracing session.

func (TraceHandle) IsValid 

func (handle TraceHandle) IsValid() bool

IsValid determines if the session handle is valid

type TraceLogfileHeader 

type TraceLogfileHeader struct {
	// BufferSize is the size of the event tracing session's buffers in bytes.
	BufferSize uint32
	// Version is the union type that represents version number of the operating system.
	Version [4]byte
	// ProviderVersion is the build number of the operating system.
	ProviderVersion uint32
	// NumberOfProcessors indicates the number of processors on the system.
	NumberOfProcessors uint32
	// EndTime is the time at which the event tracing session stopped. This value is 0 for real time event consumers.
	EndTime uint64
	// TimerResolution is the resolution of the hardware timer, in units of 100 nanoseconds.
	TimerResolution uint32
	// MaximumFileSize is the size of the log file, in megabytes.
	MaximumFileSize uint32
	// LogfileMode represents the current logging mode for the event tracing session.
	LogfileMode uint32
	// BuffersWritten is the total number of buffers written by the event tracing session.
	BuffersWritten uint32
	// GUID is a an union type with the two first field reserved for internal usage. Other fields indicate
	// the number of events lost and the CPU speed in Mhz.
	GUID [16]byte
	// LoggerName is a reserved field.
	LoggerName *uint16
	// LogfileName is a reserved field.
	LogfileName *uint16
	// TimeZone contains time-zone information for `BootTime`, `EndTime` and `StartTime` fields.
	TimeZone syscall.Timezoneinformation
	// BootTime is the time at which the system was started, in 100-nanosecond intervals since midnight, January 1, 1601.
	BootTime uint64
	// PerfFreq is the frequency of the high-resolution performance counter, if one exists.
	PerfFreq uint64
	// StartTime is the time at which the event tracing session started, in 100-nanosecond intervals since midnight, January 1, 1601.
	StartTime uint64
	// ReservedFlags specifies the clock type.
	ReservedFlags uint32
	// BuffersLost is the total number of buffers lost during the event tracing session.
	BuffersLost uint32
}

TraceLogfileHeader contains information about an event tracing session and its events.

type TraceOperation 

type TraceOperation uint32

TraceOperation is the type alias for the trace operation. 

const (
	// Query represents the query trace operation.
	Query TraceOperation = 0
	// Stop represents the stop trace operation.
	Stop TraceOperation = 1
	// Update represents the update trace operation.
	Update TraceOperation = 2
	// Flush represents the flush trace operation.
	Flush TraceOperation = 3
)

type WnodeHeader 

type WnodeHeader struct {
	// BufferSize is the total size of memory allocated, in bytes, for the event tracing session properties.
	BufferSize uint32
	// ProviderID is reserved for internal use.
	ProviderID uint32
	// HostricalContext is an union field with the following C representation:
	// union {
	//	ULONG64 HistoricalContext;
	//	struct {
	//	  ULONG Version;
	//	  ULONG Linkage;
	//	};
	// };
	// On output, HistoricalContext stores the handle to the event tracing session. Version and Linkage fields are reserved for internal use.
	HistoricalContext [8]byte
	// KernelHandle is an union with the following C representation:
	// union {
	//	HANDLE        KernelHandle;
	//	LARGE_INTEGER TimeStamp;
	//  };
	// `KernelHandle` is reserved for internal use. `TimeStamp` designates the instant at which the information of this
	// structure was updated.
	KernelHandle [8]byte
	// GUID that defines the session. For NT Kernel Logger session we have to set this member to `SystemTraceControlGuid`.
	GUID syscall.GUID
	// ClientContext represents clock resolution to use when logging the time stamp for each event. The default is Query performance counter (QPC).
	ClientContext uint32
	// Flags must contain `WnodeFlagTracedGUID` to indicate that the structure contains event tracing information.
	Flags uint32
}

WnodeHeader is a member of `EventTraceProperties` structure. The majority of the fields in this structure are not relevant to us.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.