Parse::EventLog - Parse information from Windows Event Logs
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. }
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.
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).
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.
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.
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.
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.
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).
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; }
my $count = $eventlog->count();
Returns the number of entries loaded from the event log.
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.
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)
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):
The epoch time the event was generated, suitable for feeding to gmtime and localtime.
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.
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.
The event identification number, vendor and application specific. Details can often be found in the Microsoft Knowledge Base.
The event type, vendor and application specific.
Source of the event, usually the application or service name.
The name of the computer that generated the event.
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.
Number of strings in the event.
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.
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?
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.
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.
Win32::EventLog
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 2005-2006, John Eaglesham
This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.
To install Parse::EventLog, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Parse::EventLog
CPAN shell
perl -MCPAN -e shell install Parse::EventLog
For more information on module installation, please visit the detailed CPAN module installation guide.