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: 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.