etw

package
v0.4.12 Latest Latest
Warning

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

 Go to latest Published: Feb 21, 2019 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package etw provides support for TraceLogging-based ETW (Event Tracing for Windows). TraceLogging is a format of ETW events that are self-describing (the event contains information on its own schema). This allows them to be decoded without needing a separate manifest with event information. The implementation here is based on the information found in TraceLoggingProvider.h in the Windows SDK, which implements TraceLogging as a set of C macros.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Channel 

type Channel uint8

Channel represents the ETW logging channel that is used. It can be used by event consumers to give an event special treatment. 

const (
	// ChannelTraceLogging is the default channel for TraceLogging events. It is
	// not required to be used for TraceLogging, but will prevent decoding
	// issues for these events on older operating systems.
	ChannelTraceLogging Channel = 11
)

type EnableCallback 

type EnableCallback func(*windows.GUID, ProviderState, Level, uint64, uint64, uintptr)

EnableCallback is the form of the callback function that receives provider enable/disable notifications from ETW.

type EventData 

type EventData struct {
	// contains filtered or unexported fields
}

EventData maintains a buffer which builds up the data for an ETW event. It needs to be paired with EventMetadata which describes the event.

func (*EventData) Bytes 

func (ed *EventData) Bytes() []byte

Bytes returns the raw binary data containing the event data. The returned value is not copied from the internal buffer, so it can be mutated by the EventData object after it is returned.

func (*EventData) WriteInt16 

func (ed *EventData) WriteInt16(value int16)

WriteInt16 appends a int16 to the buffer.

func (*EventData) WriteInt32 

func (ed *EventData) WriteInt32(value int32)

WriteInt32 appends a int32 to the buffer.

func (*EventData) WriteInt64 

func (ed *EventData) WriteInt64(value int64)

WriteInt64 appends a int64 to the buffer.

func (*EventData) WriteInt8 

func (ed *EventData) WriteInt8(value int8)

WriteInt8 appends a int8 to the buffer.

func (*EventData) WriteString 

func (ed *EventData) WriteString(data string)

WriteString appends a string, including the null terminator, to the buffer.

func (*EventData) WriteUint16 

func (ed *EventData) WriteUint16(value uint16)

WriteUint16 appends a uint16 to the buffer.

func (*EventData) WriteUint32 

func (ed *EventData) WriteUint32(value uint32)

WriteUint32 appends a uint32 to the buffer.

func (*EventData) WriteUint64 

func (ed *EventData) WriteUint64(value uint64)

WriteUint64 appends a uint64 to the buffer.

func (*EventData) WriteUint8 

func (ed *EventData) WriteUint8(value uint8)

WriteUint8 appends a uint8 to the buffer.

type EventDescriptor 

type EventDescriptor struct {
	Channel Channel
	Level   Level
	Opcode  uint8
	Task    uint16
	Keyword uint64
	// contains filtered or unexported fields
}

EventDescriptor represents various metadata for an ETW event.

func NewEventDescriptor 

func NewEventDescriptor() *EventDescriptor

NewEventDescriptor returns an EventDescriptor initialized for use with TraceLogging.

func (*EventDescriptor) Identity 

func (ed *EventDescriptor) Identity() uint32

Identity returns the identity of the event. If the identity is not 0, it should uniquely identify the other event metadata (contained in EventDescriptor, and field metadata). Only the lower 24 bits of this value are relevant.

func (*EventDescriptor) SetIdentity 

func (ed *EventDescriptor) SetIdentity(identity uint32)

SetIdentity sets the identity of the event. If the identity is not 0, it should uniquely identify the other event metadata (contained in EventDescriptor, and field metadata). Only the lower 24 bits of this value are relevant.

type EventMetadata 

type EventMetadata struct {
	// contains filtered or unexported fields
}

EventMetadata maintains a buffer which builds up the metadata for an ETW event. It needs to be paired with EventData which describes the event.

func (*EventMetadata) Bytes 

func (em *EventMetadata) Bytes() []byte

