Documentation
¶
Overview ¶
Package evtsubscribe provides helpers for reading Windows Event Logs with a Pull Subscription
Index ¶
- Constants
- type 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
)
Variables ¶
This section is empty.
Functions ¶
This section is empty.
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
Source Files