diff --git a/internal/etw/etw.go b/internal/etw/etw.go new file mode 100644 index 0000000..da905ec --- /dev/null +++ b/internal/etw/etw.go @@ -0,0 +1,14 @@ +// 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. +package etw + +//go:generate go run $GOROOT/src/syscall/mksyscall_windows.go -output zsyscall_windows.go etw.go + +//sys eventRegister(providerId *windows.GUID, callback uintptr, callbackContext uintptr, providerHandle *providerHandle) (win32err error) = advapi32.EventRegister +//sys eventUnregister(providerHandle providerHandle) (win32err error) = advapi32.EventUnregister +//sys eventWriteTransfer(providerHandle providerHandle, descriptor *EventDescriptor, activityID *windows.GUID, relatedActivityID *windows.GUID, dataDescriptorCount uint32, dataDescriptors *eventDataDescriptor) (win32err error) = advapi32.EventWriteTransfer diff --git a/internal/etw/eventdata.go b/internal/etw/eventdata.go new file mode 100644 index 0000000..fc270e1 --- /dev/null +++ b/internal/etw/eventdata.go @@ -0,0 +1,45 @@ +package etw + +import ( + "bytes" + "encoding/binary" +) + +// EventData maintains a buffer which builds up the data for an ETW event. It +// needs to be paired with EventMetadata which describes the event. +type EventData struct { + buffer bytes.Buffer +} + +// 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 (ed *EventData) Bytes() []byte { + return ed.buffer.Bytes() +} + +// WriteString appends a string, including the null terminator, to the buffer. +func (ed *EventData) WriteString(data string) { + ed.buffer.WriteString(data) + ed.buffer.WriteByte(0) +} + +// WriteUint8 appends a uint8 to the buffer. +func (ed *EventData) WriteUint8(value uint8) { + ed.buffer.WriteByte(value) +} + +// WriteUint16 appends a uint16 to the buffer. +func (ed *EventData) WriteUint16(value uint16) { + binary.Write(&ed.buffer, binary.LittleEndian, value) +} + +// WriteUint32 appends a uint32 to the buffer. +func (ed *EventData) WriteUint32(value uint32) { + binary.Write(&ed.buffer, binary.LittleEndian, value) +} + +// WriteUint64 appends a uint64 to the buffer. +func (ed *EventData) WriteUint64(value uint64) { + binary.Write(&ed.buffer, binary.LittleEndian, value) +} diff --git a/internal/etw/eventdatadescriptor.go b/internal/etw/eventdatadescriptor.go new file mode 100644 index 0000000..e7c53cf --- /dev/null +++ b/internal/etw/eventdatadescriptor.go @@ -0,0 +1,29 @@ +package etw + +import ( + "unsafe" +) + +type eventDataDescriptorType uint8 + +const ( + eventDataDescriptorTypeUserData eventDataDescriptorType = iota + eventDataDescriptorTypeEventMetadata + eventDataDescriptorTypeProviderMetadata +) + +type eventDataDescriptor struct { + ptr ptr64 + size uint32 + dataType eventDataDescriptorType + reserved1 uint8 + reserved2 uint16 +} + +func newEventDataDescriptor(dataType eventDataDescriptorType, buffer []byte) eventDataDescriptor { + return eventDataDescriptor{ + ptr: ptr64{ptr: unsafe.Pointer(&buffer[0])}, + size: uint32(len(buffer)), + dataType: dataType, + } +} diff --git a/internal/etw/eventdescriptor.go b/internal/etw/eventdescriptor.go new file mode 100644 index 0000000..3946765 --- /dev/null +++ b/internal/etw/eventdescriptor.go @@ -0,0 +1,67 @@ +package etw + +// Channel represents the ETW logging channel that is used. It can be used by +// event consumers to give an event special treatment. +type Channel uint8 + +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 +) + +// 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 Level uint8 + +// Predefined ETW log levels. +const ( + LevelAlways Level = iota + LevelCritical + LevelError + LevelWarning + LevelInfo + LevelVerbose +) + +// EventDescriptor represents various metadata for an ETW event. +type EventDescriptor struct { + id uint16 + version uint8 + Channel Channel + Level Level + Opcode uint8 + Task uint16 + Keyword uint64 +} + +// NewEventDescriptor returns an EventDescriptor initialized for use with +// TraceLogging. +func NewEventDescriptor() *EventDescriptor { + // Standard TraceLogging events default to the TraceLogging channel, and + // verbose level. + return &EventDescriptor{ + Channel: ChannelTraceLogging, + Level: LevelVerbose, + } +} + +// 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 (ed *EventDescriptor) Identity() uint32 { + return (uint32(ed.version) << 16) | uint32(ed.id) +} + +// 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. +func (ed *EventDescriptor) SetIdentity(identity uint32) { + ed.id = uint16(identity) + ed.version = uint8(identity >> 16) +} diff --git a/internal/etw/eventmetadata.go b/internal/etw/eventmetadata.go new file mode 100644 index 0000000..d294027 --- /dev/null +++ b/internal/etw/eventmetadata.go @@ -0,0 +1,177 @@ +package etw + +import ( + "bytes" + "encoding/binary" +) + +// InType indicates the type of data contained in the ETW event. +type InType byte + +// Various InType definitions for TraceLogging. These must match the definitions +// found in TraceLoggingProvider.h in the Windows SDK. +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 +) + +// OutType specifies a hint to the event decoder for how the value should be +// formatted. +type OutType byte + +// Various OutType definitions for TraceLogging. These must match the +// definitions found in TraceLoggingProvider.h in the Windows SDK. +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 +) + +// EventMetadata maintains a buffer which builds up the metadata for an ETW +// event. It needs to be paired with EventData which describes the event. +type EventMetadata struct { + buffer bytes.Buffer +} + +// 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 (em *EventMetadata) Bytes() []byte { + // Finalize the event metadata buffer by filling in the buffer length at the + // beginning. + binary.LittleEndian.PutUint16(em.buffer.Bytes(), uint16(em.buffer.Len())) + return em.buffer.Bytes() +} + +// WriteEventHeader writes the metadata for the start of an event to the buffer. +// This specifies the event name and tags. +func (em *EventMetadata) WriteEventHeader(name string, tags uint32) { + binary.Write(&em.buffer, binary.LittleEndian, uint16(0)) // Length placeholder + em.writeTags(tags) + em.buffer.WriteString(name) + em.buffer.WriteByte(0) // Null terminator for name +} + +func (em *EventMetadata) writeField(name string, inType InType, outType OutType, tags uint32, arrSize uint16) { + em.buffer.WriteString(name) + em.buffer.WriteByte(0) // Null terminator for name + + if outType == OutTypeDefault && tags == 0 { + em.buffer.WriteByte(byte(inType)) + } else { + em.buffer.WriteByte(byte(inType | 128)) + if tags == 0 { + em.buffer.WriteByte(byte(outType)) + } else { + em.buffer.WriteByte(byte(outType | 128)) + em.writeTags(tags) + } + } + + if arrSize != 0 { + binary.Write(&em.buffer, binary.LittleEndian, arrSize) + } +} + +// writeTags writes out the tags value to the event metadata. Tags is a 28-bit +// value, interpreted as bit flags, which are only relevant to the event +// consumer. The event consumer may choose to attribute special meaning to tags +// (e.g. 0x4 could mean the field contains PII). Tags are written as a series of +// bytes, each containing 7 bits of tag value, with the high bit set if there is +// more tag data in the following byte. This allows for a more compact +// representation when not all of the tag bits are needed. +func (em *EventMetadata) writeTags(tags uint32) { + // Only use the top 28 bits of the tags value. + tags &= 0xfffffff + + for { + // Tags are written with the most significant bits (e.g. 21-27) first. + val := tags >> 21 + + if tags&0x1fffff == 0 { + // If there is no more data to write after this, write this value + // without the high bit set, and return. + em.buffer.WriteByte(byte(val & 0x7f)) + return + } + + em.buffer.WriteByte(byte(val | 0x80)) + + tags <<= 7 + } +} + +// WriteField writes the metadata for a simple field to the buffer. +func (em *EventMetadata) WriteField(name string, inType InType, outType OutType, tags uint32) { + em.writeField(name, inType, outType, tags, 0) +} + +// 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 (em *EventMetadata) WriteArray(name string, inType InType, outType OutType, tags uint32) { + em.writeField(name, inType|InTypeArray, outType, tags, 0) +} + +// 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 (em *EventMetadata) WriteCountedArray(name string, count uint16, inType InType, outType OutType, tags uint32) { + em.writeField(name, inType|InTypeCountedArray, outType, tags, count) +} + +// 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. +func (em *EventMetadata) WriteStruct(name string, fieldCount uint8, tags uint32) { + em.writeField(name, InTypeStruct, OutType(fieldCount), tags, 0) +} diff --git a/internal/etw/eventopt.go b/internal/etw/eventopt.go new file mode 100644 index 0000000..3fe0cda --- /dev/null +++ b/internal/etw/eventopt.go @@ -0,0 +1,34 @@ +package etw + +// EventOpt defines the option function type that can be passed to +// Provider.WriteEvent to specify general event options, such as level and +// keyword. +type EventOpt func(*EventDescriptor, *uint32) + +// WithEventOpts returns the variadic arguments as a single slice. +func WithEventOpts(opts ...EventOpt) []EventOpt { + return opts +} + +// WithLevel specifies the level of the event to be written. +func WithLevel(level Level) EventOpt { + return func(descriptor *EventDescriptor, tags *uint32) { + descriptor.Level = level + } +} + +// WithKeyword specifies the keywords of the event to be written. Multiple uses +// of this option are OR'd together. +func WithKeyword(keyword uint64) EventOpt { + return func(descriptor *EventDescriptor, tags *uint32) { + descriptor.Keyword |= keyword + } +} + +// 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. +func WithTags(newTags uint32) EventOpt { + return func(descriptor *EventDescriptor, tags *uint32) { + *tags |= newTags + } +} diff --git a/internal/etw/fieldopt.go b/internal/etw/fieldopt.go new file mode 100644 index 0000000..0e6a20f --- /dev/null +++ b/internal/etw/fieldopt.go @@ -0,0 +1,40 @@ +package etw + +// FieldOpt defines the option function type that can be passed to +// Provider.WriteEvent to add fields to the event. +type FieldOpt func(em *EventMetadata, ed *EventData) + +// WithFields returns the variadic arguments as a single slice. +func WithFields(opts ...FieldOpt) []FieldOpt { + return opts +} + +// StringField adds a single string field to the event. +func StringField(name string, value string) FieldOpt { + return func(em *EventMetadata, ed *EventData) { + em.WriteField(name, InTypeANSIString, OutTypeUTF8, 0) + ed.WriteString(value) + } +} + +// StringArray adds an array of strings to the event. +func StringArray(name string, values []string) FieldOpt { + return func(em *EventMetadata, ed *EventData) { + em.WriteArray(name, InTypeANSIString, OutTypeUTF8, 0) + ed.WriteUint16(uint16(len(values))) + for _, v := range values { + ed.WriteString(v) + } + } +} + +// Struct adds a nested struct to the event, the FieldOpts in the opts argument +// are used to specify the fields of the struct. +func Struct(name string, opts ...FieldOpt) FieldOpt { + return func(em *EventMetadata, ed *EventData) { + em.WriteStruct(name, uint8(len(opts)), 0) + for _, opt := range opts { + opt(em, ed) + } + } +} diff --git a/internal/etw/provider.go b/internal/etw/provider.go new file mode 100644 index 0000000..c413351 --- /dev/null +++ b/internal/etw/provider.go @@ -0,0 +1,228 @@ +package etw + +import ( + "bytes" + "crypto/sha1" + "encoding/binary" + "strings" + "unicode/utf16" + + "golang.org/x/sys/windows" +) + +// 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). +type Provider struct { + ID *windows.GUID + handle providerHandle + metadata []byte + callback EnableCallback + index uint + enabled bool + level Level + keywordAny uint64 + keywordAll uint64 +} + +type providerHandle windows.Handle + +// ProviderState informs the provider EnableCallback what action is being +// performed. +type ProviderState uint32 + +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 +) + +// EnableCallback is the form of the callback function that receives provider +// enable/disable notifications from ETW. +type EnableCallback func(*windows.GUID, ProviderState, Level, uint64, uint64, uintptr) + +func providerCallback(sourceID *windows.GUID, state ProviderState, level Level, matchAnyKeyword uint64, matchAllKeyword uint64, filterData uintptr, i uintptr) { + provider := providers.getProvider(uint(i)) + + switch state { + case ProviderStateDisable: + provider.enabled = false + case ProviderStateEnable: + provider.enabled = true + provider.level = level + provider.keywordAny = matchAnyKeyword + provider.keywordAll = matchAllKeyword + } + + if provider.callback != nil { + provider.callback(sourceID, state, level, matchAnyKeyword, matchAllKeyword, filterData) + } +} + +// providerCallbackAdapter acts as the first-level callback from the C/ETW side +// for provider notifications. Because Go has trouble with callback arguments of +// different size, it has only pointer-sized arguments, which are then cast to +// the appropriate types when calling providerCallback. +func providerCallbackAdapter(sourceID *windows.GUID, state uintptr, level uintptr, matchAnyKeyword uintptr, matchAllKeyword uintptr, filterData uintptr, i uintptr) uintptr { + providerCallback(sourceID, ProviderState(state), Level(level), uint64(matchAnyKeyword), uint64(matchAllKeyword), filterData, i) + return 0 +} + +// providerIDFromName generates a provider ID based on the provider name. It +// uses the same algorithm as used by .NET's EventSource class, which is based +// on RFC 4122. More information on the algorithm can be found here: +// https://blogs.msdn.microsoft.com/dcook/2015/09/08/etw-provider-names-and-guids/ +// The algorithm is roughly: +// Hash = Sha1(namespace + arg.ToUpper().ToUtf16be()) +// Guid = Hash[0..15], with Hash[7] tweaked according to RFC 4122 +func providerIDFromName(name string) *windows.GUID { + buffer := sha1.New() + + namespace := []byte{0x48, 0x2C, 0x2D, 0xB2, 0xC3, 0x90, 0x47, 0xC8, 0x87, 0xF8, 0x1A, 0x15, 0xBF, 0xC1, 0x30, 0xFB} + buffer.Write(namespace) + + binary.Write(buffer, binary.BigEndian, utf16.Encode([]rune(strings.ToUpper(name)))) + + sum := buffer.Sum(nil) + sum[7] = (sum[7] & 0xf) | 0x50 + + return &windows.GUID{ + Data1: binary.LittleEndian.Uint32(sum[0:4]), + Data2: binary.LittleEndian.Uint16(sum[4:6]), + Data3: binary.LittleEndian.Uint16(sum[6:8]), + Data4: [8]byte{sum[8], sum[9], sum[10], sum[11], sum[12], sum[13], sum[14], sum[15]}, + } +} + +// NewProvider creates and registers a new ETW provider. The provider ID is +// generated based on the provider name. +func NewProvider(name string, callback EnableCallback) (provider *Provider, err error) { + return NewProviderWithID(name, providerIDFromName(name), callback) +} + +// 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 NewProviderWithID(name string, id *windows.GUID, callback EnableCallback) (provider *Provider, err error) { + providerCallbackOnce.Do(func() { + globalProviderCallback = windows.NewCallback(providerCallbackAdapter) + }) + + provider = providers.newProvider() + defer func() { + if err != nil { + providers.removeProvider(provider) + } + }() + provider.ID = id + provider.callback = callback + + if err := eventRegister(provider.ID, globalProviderCallback, uintptr(provider.index), &provider.handle); err != nil { + return nil, err + } + + metadata := &bytes.Buffer{} + binary.Write(metadata, binary.LittleEndian, uint16(0)) // Write empty size for buffer (to update later) + metadata.WriteString(name) + metadata.WriteByte(0) // Null terminator for name + binary.LittleEndian.PutUint16(metadata.Bytes(), uint16(metadata.Len())) // Update the size at the beginning of the buffer + provider.metadata = metadata.Bytes() + + return provider, nil +} + +// Close unregisters the provider. +func (provider *Provider) Close() error { + providers.removeProvider(provider) + return eventUnregister(provider.handle) +} + +// IsEnabled calls IsEnabledForLevelAndKeywords with LevelAlways and all +// keywords set. +func (provider *Provider) IsEnabled() bool { + return provider.IsEnabledForLevelAndKeywords(LevelAlways, ^uint64(0)) +} + +// IsEnabledForLevel calls IsEnabledForLevelAndKeywords with the specified level +// and all keywords set. +func (provider *Provider) IsEnabledForLevel(level Level) bool { + return provider.IsEnabledForLevelAndKeywords(level, ^uint64(0)) +} + +// 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 *Provider) IsEnabledForLevelAndKeywords(level Level, keywords uint64) bool { + if !provider.enabled { + return false + } + + // ETW automatically sets the level to 255 if it is specified as 0, so we + // don't need to worry about the level=0 (all events) case. + if level > provider.level { + return false + } + + if keywords != 0 && (keywords&provider.keywordAny == 0 || keywords&provider.keywordAll != provider.keywordAll) { + return false + } + + return true +} + +// 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 *Provider) WriteEvent(name string, eventOpts []EventOpt, fieldOpts []FieldOpt) error { + tags := uint32(0) + descriptor := NewEventDescriptor() + em := &EventMetadata{} + ed := &EventData{} + + // We need to evaluate the EventOpts first since they might change tags, and + // we write out the tags before evaluating FieldOpts. + for _, opt := range eventOpts { + opt(descriptor, &tags) + } + + if !provider.IsEnabledForLevelAndKeywords(descriptor.Level, descriptor.Keyword) { + return nil + } + + em.WriteEventHeader(name, tags) + + for _, opt := range fieldOpts { + opt(em, ed) + } + + return provider.WriteEventRaw(descriptor, [][]byte{em.Bytes()}, [][]byte{ed.Bytes()}) +} + +// 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. +func (provider *Provider) WriteEventRaw(descriptor *EventDescriptor, metadataBlobs [][]byte, dataBlobs [][]byte) error { + dataDescriptorCount := uint32(1 + len(metadataBlobs) + len(dataBlobs)) + dataDescriptors := make([]eventDataDescriptor, 0, dataDescriptorCount) + + dataDescriptors = append(dataDescriptors, newEventDataDescriptor(eventDataDescriptorTypeProviderMetadata, provider.metadata)) + for _, blob := range metadataBlobs { + dataDescriptors = append(dataDescriptors, newEventDataDescriptor(eventDataDescriptorTypeEventMetadata, blob)) + } + for _, blob := range dataBlobs { + dataDescriptors = append(dataDescriptors, newEventDataDescriptor(eventDataDescriptorTypeUserData, blob)) + } + + return eventWriteTransfer(provider.handle, descriptor, nil, nil, dataDescriptorCount, &dataDescriptors[0]) +} diff --git a/internal/etw/providerglobal.go b/internal/etw/providerglobal.go new file mode 100644 index 0000000..28177a1 --- /dev/null +++ b/internal/etw/providerglobal.go @@ -0,0 +1,52 @@ +package etw + +import ( + "sync" +) + +// Because the provider callback function needs to be able to access the +// provider data when it is invoked by ETW, we need to keep provider data stored +// in a global map based on an index. The index is passed as the callback +// context to ETW. +type providerMap struct { + m map[uint]*Provider + i uint + lock sync.Mutex + once sync.Once +} + +var providers = providerMap{ + m: make(map[uint]*Provider), +} + +func (p *providerMap) newProvider() *Provider { + p.lock.Lock() + defer p.lock.Unlock() + + i := p.i + p.i++ + + provider := &Provider{ + index: i, + } + + p.m[i] = provider + return provider +} + +func (p *providerMap) removeProvider(provider *Provider) { + p.lock.Lock() + defer p.lock.Unlock() + + delete(p.m, provider.index) +} + +func (p *providerMap) getProvider(index uint) *Provider { + p.lock.Lock() + defer p.lock.Unlock() + + return p.m[index] +} + +var providerCallbackOnce sync.Once +var globalProviderCallback uintptr diff --git a/internal/etw/ptr64_32.go b/internal/etw/ptr64_32.go new file mode 100644 index 0000000..435ec3c --- /dev/null +++ b/internal/etw/ptr64_32.go @@ -0,0 +1,16 @@ +// +build 386 arm + +package etw + +import ( + "unsafe" +) + +// byteptr64 defines a struct containing a pointer. The struct is guaranteed to +// be 64 bits, regardless of the actual size of a pointer on the platform. This +// is intended for use with certain Windows APIs that expect a pointer as a +// ULONGLONG. +type ptr64 struct { + ptr unsafe.Pointer + _ uint32 +} diff --git a/internal/etw/ptr64_64.go b/internal/etw/ptr64_64.go new file mode 100644 index 0000000..903d3c0 --- /dev/null +++ b/internal/etw/ptr64_64.go @@ -0,0 +1,15 @@ +// +build amd64 arm64 + +package etw + +import ( + "unsafe" +) + +// byteptr64 defines a struct containing a pointer. The struct is guaranteed to +// be 64 bits, regardless of the actual size of a pointer on the platform. This +// is intended for use with certain Windows APIs that expect a pointer as a +// ULONGLONG. +type ptr64 struct { + ptr unsafe.Pointer +} diff --git a/internal/etw/sample/sample.go b/internal/etw/sample/sample.go new file mode 100644 index 0000000..20cef4a --- /dev/null +++ b/internal/etw/sample/sample.go @@ -0,0 +1,109 @@ +// Shows a sample usage of the ETW logging package. +package main + +import ( + "bufio" + "encoding/binary" + "encoding/hex" + "fmt" + "os" + + "github.com/Microsoft/go-winio/internal/etw" + "github.com/sirupsen/logrus" + + "golang.org/x/sys/windows" +) + +func callback(sourceID *windows.GUID, state etw.ProviderState, level etw.Level, matchAnyKeyword uint64, matchAllKeyword uint64, filterData uintptr) { + fmt.Printf("Callback: isEnabled=%d, level=%d, matchAnyKeyword=%d\n", state, level, matchAnyKeyword) +} + +func guidToString(guid *windows.GUID) string { + data1 := make([]byte, 4) + binary.BigEndian.PutUint32(data1, guid.Data1) + data2 := make([]byte, 2) + binary.BigEndian.PutUint16(data2, guid.Data2) + data3 := make([]byte, 2) + binary.BigEndian.PutUint16(data3, guid.Data3) + return fmt.Sprintf( + "%s-%s-%s-%s-%s", + hex.EncodeToString(data1), + hex.EncodeToString(data2), + hex.EncodeToString(data3), + hex.EncodeToString(guid.Data4[:2]), + hex.EncodeToString(guid.Data4[2:])) +} + +func main() { + provider, err := etw.NewProvider("TestProvider", callback) + + if err != nil { + logrus.Error(err) + return + } + defer func() { + if err := provider.Close(); err != nil { + logrus.Error(err) + } + }() + + fmt.Println("Provider ID:", guidToString(provider.ID)) + + reader := bufio.NewReader(os.Stdin) + + fmt.Println("Press enter to log events") + reader.ReadString('\n') + + // Write using high-level API. + if err := provider.WriteEvent( + "TestEvent", + etw.WithEventOpts( + etw.WithLevel(etw.LevelInfo), + etw.WithKeyword(0x140), + ), + etw.WithFields( + etw.StringField("TestField", "Foo"), + etw.StringField("TestField2", "Bar"), + etw.Struct("TestStruct", + etw.StringField("Field1", "Value1"), + etw.StringField("Field2", "Value2")), + etw.StringArray("TestArray", []string{ + "Item1", + "Item2", + "Item3", + "Item4", + "Item5", + })), + ); err != nil { + logrus.Error(err) + return + } + + // Write using low-level API. + descriptor := etw.NewEventDescriptor() + descriptor.Level = etw.LevelInfo + descriptor.Keyword = 0x140 + em := &etw.EventMetadata{} + ed := &etw.EventData{} + em.WriteEventHeader("TestEvent", 0) + em.WriteField("TestField", etw.InTypeANSIString, etw.OutTypeUTF8, 0) + ed.WriteString("Foo") + em.WriteField("TestField2", etw.InTypeANSIString, etw.OutTypeUTF8, 0) + ed.WriteString("Bar") + em.WriteStruct("TestStruct", 2, 0) + em.WriteField("Field1", etw.InTypeANSIString, etw.OutTypeUTF8, 0) + ed.WriteString("Value1") + em.WriteField("Field2", etw.InTypeANSIString, etw.OutTypeUTF8, 0) + ed.WriteString("Value2") + em.WriteArray("TestArray", etw.InTypeANSIString, etw.OutTypeDefault, 0) + ed.WriteUint16(5) + ed.WriteString("Item1") + ed.WriteString("Item2") + ed.WriteString("Item3") + ed.WriteString("Item4") + ed.WriteString("Item5") + if err := provider.WriteEventRaw(descriptor, [][]byte{em.Bytes()}, [][]byte{ed.Bytes()}); err != nil { + logrus.Error(err) + return + } +} diff --git a/internal/etw/zsyscall_windows.go b/internal/etw/zsyscall_windows.go new file mode 100644 index 0000000..5b044ca --- /dev/null +++ b/internal/etw/zsyscall_windows.go @@ -0,0 +1,69 @@ +// Code generated by 'go generate'; DO NOT EDIT. + +package etw + +import ( + "syscall" + "unsafe" + + "golang.org/x/sys/windows" +) + +var _ unsafe.Pointer + +// Do the interface allocations only once for common +// Errno values. +const ( + errnoERROR_IO_PENDING = 997 +) + +var ( + errERROR_IO_PENDING error = syscall.Errno(errnoERROR_IO_PENDING) +) + +// errnoErr returns common boxed Errno values, to prevent +// allocations at runtime. +func errnoErr(e syscall.Errno) error { + switch e { + case 0: + return nil + case errnoERROR_IO_PENDING: + return errERROR_IO_PENDING + } + // TODO: add more here, after collecting data on the common + // error values see on Windows. (perhaps when running + // all.bat?) + return e +} + +var ( + modadvapi32 = windows.NewLazySystemDLL("advapi32.dll") + + procEventRegister = modadvapi32.NewProc("EventRegister") + procEventUnregister = modadvapi32.NewProc("EventUnregister") + procEventWriteTransfer = modadvapi32.NewProc("EventWriteTransfer") +) + +func eventRegister(providerId *windows.GUID, callback uintptr, callbackContext uintptr, providerHandle *providerHandle) (win32err error) { + r0, _, _ := syscall.Syscall6(procEventRegister.Addr(), 4, uintptr(unsafe.Pointer(providerId)), uintptr(callback), uintptr(callbackContext), uintptr(unsafe.Pointer(providerHandle)), 0, 0) + if r0 != 0 { + win32err = syscall.Errno(r0) + } + return +} + +func eventUnregister(providerHandle providerHandle) (win32err error) { + r0, _, _ := syscall.Syscall(procEventUnregister.Addr(), 1, uintptr(providerHandle), 0, 0) + if r0 != 0 { + win32err = syscall.Errno(r0) + } + return +} + +func eventWriteTransfer(providerHandle providerHandle, descriptor *EventDescriptor, activityID *windows.GUID, relatedActivityID *windows.GUID, dataDescriptorCount uint32, dataDescriptors *eventDataDescriptor) (win32err error) { + r0, _, _ := syscall.Syscall6(procEventWriteTransfer.Addr(), 6, uintptr(providerHandle), uintptr(unsafe.Pointer(descriptor)), uintptr(unsafe.Pointer(activityID)), uintptr(unsafe.Pointer(relatedActivityID)), uintptr(dataDescriptorCount), uintptr(unsafe.Pointer(dataDescriptors))) + if r0 != 0 { + win32err = syscall.Errno(r0) + } + return +} diff --git a/pkg/etwlogrus/hook.go b/pkg/etwlogrus/hook.go new file mode 100644 index 0000000..28d079f --- /dev/null +++ b/pkg/etwlogrus/hook.go @@ -0,0 +1,76 @@ +package etwlogrus + +import ( + "fmt" + "reflect" + + "github.com/Microsoft/go-winio/internal/etw" + "github.com/sirupsen/logrus" +) + +// Hook is a Logrus hook which logs received events to ETW. +type Hook struct { + provider *etw.Provider +} + +// NewHook registers a new ETW provider and returns a hook to log from it. +func NewHook(providerName string) (*Hook, error) { + hook := Hook{} + + provider, err := etw.NewProvider(providerName, nil) + if err != nil { + return nil, err + } + hook.provider = provider + + return &hook, nil +} + +// Levels returns the set of levels that this hook wants to receive log entries +// for. +func (h *Hook) Levels() []logrus.Level { + return []logrus.Level{ + logrus.TraceLevel, + logrus.DebugLevel, + logrus.InfoLevel, + logrus.WarnLevel, + logrus.ErrorLevel, + logrus.FatalLevel, + logrus.PanicLevel, + } +} + +// Fire receives each Logrus entry as it is logged, and logs it to ETW. +func (h *Hook) Fire(e *logrus.Entry) error { + level := etw.Level(e.Level) + if !h.provider.IsEnabledForLevel(level) { + return nil + } + + // Reserve extra space for the message field. + fields := make([]etw.FieldOpt, 0, len(e.Data)+1) + + fields = append(fields, etw.StringField("Message", e.Message)) + + for k, v := range e.Data { + switch v := v.(type) { + case string: + fields = append(fields, etw.StringField(k, v)) + default: + fields = append(fields, etw.StringField(k, fmt.Sprintf(" %v", reflect.TypeOf(v), v))) + } + } + + // We could try to map Logrus levels to ETW levels, but we would lose some + // fidelity as there are fewer ETW levels. So instead we use the level + // directly. + return h.provider.WriteEvent( + "LogrusEntry", + etw.WithEventOpts(etw.WithLevel(level)), + fields) +} + +// Close cleans up the hook and closes the ETW provider. +func (h *Hook) Close() error { + return h.provider.Close() +}