Bytes returns the raw binary data containing the event metadata. Before being returned, the current size of the buffer is written to the start of the buffer. The returned value is not copied from the internal buffer, so it can be mutated by the EventMetadata object after it is returned.

func (*EventMetadata) WriteArray 

func (em *EventMetadata) WriteArray(name string, inType InType, outType OutType, tags uint32)

WriteArray writes the metadata for an array field to the buffer. The number of elements in the array must be written as a uint16 in the event data, immediately preceeding the event data.

func (*EventMetadata) WriteCountedArray 

func (em *EventMetadata) WriteCountedArray(name string, count uint16, inType InType, outType OutType, tags uint32)

WriteCountedArray writes the metadata for an array field to the buffer. The size of a counted array is fixed, and the size is written into the metadata directly.

func (*EventMetadata) WriteEventHeader 

func (em *EventMetadata) WriteEventHeader(name string, tags uint32)

WriteEventHeader writes the metadata for the start of an event to the buffer. This specifies the event name and tags.

func (*EventMetadata) WriteField 

func (em *EventMetadata) WriteField(name string, inType InType, outType OutType, tags uint32)

WriteField writes the metadata for a simple field to the buffer.

func (*EventMetadata) WriteStruct 

func (em *EventMetadata) WriteStruct(name string, fieldCount uint8, tags uint32)

WriteStruct writes the metadata for a nested struct to the buffer. The struct contains the next N fields in the metadata, where N is specified by the fieldCount argument.

type EventOpt 

type EventOpt func(options *eventOptions)

EventOpt defines the option function type that can be passed to Provider.WriteEvent to specify general event options, such as level and keyword.

func WithActivityID 

func WithActivityID(activityID *windows.GUID) EventOpt

func WithChannel 

func WithChannel(channel Channel) EventOpt

func WithEventOpts 

func WithEventOpts(opts ...EventOpt) []EventOpt

WithEventOpts returns the variadic arguments as a single slice.

func WithKeyword 

func WithKeyword(keyword uint64) EventOpt

WithKeyword specifies the keywords of the event to be written. Multiple uses of this option are OR'd together.

func WithLevel 

func WithLevel(level Level) EventOpt

WithLevel specifies the level of the event to be written.

func WithRelatedActivityID 

func WithRelatedActivityID(activityID *windows.GUID) EventOpt

func WithTags 

func WithTags(newTags uint32) EventOpt

WithTags specifies the tags of the event to be written. Tags is a 28-bit value (top 4 bits are ignored) which are interpreted by the event consumer.

type FieldOpt 

type FieldOpt func(em *EventMetadata, ed *EventData)

FieldOpt defines the option function type that can be passed to Provider.WriteEvent to add fields to the event.

func BoolArray 

func BoolArray(name string, values []bool) FieldOpt

BoolArray adds an array of bool to the event.

func BoolField 

func BoolField(name string, value bool) FieldOpt

BoolField adds a single bool field to the event.

func Float32Array 

func Float32Array(name string, values []float32) FieldOpt

Float32Array adds an array of float32 to the event.

func Float32Field 

func Float32Field(name string, value float32) FieldOpt

Float32Field adds a single float32 field to the event.

func Float64Array 

func Float64Array(name string, values []float64) FieldOpt

Float64Array adds an array of float64 to the event.

func Float64Field 

func Float64Field(name string, value float64) FieldOpt

Float64Field adds a single float64 field to the event.

func Int16Array 

func Int16Array(name string, values []int16) FieldOpt

Int16Array adds an array of int16 to the event.

func Int16Field 

func Int16Field(name string, value int16) FieldOpt

Int16Field adds a single int16 field to the event.

func Int32Array 

func Int32Array(name string, values []int32) FieldOpt

Int32Array adds an array of int32 to the event.

func Int32Field 

func Int32Field(name string, value int32) FieldOpt

Int32Field adds a single int32 field to the event.

func Int64Array 

func Int64Array(name string, values []int64) FieldOpt

Int64Array adds an array of int64 to the event.

func Int64Field 

func Int64Field(name string, value int64) FieldOpt

Int64Field adds a single int64 field to the event.

func Int8Array 

