John Eaglesham > Parse-EventLog > Parse::EventLog

Download:
Parse-EventLog-0.7.zip

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.7   Source  

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:

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 ^

KNOWN BUGS ^

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.

syntax highlighting: