evtsubscribe

Documentation

Overview

Package evtsubscribe provides helpers for reading Windows Event Logs with a Pull Subscription

Index

• Constants
• type PullSubscription
  • func NewPullSubscription(channelPath, query string, options ...PullSubscriptionOption) PullSubscription
• type PullSubscriptionOption
  • func WithEventBatchCount(count uint) PullSubscriptionOption
  • func WithSession(session evtsession.Session) PullSubscriptionOption
  • func WithStartAfterBookmark(bookmark evtbookmark.Bookmark) PullSubscriptionOption
  • func WithStartAtOldestRecord() PullSubscriptionOption
  • func WithSubscribeFlags(flags uint) PullSubscriptionOption
  • func WithWindowsEventLogAPI(api evtapi.API) PullSubscriptionOption

Constants

const (
	// DefaultEventBatchCount is the default number of events to fetch per EvtNext call
	DefaultEventBatchCount = 10
)

Types

type PullSubscription

type PullSubscription interface {
	// Start the event subscription
	Start() error

	// Stop the event subscription and free resources.
	// The subscription can be started again after it is stopped.
	//
	// Stop will automatically close any outstanding event record handles associated with this subscription,
	// so you must not continue using any EventRecord returned by GetEvents.
	// https://learn.microsoft.com/en-us/windows/win32/api/winevt/nf-winevt-evtclose
	Stop()

	// Return true is the subscription is active (started), false otherwise (stopped)
	Running() bool

	// GetEvents returns a channel that provides the next available events in the subscription.
	// The channel is closed on error and Error() returns the error.
	// If an error occurs the subscription must be stopped to free resources.
	// You must close every event record handle returned from this function.
	// You must not use any EventRecords after the subscription is stopped. Windows automatically closes
	// all of the event record handles when the subscription handle is closed.
	// https://learn.microsoft.com/en-us/windows/win32/api/winevt/nf-winevt-evtclose
	GetEvents() <-chan []*evtapi.EventRecord

	// Error returns the last error returned from the subscription, for example from EvtNext
	Error() error

	// Set the subscription to "StartAfterBookmark"
	SetBookmark(bookmark evtbookmark.Bookmark)
}

PullSubscription defines the interface for reading Windows Event Logs with a Pull Subscription https://learn.microsoft.com/en-us/windows/win32/wes/subscribing-to-events#pull-subscriptions

func NewPullSubscription

func NewPullSubscription(channelPath, query string, options ...PullSubscriptionOption) PullSubscription

NewPullSubscription constructs a new PullSubscription. Call Stop() when done to release resources.

type PullSubscriptionOption

type PullSubscriptionOption func(*pullSubscription)

PullSubscriptionOption type for option pattern for NewPullSubscription constructor

func WithEventBatchCount

func WithEventBatchCount(count uint) PullSubscriptionOption

WithEventBatchCount sets the maximum number of event records returned per EvtNext call.

Keep this value low, EvtNext will fail if the sum of the size of the events it is returning exceeds a buffer size that is internal to subscription. Note that this maximum is unrelated provided to EvtNext, except in that a lower event batch means the per-event size must be larger to cause the error.

There is a very small difference in performance between requesting 10 events per call and 1000 events per call. The bottlneck by far is EvtFormatMessage. See subscription benchmark tests for results.

Windows limits this to 1024. https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-even6/65f22d62-5f0f-4306-85c4-50fb9e77075b

func WithSession

func WithSession(session evtsession.Session) PullSubscriptionOption

WithSession sets the session option for the subscription to enable collecting event logs from remote hosts. https://learn.microsoft.com/en-us/windows/win32/wes/accessing-remote-computers

func WithStartAfterBookmark

func WithStartAfterBookmark(bookmark evtbookmark.Bookmark) PullSubscriptionOption

WithStartAfterBookmark sets the bookmark for the subscription. The subscription will start reading the event log from the record identified by the bookmark. The subscription will not automatically update the bookmark. The user should update the bookmark to an event record returned from GetEvents() when it makes sense for the user. https://learn.microsoft.com/en-us/windows/win32/wes/bookmarking-events https://learn.microsoft.com/en-us/windows/win32/api/winevt/ne-winevt-evt_subscribe_flags

func WithStartAtOldestRecord

func WithStartAtOldestRecord() PullSubscriptionOption

WithStartAtOldestRecord will start the subscription from the oldest record in the event log. https://learn.microsoft.com/en-us/windows/win32/api/winevt/ne-winevt-evt_subscribe_flags

func WithSubscribeFlags

func WithSubscribeFlags(flags uint) PullSubscriptionOption

WithSubscribeFlags can be used to manually set EVT_SUBSCRIBE_FLAGS https://learn.microsoft.com/en-us/windows/win32/api/winevt/ne-winevt-evt_subscribe_flags

func WithWindowsEventLogAPI

func WithWindowsEventLogAPI(api evtapi.API) PullSubscriptionOption

WithWindowsEventLogAPI sets the API implementation used by the subscription