func Int8Array(name string, values []int8) FieldOpt

Int8Array adds an array of int8 to the event.

func Int8Field 

func Int8Field(name string, value int8) FieldOpt

Int8Field adds a single int8 field to the event.

func IntArray 

func IntArray(name string, values []int) FieldOpt

IntArray adds an array of int to the event.

func IntField 

func IntField(name string, value int) FieldOpt

IntField adds a single int field to the event.

func StringArray 

func StringArray(name string, values []string) FieldOpt

StringArray adds an array of string to the event.

func StringField 

func StringField(name string, value string) FieldOpt

StringField adds a single string field to the event.

func Struct 

func Struct(name string, opts ...FieldOpt) FieldOpt

Struct adds a nested struct to the event, the FieldOpts in the opts argument are used to specify the fields of the struct.

func Uint16Array 

func Uint16Array(name string, values []uint16) FieldOpt

Uint16Array adds an array of uint16 to the event.

func Uint16Field 

func Uint16Field(name string, value uint16) FieldOpt

Uint16Field adds a single uint16 field to the event.

func Uint32Array 

func Uint32Array(name string, values []uint32) FieldOpt

Uint32Array adds an array of uint32 to the event.

func Uint32Field 

func Uint32Field(name string, value uint32) FieldOpt

Uint32Field adds a single uint32 field to the event.

func Uint64Array 

func Uint64Array(name string, values []uint64) FieldOpt

Uint64Array adds an array of uint64 to the event.

func Uint64Field 

func Uint64Field(name string, value uint64) FieldOpt

Uint64Field adds a single uint64 field to the event.

func Uint8Array 

func Uint8Array(name string, values []uint8) FieldOpt

Uint8Array adds an array of uint8 to the event.

func Uint8Field 

func Uint8Field(name string, value uint8) FieldOpt

Uint8Field adds a single uint8 field to the event.

func UintArray 

func UintArray(name string, values []uint) FieldOpt

UintArray adds an array of uint to the event.

func UintField 

func UintField(name string, value uint) FieldOpt

UintField adds a single uint field to the event.

func UintptrArray 

func UintptrArray(name string, values []uintptr) FieldOpt

UintptrArray adds an array of uintptr to the event.

func UintptrField 

func UintptrField(name string, value uintptr) FieldOpt

UintptrField adds a single uintptr field to the event.

func WithFields 

func WithFields(opts ...FieldOpt) []FieldOpt

WithFields returns the variadic arguments as a single slice.

type InType 

type InType byte

InType indicates the type of data contained in the ETW event. 

const (
	InTypeNull InType = iota
	InTypeUnicodeString
	InTypeANSIString
	InTypeInt8
	InTypeUint8
	InTypeInt16
	InTypeUint16
	InTypeInt32
	InTypeUint32
	InTypeInt64
	InTypeUint64
	InTypeFloat
	InTypeDouble
	InTypeBool32
	InTypeBinary
	InTypeGUID
	InTypePointerUnsupported
	InTypeFileTime
	InTypeSystemTime
	InTypeSID
	InTypeHexInt32
	InTypeHexInt64
	InTypeCountedString
	InTypeCountedANSIString
	InTypeStruct
	InTypeCountedBinary
	InTypeCountedArray InType = 32
	InTypeArray        InType = 64
)

Various InType definitions for TraceLogging. These must match the definitions found in TraceLoggingProvider.h in the Windows SDK.

type Level 

type Level uint8

Level represents the ETW logging level. There are several predefined levels that are commonly used, but technically anything from 0-255 is allowed. Lower levels indicate more important events, and 0 indicates an event that will always be collected. 

const (
	LevelAlways Level = iota
	LevelCritical
	LevelError
	LevelWarning
	LevelInfo
	LevelVerbose
)

Predefined ETW log levels.

type OutType 

type OutType byte

OutType specifies a hint to the event decoder for how the value should be formatted. 

