/ 
Parse-EventLog-0.7
River stage zero No dependents
/ Parse::EventLog

NAME

Parse::EventLog - Parse information from Windows Event Logs

SYNOPSIS

use Parse::EventLog;
my $elog =
 Parse::EventLog->new("c:\\winnt\\system32\\config\\SysEvent.Evt");

my %c = $elog->getNewestEvent();
# Do something interesting here.

while (%c = $elog->getPreviousEvent()) {
 print localtime($c{TimeGenerated}) .
  ": $c{EventID} generated by $c{Source} on $c{Computer}.\n";
 # Do a lot of interesting somethings here.
}

DESCRIPTION

Parse::EventLog is a module designed to allow parsing of binary Windows 2000+ Event Logs on any platform. For better Event Log parsing on Windows platforms, see Win32::EventLog.

When instansiated with the location of an Event Log file, you will be able to walk through the existing events in chronological order from oldest to newest or vice versa, as well as being able to extract the whole log to a hash table and seek through however you wish.

METHODS

new

my $eventlog =
 Parse::EventLog->new("c:\\winnt\\system32\\config\\SysEvent.Evt");

Parse::EventLog constructor, called with the location of the event log file to open. Returns a Parse::EventLog object or dies on error. Stores the internal record pointer at the newest event, so the next call to getPreviousEvent will succeed but getNextEvent will fail (there are no newer events).

getOldestEvent

my %event = $eventlog->getOldestEvent();

Returns a hash table containing the oldest entry in the event logand moves the current event pointer to the oldest event.

getNewestEvent

my %event = $eventlog->getNewestEvent();

Returns a hash table containing the newest entry in the event log and moves the current event pointer to the newest event.

getNextEvent

my %event = $eventlog->getNextEvent();

Moves us forward in time, returning a hash table containing the next event in the event log. Returns an empty array/hashtable if there are no more events to get.

getPreviousEvent

my %event = $eventlog->getPreviousEvent();

Moves us backward in time, returning a hash table containing the previous event in the event log. Returns an empty array/hashtable if there are no more events to get.

getAll

my %event = $eventlog->getAll();

Returns a copy of the internal Event Log hash table for your own nefarious pleasure. The main hash table is keyed by the internal RecordNumber (which is unique to each entry in the file). The value of each of those keys is another hash table containing the actual event (in the same format as is returned by the other get*Event functions).

Example

my %c = $eventlog->getAll();
foreach my $a (keys %c) {
 print 'Time: ' . localtime($c{$a}{'TimeGenerated'} . "\n";
 print "Computer: $c{$a}{'Computer'}\n";
 print "Source: $c{$a}{'Source'}\n";
 print 'Type: ' . GetEventType($c{$a}{'EventType'}) . "\n";
 print '-' x 10;
}

count

my $count = $eventlog->count();

Returns the number of entries loaded from the event log.

FUNCTIONS

GetEventType

print 'Event type:' . GetEventType($c{'EventType'}) . "\n";

Returns a string containing the type of event (Error, Warning, Information, Audit Success, Audit Failure, or Unknown).

GetEventType is exported by default.

CONSTANTS

Several constants are exported by default. These constants are Event Type definitions. They are as follows:

  • EVENT_ERROR (1)

  • EVENT_WARNING (2)

  • EVENT_INFORMATION (4)

  • EVENT_AUDIT_SUCCESS (8)

  • EVENT_AUDIT_FAILURE (16)

RETURN VALUES

On success, all of the get*Event functions return a hash of the current Event. The hash itself has several keys made up of each of the values in the Event itself. The following keys are defined (note the capitals):

TimeGenerated

The epoch time the event was generated, suitable for feeding to gmtime and localtime.

TimeWritten

The epoch time the event was written to the event log, usually the same as TimeGenerated (give or take a second). Suitable for feeding to gmtime and localtime.

RecordNumber

The record number of the event. This is assigned and due to the binary nature of the file, and can not be expected to be consistant or unique on subsequent parsings of the same file.

EventID

The event identification number, vendor and application specific. Details can often be found in the Microsoft Knowledge Base.

EventType

The event type, vendor and application specific.

Source

Source of the event, usually the application or service name.

Computer

The name of the computer that generated the event.

SID

The SID associated with the entry. It is unknown whether this is the SID of the source PC, the PC the log was stored on, the user, or something else.

NumStrings

Number of strings in the event.

Strings

An array reference to all (if any) of the strings included with the event. Events work a lot like printf format strings, that is, there is a fixed message with a variable part, such as:

The %s service failed to start due to the following error:
The system cannot find the file specified.

In this case, the Strings parameter would contain the name of the service that would be placed in %s above to complete the event message.

TO DO

  • Support for random access reads.

  • Parsing without loading the whole file into memory. By default, the files are only 64k, but it's possible to specify a much larger size.

  • Descriptions for general Microsoft Windows events.

  • Rename/alias getNextEvent and getPreviousEvent to getNewerEvent and getOlderEvent?

KNOWN BUGS

  • Occasional spurious Strings are read from the Event Log. It seems the log itself specifies they should be there, but there is only garbage data to be read.

  • Incomplete parsing. Due to the mysterious nature of the Event Logs and the lack of documentation on their format, there are several unknown fields in the log. These fields are currently ignored. If anyone knows what these fields are for, please let me know.

CAVEATS

While this module can extract general information on the events, most of the error description is stored in system libraries specific to the Windows version and patch level that created the log. At this time, Parse::EventLog does not have a facility to extract that data.

Assume the Event Viewer shows the following event description:

The Print Spooler service was successfully sent a stop control.

The data to build this description is stored in two locations. The first, a DLL file associated with the Service Control Manager, contains the string:

The %s service was successfully sent a %s control.

The Event Log itself contains the strings:

Print Spooler

and

stop

Unfortunately, at this time Parse::EventLog is not able to extract the string data from files outside of the Event Log itself, only the strings contained within it. At this time, I recommend either parsing the events on the Windows server itself (via Win32::EventLog or a syslog plugin) or manually looking up the data elsewhere.

SEE ALSO

Win32::EventLog

THANKS

Thanks to Malik of www.whitehats.ca for the initial data structure format that this module was based on. See: http://www.whitehats.ca/main/members/Malik/malik_eventlogs/malik_eventlogs.html for more details and his origional work.

COPYRIGHT

Copyright 2005-2006, John Eaglesham

This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.