package etw

import "github.com/Microsoft/go-winio/pkg/etw"

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 ¶

• type Channel
• type EnableCallback
• type EventOpt
• func WithActivityID(activityID guid.GUID) EventOpt
• func WithChannel(channel Channel) EventOpt
• func WithEventOpts(opts ...EventOpt) []EventOpt
• func WithKeyword(keyword uint64) EventOpt
• func WithLevel(level Level) EventOpt
• func WithOpcode(opcode Opcode) EventOpt
• func WithRelatedActivityID(activityID guid.GUID) EventOpt
• func WithTags(newTags uint32) EventOpt
• type FieldOpt
• func BoolArray(name string, values []bool) FieldOpt
• func BoolField(name string, value bool) FieldOpt
• func Float32Array(name string, values []float32) FieldOpt
• func Float32Field(name string, value float32) FieldOpt
• func Float64Array(name string, values []float64) FieldOpt
• func Float64Field(name string, value float64) FieldOpt
• func Int16Array(name string, values []int16) FieldOpt
• func Int16Field(name string, value int16) FieldOpt
• func Int32Array(name string, values []int32) FieldOpt
• func Int32Field(name string, value int32) FieldOpt
• func Int64Array(name string, values []int64) FieldOpt
• func Int64Field(name string, value int64) FieldOpt
• func Int8Array(name string, values []int8) FieldOpt
• func Int8Field(name string, value int8) FieldOpt
• func IntArray(name string, values []int) FieldOpt
• func IntField(name string, value int) FieldOpt
• func SmartField(name string, v interface{}) FieldOpt
• func StringArray(name string, values []string) FieldOpt
• func StringField(name string, value string) FieldOpt
• func Struct(name string, opts ...FieldOpt) FieldOpt
• func Time(name string, value time.Time) FieldOpt
• func Uint16Array(name string, values []uint16) FieldOpt
• func Uint16Field(name string, value uint16) FieldOpt
• func Uint32Array(name string, values []uint32) FieldOpt
• func Uint32Field(name string, value uint32) FieldOpt
• func Uint64Array(name string, values []uint64) FieldOpt
• func Uint64Field(name string, value uint64) FieldOpt
• func Uint8Array(name string, values []uint8) FieldOpt
• func Uint8Field(name string, value uint8) FieldOpt
• func UintArray(name string, values []uint) FieldOpt
• func UintField(name string, value uint) FieldOpt
• func UintptrArray(name string, values []uintptr) FieldOpt
• func UintptrField(name string, value uintptr) FieldOpt
• func WithFields(opts ...FieldOpt) []FieldOpt
• type Level
• type Opcode
• type Provider
• func NewProvider(name string, callback EnableCallback) (provider *Provider, err error)
• func (provider *Provider) Close() error
• func (provider *Provider) IsEnabled() bool
• func (provider *Provider) IsEnabledForLevel(level Level) bool
• func (provider *Provider) IsEnabledForLevelAndKeywords(level Level, keywords uint64) bool
• func (provider *Provider) String() string
• func (provider *Provider) WriteEvent(name string, eventOpts []EventOpt, fieldOpts []FieldOpt) error
• type ProviderState

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(guid.GUID, ProviderState, Level, uint64, uint64, uintptr)

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

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 guid.GUID) EventOpt

WithActivityID specifies the activity ID of the event to be written.

func WithChannel ¶

func WithChannel(channel Channel) EventOpt

WithChannel specifies the channel of the event to be written.

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 WithOpcode ¶

func WithOpcode(opcode Opcode) EventOpt

WithOpcode specifies the opcode of the event to be written.

func WithRelatedActivityID ¶

func WithRelatedActivityID(activityID guid.GUID) EventOpt

WithRelatedActivityID specifies the parent activity ID of the event to be written.

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 SmartField ¶

func SmartField(name string, v interface{}) FieldOpt

Currently, we support logging basic builtin types (int, string, etc), slices of basic builtin types, error, types derived from the basic types (e.g. "type foo int"), and structs (recursively logging their fields). We do not support slices of derived types (e.g. "[]foo").

For types that we don't support, the value is formatted via fmt.Sprint, and we also log a message that the type is unsupported along with the formatted type. The intent of this is to make it easier to see which types are not supported in traces, so we can evaluate adding support for more types in the future.

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 Time ¶

func Time(name string, value time.Time) FieldOpt

Time adds a time to the event.

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 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 from winmeta.xml in the Windows SDK.

type Opcode ¶

type Opcode uint8

Opcode represents the operation that the event indicates is being performed.

const (
	// OpcodeInfo indicates an informational event.
	OpcodeInfo Opcode = iota
	// OpcodeStart indicates the start of an operation.
	OpcodeStart
	// OpcodeStop indicates the end of an operation.
	OpcodeStop
	// OpcodeDCStart indicates the start of a provider capture state operation.
	OpcodeDCStart
	// OpcodeDCStop indicates the end of a provider capture state operation.
	OpcodeDCStop
)

Predefined ETW opcodes from winmeta.xml in the Windows SDK.

type Provider ¶

type Provider struct {
	ID guid.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 (*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.

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 ¶

etw.go eventdata.go eventdatadescriptor.go eventdescriptor.go eventmetadata.go eventopt.go fieldopt.go provider.go providerglobal.go

Directories ¶