const (
	// OutTypeDefault indicates that the default formatting for the InType will
	// be used by the event decoder.
	OutTypeDefault OutType = iota
	OutTypeNoPrint
	OutTypeString
	OutTypeBoolean
	OutTypeHex
	OutTypePID
	OutTypeTID
	OutTypePort
	OutTypeIPv4
	OutTypeIPv6
	OutTypeSocketAddress
	OutTypeXML
	OutTypeJSON
	OutTypeWin32Error
	OutTypeNTStatus
	OutTypeHResult
	OutTypeFileTime
	OutTypeSigned
	OutTypeUnsigned
	OutTypeUTF8              OutType = 35
	OutTypePKCS7WithTypeInfo OutType = 36
	OutTypeCodePointer       OutType = 37
	OutTypeDateTimeUTC       OutType = 38
)

Various OutType definitions for TraceLogging. These must match the definitions found in TraceLoggingProvider.h in the Windows SDK.

type Provider 

type Provider struct {
	ID *windows.GUID
	// contains filtered or unexported fields
}

Provider represents an ETW event provider. It is identified by a provider name and ID (GUID), which should always have a 1:1 mapping to each other (e.g. don't use multiple provider names with the same ID, or vice versa).

func NewProvider 

func NewProvider(name string, callback EnableCallback) (provider *Provider, err error)

NewProvider creates and registers a new ETW provider. The provider ID is generated based on the provider name.

func NewProviderWithID 

func NewProviderWithID(name string, id *windows.GUID, callback EnableCallback) (provider *Provider, err error)

NewProviderWithID creates and registers a new ETW provider, allowing the provider ID to be manually specified. This is most useful when there is an existing provider ID that must be used to conform to existing diagnostic infrastructure.

func (*Provider) Close 

func (provider *Provider) Close() error

Close unregisters the provider.

func (*Provider) IsEnabled 

func (provider *Provider) IsEnabled() bool

IsEnabled calls IsEnabledForLevelAndKeywords with LevelAlways and all keywords set.

func (*Provider) IsEnabledForLevel 

func (provider *Provider) IsEnabledForLevel(level Level) bool

IsEnabledForLevel calls IsEnabledForLevelAndKeywords with the specified level and all keywords set.

func (*Provider) IsEnabledForLevelAndKeywords 

func (provider *Provider) IsEnabledForLevelAndKeywords(level Level, keywords uint64) bool

IsEnabledForLevelAndKeywords allows event producer code to check if there are any event sessions that are interested in an event, based on the event level and keywords. Although this check happens automatically in the ETW infrastructure, it can be useful to check if an event will actually be consumed before doing expensive work to build the event data.

func (*Provider) String 

func (provider *Provider) String() string

String returns the `provider`.ID as a string

func (*Provider) WriteEvent 

func (provider *Provider) WriteEvent(name string, eventOpts []EventOpt, fieldOpts []FieldOpt) error

WriteEvent writes a single ETW event from the provider. The event is constructed based on the EventOpt and FieldOpt values that are passed as opts.

func (*Provider) WriteEventRaw 

func (provider *Provider) WriteEventRaw(
	descriptor *EventDescriptor,
	activityID *windows.GUID,
	relatedActivityID *windows.GUID,
	metadataBlobs [][]byte,
	dataBlobs [][]byte) error

WriteEventRaw writes a single ETW event from the provider. This function is less abstracted than WriteEvent, and presents a fairly direct interface to the event writing functionality. It expects a series of event metadata and event data blobs to be passed in, which must conform to the TraceLogging schema. The functions on EventMetadata and EventData can help with creating these blobs. The blobs of each type are effectively concatenated together by the ETW infrastructure.

type ProviderState 

type ProviderState uint32

ProviderState informs the provider EnableCallback what action is being performed. 

const (
	// ProviderStateDisable indicates the provider is being disabled.
	ProviderStateDisable ProviderState = iota
	// ProviderStateEnable indicates the provider is being enabled.
	ProviderStateEnable
	// ProviderStateCaptureState indicates the provider is having its current
	// state snap-shotted.
	ProviderStateCaptureState
)

Source Files

View all Source files

Directories

Path Synopsis
Shows a sample usage of the ETW logging package.
 Shows a sample usage of the ETW logging package.

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.