eventlog

The EventLog Backend for Deck

The eventlog backend allows log messages to be sent to Windows Event Log.

The eventlog backend only supports the Windows platform.

Init

The eventlog backend takes a source setup parameter. source corresponds to the name of the Event Log message source. The source must be registered with Event Log for events to render properly in Event Viewer.

Attributes

eventlog.EventID

The eventlog package exports the EventID attribute. This attribute allows events to be stored with custom Event IDs. The Event ID will default to 1 if not specified.

Details & Features

Source Registration

Event Log requires message sources to be registered in order for events to render properly in Event Viewer. This is a one-time operation that creates registry keys. Event Log must be supplied with a Message File which exports any and all Event IDs the application will use.

It is recommended to perform event registration as part of application setup or installation. Registration has to be done with administrator privileges, and only needs to happen once per source.

The eventlog backend provides two helpers which may be used to perform the source registration: InitWithInstall and InitWithDefaultInstall. These helpers have a couple caveats:

1. They will attempt to register the source every time they're called (every time Init happens), which is somewhat wasteful given that registration does not need to happen every time an application wants to log to Event Log.
2. They must be called with administrator-level privileges, which means they are inappropriate to use in any applications running with user-level privileges. In these scenarios, use application installer code to perform the registration in advance.

InitWithInstall requires the user to provide their own message file. The message file must export all event IDs used by the application.

InitWithDefaultInstall leverages code in the underlying eventlog package to register %SystemRoot%\System32\EventCreate.exe as the message file. This file is provided with most modern Windows versions, and is a safe bet for many simple situations where the user does not want to provide their own message file, however there is one important limitation: EventCreate.exe does not support the full range of possible Event IDs. To use Event IDs greater than ~1000, you will need to provide a different message file.

Usage

import (
  github.com/google/deck
  github.com/google/deck/backends/eventlog
)

...

func main() {
  evt, err := eventlog.Init("My Application")
  if err != nil {
      os.Exit(1)
  }
  deck.Add(evt)
  deck.InfoA("A Windows event with Event ID.").With(eventlog.EventID(10)).Go()
}