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.
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 )
EnableCallback is the form of the callback function that receives provider enable/disable notifications from ETW.
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.
WithActivityID specifies the activity ID of the event to be written.
WithChannel specifies the channel of the event to be written.
WithEventOpts returns the variadic arguments as a single slice.
WithKeyword specifies the keywords of the event to be written. Multiple uses of this option are OR'd together.
WithLevel specifies the level of the event to be written.
WithOpcode specifies the opcode of the event to be written.
WithRelatedActivityID specifies the parent activity ID of the event to be written.
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 func(em *eventMetadata, ed *eventData)
FieldOpt defines the option function type that can be passed to Provider.WriteEvent to add fields to the event.
BoolArray adds an array of bool to the event.
BoolField adds a single bool field to the event.
Float32Array adds an array of float32 to the event.
Float32Field adds a single float32 field to the event.
Float64Array adds an array of float64 to the event.
Float64Field adds a single float64 field to the event.
Int16Array adds an array of int16 to the event.
Int16Field adds a single int16 field to the event.
Int32Array adds an array of int32 to the event.
Int32Field adds a single int32 field to the event.
Int64Array adds an array of int64 to the event.
Int64Field adds a single int64 field to the event.
Int8Array adds an array of int8 to the event.
Int8Field adds a single int8 field to the event.
IntArray adds an array of int to the event.
IntField adds a single int field to the event.
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.
StringArray adds an array of string to the event.
StringField adds a single string field to the event.
Struct adds a nested struct to the event, the FieldOpts in the opts argument are used to specify the fields of the struct.
Time adds a time to the event.
Uint16Array adds an array of uint16 to the event.
Uint16Field adds a single uint16 field to the event.
Uint32Array adds an array of uint32 to the event.
Uint32Field adds a single uint32 field to the event.
Uint64Array adds an array of uint64 to the event.
Uint64Field adds a single uint64 field to the event.
Uint8Array adds an array of uint8 to the event.
Uint8Field adds a single uint8 field to the event.
UintArray adds an array of uint to the event.
UintField adds a single uint field to the event.
UintptrArray adds an array of uintptr to the event.
UintptrField adds a single uintptr field to the event.
WithFields returns the variadic arguments as a single slice.
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.
Predefined ETW log levels from winmeta.xml in the Windows SDK.
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.
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).
NewProvider creates and registers a new ETW provider. The provider ID is generated based on the provider name.
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.
Close unregisters the provider.
IsEnabled calls IsEnabledForLevelAndKeywords with LevelAlways and all keywords set.
IsEnabledForLevel calls IsEnabledForLevelAndKeywords with the specified level and all keywords set.
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.
String returns the `provider`.ID as a string
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.
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 )
|sample||Shows a sample usage of the ETW logging package.|