etw

package
v0.4.15 Latest Latest
Warning

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

 Go to latest Published: Jan 18, 2020 License: MIT Imports: 14 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(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 NewProviderWithID 

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 

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

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.