From 87532d1cfecaa30ec76bc0b281875615ffb20a8f Mon Sep 17 00:00:00 2001 From: Hamza El-Saawy <84944216+helsaawy@users.noreply.github.com> Date: Wed, 27 Apr 2022 15:00:13 -0400 Subject: [PATCH] Set ETW event name and options for logrus hook (#245) * ETW name and options functionality Added functionality to set the event (task) name and options (such as event or associated event ID) for ETW events created by the hook based on the logrus.Entry fields. Signed-off-by: Hamza El-Saawy * PR: export and comment Signed-off-by: Hamza El-Saawy --- pkg/etwlogrus/hook.go | 77 +++++++++++++++++++++++++++++++++++-------- pkg/etwlogrus/opts.go | 53 +++++++++++++++++++++++++++++ 2 files changed, 117 insertions(+), 13 deletions(-) create mode 100644 pkg/etwlogrus/opts.go diff --git a/pkg/etwlogrus/hook.go b/pkg/etwlogrus/hook.go index 4332af56..8cf7baa1 100644 --- a/pkg/etwlogrus/hook.go +++ b/pkg/etwlogrus/hook.go @@ -1,35 +1,74 @@ +//go:build windows // +build windows package etwlogrus import ( + "errors" "sort" - "github.com/Microsoft/go-winio/pkg/etw" "github.com/sirupsen/logrus" + + "github.com/Microsoft/go-winio/pkg/etw" ) +const defaultEventName = "LogrusEntry" + +// ErrNoProvider is returned when a hook is created without a provider being configured. +var ErrNoProvider = errors.New("no ETW registered provider") + +// HookOpt is an option to change the behavior of the Logrus ETW hook +type HookOpt func(*Hook) error + // Hook is a Logrus hook which logs received events to ETW. type Hook struct { provider *etw.Provider closeProvider bool + // allows setting the entry name + getName func(*logrus.Entry) string + // returns additional options to add to the event + getEventsOpts func(*logrus.Entry) []etw.EventOpt } // NewHook registers a new ETW provider and returns a hook to log from it. The // provider will be closed when the hook is closed. -func NewHook(providerName string) (*Hook, error) { - provider, err := etw.NewProvider(providerName, nil) - if err != nil { - return nil, err - } +func NewHook(providerName string, opts ...HookOpt) (*Hook, error) { + opts = append(opts, WithNewETWProvider(providerName)) - return &Hook{provider, true}, nil + return NewHookFromOpts(opts...) } // NewHookFromProvider creates a new hook based on an existing ETW provider. The // provider will not be closed when the hook is closed. -func NewHookFromProvider(provider *etw.Provider) (*Hook, error) { - return &Hook{provider, false}, nil +func NewHookFromProvider(provider *etw.Provider, opts ...HookOpt) (*Hook, error) { + opts = append(opts, WithExistingETWProvider(provider)) + + return NewHookFromOpts(opts...) +} + +// NewHookFromOpts creates a new hook with the provided options. +// An error is returned if the hook does not have a valid provider. +func NewHookFromOpts(opts ...HookOpt) (*Hook, error) { + h := defaultHook() + + for _, o := range opts { + if err := o(h); err != nil { + return nil, err + } + } + return h, h.validate() +} + +func defaultHook() *Hook { + h := &Hook{} + return h +} + +func (h *Hook) validate() error { + if h.provider == nil { + return ErrNoProvider + } + return nil } // Levels returns the set of levels that this hook wants to receive log entries @@ -58,6 +97,21 @@ func (h *Hook) Fire(e *logrus.Entry) error { return nil } + name := defaultEventName + if h.getName != nil { + if n := h.getName(e); n != "" { + name = n + } + } + + // extra room for two more options in addition to log level to avoid repeated reallocations + // if the user also provides options + opts := make([]etw.EventOpt, 0, 3) + opts = append(opts, etw.WithLevel(level)) + if h.getEventsOpts != nil { + opts = append(opts, h.getEventsOpts(e)...) + } + // Sort the fields by name so they are consistent in each instance // of an event. Otherwise, the fields don't line up in WPA. names := make([]string, 0, len(e.Data)) @@ -88,10 +142,7 @@ func (h *Hook) Fire(e *logrus.Entry) error { // as a session listening for the event having no available space in its // buffers). Therefore, we don't return the error from WriteEvent, as it is // just noise in many cases. - h.provider.WriteEvent( - "LogrusEntry", - etw.WithEventOpts(etw.WithLevel(level)), - fields) + h.provider.WriteEvent(name, opts, fields) return nil } diff --git a/pkg/etwlogrus/opts.go b/pkg/etwlogrus/opts.go new file mode 100644 index 00000000..ea3f2e4f --- /dev/null +++ b/pkg/etwlogrus/opts.go @@ -0,0 +1,53 @@ +//go:build windows + +package etwlogrus + +import ( + "github.com/sirupsen/logrus" + + "github.com/Microsoft/go-winio/pkg/etw" +) + +// etw provider + +// WithNewETWProvider registers a new ETW provider and sets the hook to log using it. +// The provider will be closed when the hook is closed. +func WithNewETWProvider(n string) HookOpt { + return func(h *Hook) error { + provider, err := etw.NewProvider(n, nil) + if err != nil { + return err + } + + h.provider = provider + h.closeProvider = true + return nil + } +} + +// WithExistingETWProvider configures the hook to use an existing ETW provider. +// The provider will not be closed when the hook is closed. +func WithExistingETWProvider(p *etw.Provider) HookOpt { + return func(h *Hook) error { + h.provider = p + h.closeProvider = false + return nil + } +} + +// WithGetName sets the ETW EventName of an event to the value returned by f +// If the name is empty, the default event name will be used. +func WithGetName(f func(*logrus.Entry) string) HookOpt { + return func(h *Hook) error { + h.getName = f + return nil + } +} + +// WithAdditionalEventOpts allows additional ETW event properties (keywords, tags, etc.) to be specified +func WithEventOpts(f func(*logrus.Entry) []etw.EventOpt) HookOpt { + return func(h *Hook) error { + h.getEventsOpts = f + return nil + } +}