Class Win32::EventLog
In: eventlog.rb
Parent: Object

The EventLog class encapsulates an Event Log source and provides methods for interacting with that source.


Included Modules

Windows::Error Windows::EventLog Windows::Security Windows::Registry Windows::SystemInfo Windows::Library Windows::Synchronize Windows::Handle

Classes and Modules

Class Win32::EventLog::Error


VERSION = '0.4.4'
SUCCESS = EVENTLOG_SUCCESS   Aliased event types
BUFFER_SIZE = 1024 * 64
MAX_SIZE = 256
BASE_KEY = "SYSTEM\\CurrentControlSet\\Services\\EventLog\\"
EventLogStruct ='EventLogStruct', :record_number, :time_generated, :time_written, :event_id, :event_type, :category, :source, :computer, :user, :string_inserts, :description   The EventLogStruct encapsulates a single event log record.

External Aliases

new -> open


file  [R]  The name of the file used in the EventLog.open_backup method. This is set to nil if the file was not opened using the EventLog.open_backup method.
server  [R]  The name of the server which the event log is reading from.
source  [R]  The name of the event log source. This will typically be ‘Application’, ‘System’ or ‘Security’, but could also refer to a custom event log source.

Public Class methods

Adds an event source to the registry. The following are valid keys:

  • source - Source name. Set to "Application" by default
  • key_name - Name stored as the registry key
  • category_count - Number of supported (custom) categories
  • event_message_file - File (dll) that defines events
  • category_message_file - File (dll) that defines categories
  • supported_types - See the ‘event types’ constants

Of these keys, only key_name is mandatory. An ArgumentError is raised if you attempt to use an invalid key. If supported_types is not specified then the following value is used:

EventLog::ERROR | EventLog::WARN | EventLog::INFO

The event_message_file and category_message_file are typically, though not necessarily, the same file. See the documentation on .mc files for more details.

Opens a handle to the new EventLog source on server, or the local machine if no host is specified. Typically, your source will be ‘Application, ‘Security’ or ‘System’, although you can specify a custom log file as well.

If a custom, registered log file name cannot be found, the event logging service opens the ‘Application’ log file. This is the behavior of the underlying Windows function, not my own doing.

Nearly identical to, except that the source is a backup file and not an event source (and there is no default).

This class method is nearly identical to the EventLog#read instance method, except that it takes a source and server as the first two arguments.

Public Instance methods

Backs up the event log to file. Note that you cannot backup to a file that already exists or a Error will be raised.

Clears the EventLog. If backup_file is provided, it backs up the event log to that file first.

Closes the EventLog handle. Automatically closed for you if you use the block form of

Indicates whether or not the event log is full.

Yields an EventLogStruct every time a record is written to the event log. Unlike EventLog#tail, this method breaks out of the block after the event.

Raises an Error if no block is provided.

Returns the absolute record number of the oldest record. Note that this is not guaranteed to be 1 because event log records can be overwritten.

EventLog#read(flags=nil, offset=0) EventLog#read(flags=nil, offset=0){ |log| … }

Iterates over each record in the event log, yielding a EventLogStruct for each record. The offset value is only used when used in conjunction with the EventLog::SEEK_READ flag. Otherwise, it is ignored. If no flags are specified, then the default flags are:


Note that, if you‘re performing a SEEK_READ, then the offset must refer to a record number that actually exists. The default of 0 may or may not work for your particular event log.

The EventLogStruct struct contains the following members:

record_number # Fixnum time_generated # Time time_written # Time event_id # Fixnum event_type # String category # String source # String computer # String user # String or nil description # String or nil string_inserts # An array of Strings or nil

If no block is given the method returns an array of EventLogStruct‘s.

EventLog#report_event(key => value, …)

Writes an event to the event log. The following are valid keys:

source # Event log source name. Defaults to "Application" event_id # Event ID (defined in event message file) category # Event category (defined in category message file) data # String that is written to the log event_type # Type of event, e.g. EventLog::ERROR, etc.

The event_type keyword is the only mandatory keyword. The others are optional. Although the source defaults to "Application", I recommend that you create an application specific event source and use that instead. See the ‘EventLog.add_event_source’ method for more details.

The event_id and category values are defined in the message file(s) that you created for your application. See the tutorial.txt file for more details on how to create a message file.

An ArgumentError is raised if you attempt to use an invalid key.

Yields an EventLogStruct every time a record is written to the event log, once every frequency seconds. Unlike EventLog#notify_change, this method does not break out of the block after the event. The read frequency is set to 5 seconds by default.

Raises an Error if no block is provided.

The delay between reads is due to the nature of the Windows event log. It is not really designed to be tailed in the manner of a Unix syslog, for example, in that not nearly as many events are typically recorded. It‘s just not designed to be polled that heavily.

Returns the total number of records for the given event log.


Alias for report_event