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 ¶
- type Channel
- type EnableCallback
- type EventData
- func (ed *EventData) Bytes() []byte
- func (ed *EventData) WriteInt16(value int16)
- func (ed *EventData) WriteInt32(value int32)
- func (ed *EventData) WriteInt64(value int64)
- func (ed *EventData) WriteInt8(value int8)
- func (ed *EventData) WriteString(data string)
- func (ed *EventData) WriteUint16(value uint16)
- func (ed *EventData) WriteUint32(value uint32)
- func (ed *EventData) WriteUint64(value uint64)
- func (ed *EventData) WriteUint8(value uint8)
- type EventDescriptor
- type EventMetadata
- func (em *EventMetadata) Bytes() []byte
- func (em *EventMetadata) WriteArray(name string, inType InType, outType OutType, tags uint32)
- func (em *EventMetadata) WriteCountedArray(name string, count uint16, inType InType, outType OutType, tags uint32)
- func (em *EventMetadata) WriteEventHeader(name string, tags uint32)
- func (em *EventMetadata) WriteField(name string, inType InType, outType OutType, tags uint32)
- func (em *EventMetadata) WriteStruct(name string, fieldCount uint8, tags uint32)
- type EventOpt
- func WithActivityID(activityID *windows.GUID) EventOpt
- func WithChannel(channel Channel) EventOpt
- func WithEventOpts(opts ...EventOpt) []EventOpt
- func WithKeyword(keyword uint64) EventOpt
- func WithLevel(level Level) EventOpt
- func WithRelatedActivityID(activityID *windows.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 StringArray(name string, values []string) FieldOpt
- func StringField(name string, value string) FieldOpt
- func Struct(name string, opts ...FieldOpt) 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 InType
- type Level
- type OutType
- type Provider
- 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
- func (provider *Provider) WriteEventRaw(descriptor *EventDescriptor, activityID *windows.GUID, ...) error
- type ProviderState
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 ¶
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 ¶
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 ¶
WriteInt16 appends a int16 to the buffer.
func (*EventData) WriteInt32 ¶
WriteInt32 appends a int32 to the buffer.
func (*EventData) WriteInt64 ¶
WriteInt64 appends a int64 to the buffer.
func (*EventData) WriteString ¶
WriteString appends a string, including the null terminator, to the buffer.
func (*EventData) WriteUint16 ¶
WriteUint16 appends a uint16 to the buffer.
func (*EventData) WriteUint32 ¶
WriteUint32 appends a uint32 to the buffer.
func (*EventData) WriteUint64 ¶
WriteUint64 appends a uint64 to the buffer.
func (*EventData) WriteUint8 ¶
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 WithChannel ¶
func WithEventOpts ¶
WithEventOpts returns the variadic arguments as a single slice.
func WithKeyword ¶
WithKeyword specifies the keywords of the event to be written. Multiple uses of this option are OR'd together.
func WithRelatedActivityID ¶
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 Float32Array ¶
Float32Array adds an array of float32 to the event.
func Float32Field ¶
Float32Field adds a single float32 field to the event.
func Float64Array ¶
Float64Array adds an array of float64 to the event.
func Float64Field ¶
Float64Field adds a single float64 field to the event.
func Int16Array ¶
Int16Array adds an array of int16 to the event.
func Int16Field ¶
Int16Field adds a single int16 field to the event.
func Int32Array ¶
Int32Array adds an array of int32 to the event.
func Int32Field ¶
Int32Field adds a single int32 field to the event.
func Int64Array ¶
Int64Array adds an array of int64 to the event.
func Int64Field ¶
Int64Field adds a single int64 field to the event.
func StringArray ¶
StringArray adds an array of string to the event.
func StringField ¶
StringField adds a single string field to the event.
func Struct ¶
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 ¶
Uint16Array adds an array of uint16 to the event.
func Uint16Field ¶
Uint16Field adds a single uint16 field to the event.
func Uint32Array ¶
Uint32Array adds an array of uint32 to the event.
func Uint32Field ¶
Uint32Field adds a single uint32 field to the event.
func Uint64Array ¶
Uint64Array adds an array of uint64 to the event.
func Uint64Field ¶
Uint64Field adds a single uint64 field to the event.
func Uint8Array ¶
Uint8Array adds an array of uint8 to the event.
func Uint8Field ¶
Uint8Field adds a single uint8 field to the event.
func UintptrArray ¶
UintptrArray adds an array of uintptr to the event.
func UintptrField ¶
UintptrField adds a single uintptr field to the event.
func WithFields ¶
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.
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 ¶
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) IsEnabled ¶
IsEnabled calls IsEnabledForLevelAndKeywords with LevelAlways and all keywords set.
func (*Provider) IsEnabledForLevel ¶
IsEnabledForLevel calls IsEnabledForLevelAndKeywords with the specified level and all keywords set.
func (*Provider) IsEnabledForLevelAndKeywords ¶
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) WriteEvent ¶
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 )