Documentation
¶
Overview ¶
Package evtsubscribe provides helpers for reading Windows Event Logs with a Pull Subscription
Index ¶
- Constants
- type PullSubscription
- type PullSubscriptionOption
- func WithBookmarkSaver(saver evtbookmark.Saver) PullSubscriptionOption
- func WithEventBatchCount(count uint) PullSubscriptionOption
- func WithSession(session evtsession.Session) PullSubscriptionOption
- func WithStartAtOldestRecord() PullSubscriptionOption
- func WithStartMode(mode string) 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
}
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 WithBookmarkSaver ¶ added in v0.73.0
func WithBookmarkSaver(saver evtbookmark.Saver) PullSubscriptionOption
WithBookmarkSaver provides an interface for the subscription to load and save persisted bookmarks.
On Start(), the subscription will attempt to load a persisted bookmark.
- If successful, the subscription starts from that position.
- If loading fails or returns an empty string, the subscription uses the startMode to determine where to start reading events. When a bookmark is created by FromLatestEvent (start mode "now"), it is immediately persisted.
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
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 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 WithStartMode ¶ added in v0.73.0
func WithStartMode(mode string) PullSubscriptionOption
WithStartMode sets the start mode ("oldest" or "now") used when no bookmark exists. This option is only used when no bookmark is loaded via WithBookmarkSaver.
- "oldest": start from oldest event in log (EvtSubscribeStartAtOldestRecord)
- "now": use FromLatestEvent to create bookmark from latest matching event
If startMode is "now" and no matching events are found, the subscription will start with EvtSubscribeToFutureEvents to capture any new events that match the query. The default mode if not specified is "now" (EvtSubscribeToFutureEvents).
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