go-winio: github.com/microsoft/go-winio/pkg/etw Index | Files | Directories

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

Package Files

etw.go eventdata.go eventdatadescriptor.go eventdescriptor.go eventmetadata.go eventopt.go fieldopt.go newprovider.go provider.go providerglobal.go ptr64_64.go wrapper_64.go

type Channel Uses

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 Uses

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 Uses

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 Uses

func WithActivityID(activityID guid.GUID) EventOpt

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

func WithChannel Uses

func WithChannel(channel Channel) EventOpt

WithChannel specifies the channel of the event to be written.

func WithEventOpts Uses

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

WithEventOpts returns the variadic arguments as a single slice.

func WithKeyword Uses

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 Uses

func WithLevel(level Level) EventOpt

WithLevel specifies the level of the event to be written.

func WithOpcode Uses

func WithOpcode(opcode Opcode) EventOpt

WithOpcode specifies the opcode of the event to be written.

func WithRelatedActivityID Uses

func WithRelatedActivityID(activityID guid.GUID) EventOpt

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

func WithTags Uses

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 Uses

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 Uses

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

BoolArray adds an array of bool to the event.

func BoolField Uses

func BoolField(name string, value bool) FieldOpt

BoolField adds a single bool field to the event.

func Float32Array Uses

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

Float32Array adds an array of float32 to the event.

func Float32Field Uses

func Float32Field(name string, value float32) FieldOpt

Float32Field adds a single float32 field to the event.

func Float64Array Uses

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

Float64Array adds an array of float64 to the event.

func Float64Field Uses

func Float64Field(name string, value float64) FieldOpt

Float64Field adds a single float64 field to the event.

func Int16Array Uses

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

Int16Array adds an array of int16 to the event.

func Int16Field Uses

func Int16Field(name string, value int16) FieldOpt

Int16Field adds a single int16 field to the event.

func Int32Array Uses

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

Int32Array adds an array of int32 to the event.

func Int32Field Uses

func Int32Field(name string, value int32) FieldOpt

Int32Field adds a single int32 field to the event.

func Int64Array Uses

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

Int64Array adds an array of int64 to the event.

func Int64Field Uses

func Int64Field(name string, value int64) FieldOpt

Int64Field adds a single int64 field to the event.

func Int8Array Uses

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

Int8Array adds an array of int8 to the event.

func Int8Field Uses

func Int8Field(name string, value int8) FieldOpt

Int8Field adds a single int8 field to the event.

func IntArray Uses

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

IntArray adds an array of int to the event.

func IntField Uses

func IntField(name string, value int) FieldOpt

IntField adds a single int field to the event.

func SmartField Uses

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 Uses

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

StringArray adds an array of string to the event.

func StringField Uses

func StringField(name string, value string) FieldOpt

StringField adds a single string field to the event.

func Struct Uses

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 Uses

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

Time adds a time to the event.

func Uint16Array Uses

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

Uint16Array adds an array of uint16 to the event.

func Uint16Field Uses

func Uint16Field(name string, value uint16) FieldOpt

Uint16Field adds a single uint16 field to the event.

func Uint32Array Uses

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

Uint32Array adds an array of uint32 to the event.

func Uint32Field Uses

func Uint32Field(name string, value uint32) FieldOpt

Uint32Field adds a single uint32 field to the event.

func Uint64Array Uses

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

Uint64Array adds an array of uint64 to the event.

func Uint64Field Uses

func Uint64Field(name string, value uint64) FieldOpt

Uint64Field adds a single uint64 field to the event.

func Uint8Array Uses

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

Uint8Array adds an array of uint8 to the event.

func Uint8Field Uses

func Uint8Field(name string, value uint8) FieldOpt

Uint8Field adds a single uint8 field to the event.

func UintArray Uses

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

UintArray adds an array of uint to the event.

func UintField Uses

func UintField(name string, value uint) FieldOpt

UintField adds a single uint field to the event.

func UintptrArray Uses

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

UintptrArray adds an array of uintptr to the event.

func UintptrField Uses

func UintptrField(name string, value uintptr) FieldOpt

UintptrField adds a single uintptr field to the event.

func WithFields Uses

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

WithFields returns the variadic arguments as a single slice.

type Level Uses

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 Uses

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 Uses

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 Uses

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 Uses

func NewProviderWithID(name string, id guid.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 Uses

func (provider *Provider) Close() error

Close unregisters the provider.

func (*Provider) IsEnabled Uses

func (provider *Provider) IsEnabled() bool

IsEnabled calls IsEnabledForLevelAndKeywords with LevelAlways and all keywords set.

func (*Provider) IsEnabledForLevel Uses

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

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

func (*Provider) IsEnabledForLevelAndKeywords Uses

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 Uses

func (provider *Provider) String() string

String returns the `provider`.ID as a string

func (*Provider) WriteEvent Uses

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 Uses

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
)

Directories

PathSynopsis
sampleShows a sample usage of the ETW logging package.

Package etw imports 14 packages (graph). Updated 2019-07-26. Refresh now. Tools for package owners.