Net::Peep - Perl extension for Peep: The Network Auralizer.
Peep is an open source free software network monitoring tool issued under the Gnu General Public License that presents information via audio output. Network diagnosis with Peep is made not only based on single network events, but the network as a whole "sounds normal."
Although Peep has found much use as a monitoring tool, the tool has been designed to allow customized clients to be created for virtually any purpose. It could be used, for example, to create a stock ticker or to parse input from a web cam with ImageMagick and create aural output based on the nature of the image.
Please refer to the section on creating a custom client below for more information.
This document serves as an introduction to the Peep clients and the Peep client architecture.
File::Tail Time::HiRes Net::Ping::External Filesys::DiskFree Proc::ProcessTable
Peep is built on a client-server model in which the clients generate "events" based on user-defined criteria (e.g., whether a packet denial has been logged or a broken link on a web site was found). One or several Peep servers are then notified of the events by clients, at which time an audio signal is generated.
The clients, which include such applications as logparser and sysmonitor and for which this document constitutes introductory documentation, are written in Perl, IMHO about the coolest language ever. The bulk of the client code is composed of a set of Perl modules comprising objects and base classes for use by Peep clients and their derivatives.
logparser
sysmonitor
The server, peepd, is written in C.
peepd
Both the client and server are available for download free of charge from the Peep homepage located at
http://peep.sourceforge.net
The Peep client modules and executables are also available on the CPAN (Comprehensive Perl Archive Network) for installation via the time-honored
perl -MCPAN -e "install Net::Peep"
In fact, this is the preferred method of installation of the Peep clients.
Consult the core Peep documentation for more information on installation and usage of Peep.
The Peep client library is composed of the following core modules:
Perl Modules ------------ Net::Peep A non-functional module. Simply holds POD documentation for Peep; in fact, it holds the documentation that you are reading right now! Net::Peep::Conf The Peep configuration object. An object representation of peep.conf. Net::Peep::Parser The Peep configuration file parser. Reads peep.conf and populates Peep::Conf appropriately. Net::Peep::BC The Peep broadcast module. Used to notify Peep servers that an event has been generated. Net::Peep::Log Provides utility methods for logging, debugging, and benchmarking. Net::Peep::Client Base and utility class for Peep clients and client modules. Net::Peep::Client::Logparser Utility class for the logparser client. Net::Peep::Client::Sysmonitor Utility class for the sysmonitor client. Net::Peep::Client::Pinger Utility class for the pinger client. Net::Peep::Peck Utility class for the peck client. Net::Peep::Notifier A class Peep uses to send out e-mail notifications.
There are a variety of helper classes other than those mentioned above that server a variety of useful functions. Consult the individual PODs for more information.
Clients ------- logparser Generates events based on matching regular expressions to tailed logs (e.g., /var/log/messages). sysmonitor Generates events based on system events (e.g., load average exceeding 2.0). pinger Generates events based on whether a host is responsive. peck Generates ad hoc Peep events. Primarily for testing purposes. keytest Generates ad hoc Peep events. Primarily for fun.
Please refer to the individual modules of the Peep distribution (e.g., Net::Peep::BC) or the Peep client executables (e.g., logparser) for further documentation.
One of the most powerful features of Peep is the ability to create customized clients to use Peep for whatever you like. Although Peep is used widely as a systems and network monitor because it is well suited to the task, you could do anything from creating a stock monitoring client to creating a client that will take output from a web cam, parse it with ImageMagick (see http://www.imagemagick.org and http://www.imagemagick.org/www/perl.html) and generate real-time sound effects based on what you see.
With the whole of the CPAN at your disposal, the sky is the limit.
The Net::Peep::Client module and other helper classes make constructing a custom Peep client a breeze.
It is quite formulaic, and once you have done it once, you will already feel like it is old hat. In describing the process, we will create the first example mentioned above: A client to monitor stock prices. All told, the code is only 50 lines (only 33 statements!) and took me about a half hour to write.
The client will wake up every 60 seconds, get some stock quotes over the web, and depending on whether the stock is above or below a certain price, will alert you with both a peep and an e-mail notification.
Bear in mind that you really do not need to know much Perl to create a client. If you are a newbie, just copy what is done here while using your favorite Perl book to figure out whatever you do not understand.
The full code listing is given at the end of this section for reference.
The ticker requires a Perl module by the name of Finance::Quote.
ticker
Finance::Quote
I will assume that the reader is familiar with how to install a Perl module. For those who are unfamiliar with the process of installing a Perl module from the CPAN, a hint:
sudo perl -MCPAN -e 'install Finance::Quote'
First, create a section in the Peep configuration file, peep.conf, for your client. (peep.conf would typically be put in your /usr/local/etc directory during install.) peep.conf is heavily commented, so you should use that as a reference as well as this document.
peep.conf
/usr/local/etc
The section begins with a client declaration and ends with an end client declaration.
client
end client
There is some window dressing you have to add, including a class and port declaration. You can just copy those from one of the other clients.
class
port
You can also put an optional default section, which specifies any defaults for command-line options. See the logparser section of peep.conf for an example.
default
Next (and this is where you are doing the real work), you create the config section.
config
Between the config and end config, you can put anything you want. You will see what this section is all about in a bit, but for now let us just create a section that lists some stock symbols and related information we will need for the client.
end config
If you want to receive e-mail notifications, you can include an optional notification section following the config section as well which will describe who is to be sent the e-mail and some other information.
notification
The whole thing looks like this:
client ticker class morgenstern port 1999 config # Stock symbol Stock exchange Event Max Min RHAT nasdaq red-hat 4.0 3.6 SUNW nasdaq sun-microsystems 9.0 8.0 end config notification notification-hosts morgenstern notification-recipients collin.starkweather@colorado.edu notification-level warn end notification end client ticker
Finally, you should define the events you just created. An event named red-hat is associated with the stock symbol for Red Hat (no endorsement implied) and one named sun-microsystems is associated with, you guessed it, Sun Microsystems (again, no endorsement implied).
red-hat
sun-microsystems
So let us tie these events into some sounds. Going down to the events block in the configuration file, put in the following:
events
events # Event Type | Path to Sound File | # of sounds to load ... red-hat /usr/local/share/peep/sounds/misc/events/rooster.* 1 sun-microsystems /usr/local/share/peep/sounds/misc/events/doorbell.* 1 end events
This will cause a rooster to crow when RHAT goes out of bounds and a doorbell to chime when the same happens with SUNW.
RHAT
SUNW
Creating the client itself is really quite easy. There is going to be alot of discussion in this section, and the code is quite liberally commented. However there are actually only 50 lines (and only 33 statements - some statements span lines for clarity) of code to create the entire client. So you should not feel intimidated. There is really not much to it.
I assume that the reader has some working knowledge of Perl. If you are just starting out, I would recommend that you look up
http://www.perlmonks.org
to supplement any other learning you are doing. It is a very helpful forum and a real boon to those just starting out.
Open a file called ticker in your text editor of choice.
The first thing we will create is the use section. This will read in all of the objects we need. I will also use the strict pragma. Using strict is a habit I highly recommend:
use
strict
#!/usr/bin/perl use strict; use Net::Peep::BC; use Net::Peep::Log; use Net::Peep::Client; use Net::Peep::Notifier; use Net::Peep::Notification; use Finance::Quote; use vars qw{ %config $logger $client $quoter $conf };
After using strict, several Peep modules are used. The Net::Peep::BC module is used to send a broadcast to the server to let it know it is supposed to play a sound. Net::Peep::Log is a helpful module if you need to create some well-formatted output. (We will use it in a couple of places to let ourselves know what we are doing.)
Net::Peep::BC
Net::Peep::Log
The Net::Peep::Client module is the real workhorse. That is what will enable us to write a client in 33 statements or less. The Net::Peep::Notifier and Net::Peep::Notification modules are used to send e-mail notifications. (I want to know it if my stocks take a nosedive and I am out of my office!)
Net::Peep::Client
Net::Peep::Notifier
Net::Peep::Notification
Next is the Finance::Quote module, which we will use to fetch the stock prices.
Finally we declare some global variables with the vars pragma. You will see what these are used for later.
vars
We will be using three objects in the main section of the script: A logging object, a Peep client object, and the object that gets our stock quotes for us.
$logger = new Net::Peep::Log; $client = new Net::Peep::Client; $quoter = new Finance::Quote;
Now we will work some magic with the client object.
The first thing we do is give the client a name. We will call our client 'ticker'.
$client->name('ticker');
Now we need to initialize the client.
$client->initialize();
There are a variety of command-line options that will be read and parsed during the initialization. If you would like to supply some of your own command-line options to the initialization, you can do so using the format of the Getopt::Long object with something like:
Getopt::Long
my $foo = ''; my %options = ( 'foo=s'=>\$foo, ... ); $client->initialize(%options);
Next we will tell the client what it will use to parse the config block we defined above. We will simply pass it a reference to a subroutine which we will define later. How about we call the subroutine parse?
parse
$client->parser( \&parse );
Now that we have told the client what to use to parse the config block, we can tell it to read in the configuration information from the Peep configuration file:
my $conf = $client->configure();
The return value of the configure method, $conf, is a Net::Peep::Conf object containing the information gleaned from the Peep configuration file and a variety of useful methods. See the Net::Peep::Conf PODs for more information.
$conf
Net::Peep::Conf
After the configuration information is read, we will start the client on its way. The first thing we do is tell the client what to do every time it wakes up. We will feed it a callback (another reference to a subroutine, this one called loop) which will be run every time the client wakes up. Then we will start the client up, telling it to wake up every 60 seconds and execute the callback.
loop
$client->callback( \&loop ); $client->MainLoop(60);
That is all there is to it! Well, almost. We mentioned two subroutines above which we have not yet defined. So the last thing we will do is write these subroutines.
The parser is given everything between the config and end config lines in the section of the configuration file we defined above.
Though you can parse it any way you like, I favor using a regular expression. They seem to intimidate people because they look so cryptic, but they were much easier for me to get the hang of than I expected.
# This subroutine will be used to parse the following 2 lines from # peep.conf (see above) and store the information in %config: # RHAT nasdaq red-hat 4.0 3.6 # SUNW nasdaq sun-microsystems 9.0 8.0 sub parse { for my $line (@_) { if ($line =~ /^\s*([A-Z]+)\s+(\w+)\s+([\w\-]+)\s+([\d\.]+)\s+([\d\.]+)/) { my ($symbol,$exchange,$event,$max,$min) = ($1,$2,$3,$4,$5,$6); $config{$symbol} = { event=>$event, exchange=>$exchange, max=>$max, min=>$min }; } } } # end sub parse
We basically create a data structure from the %config hash. The keys of the hash are the stock symbols and the values are hash references used to describe some information about the stock symbol such as what stock exchange to look at, what event (sound) to play, and what the maximum and minimum prices that will trigger the event are.
%config
The information that we get from the configuration file will be used in the next section to trigger the event and the e-mail notification.
Finally, the meat of the client: The callback. I will leave it as an exercise to the reader to browse the documentation for Finance::Quote.
First the code, then the explanation:
sub loop { for my $key (sort keys %config) { $logger->log("Checking the price of [$key] ..."); # Fetch some information about the stock including the price my %results = $quoter->fetch($config{$key}->{'exchange'},$key); my $price = $results{$key,'price'}; $logger->log("\tThe price of [$key] is [$price]."); if ($price > $config{$key}->{'max'} or $price < $config{$key}->{'min'}) { $logger->log("\tThe price is out of bounds! Sending notification ...."); # The price is out of bounds! We'll start peeping ... my $broadcast = Net::Peep::BC->new('ticker',$conf); $broadcast->send('ticker', type=>0, sound=>$config{$key}->{'event'}, location=>128, priority=>0, volume=>255); my $notifier = new Net::Peep::Notifier; my $notification = new Net::Peep::Notification; $notification->client('ticker'); $notification->status('crit'); $notification->datetime(time()); $notification->message("The price of $key is $price!"); $notifier->notify($notification); } } } # end sub loop
In the callback, we loop over the stock symbols we found in the parse subroutine described above with
for my $key (sort keys %config) { ... }
For each stock symbol, we fetch the price and other information using
my %results = $quoter->fetch($config{$key}->{'exchange'},$key);
Next, we check if the price is greater than the maximum or less than the minimum defined in the configuration file:
if ($price > $config{$key}->{'max'} or $price < $config{$key}->{'min'}) { ... }
If it is, we first send a message to the Peep server to play a sound. We do this by instantiating a Net::Peep::BC, the Peep broadcast object, and calling its send method.
send
my $broadcast = Net::Peep::BC->new('ticker',$conf); $broadcast->send('ticker', type=>0, sound=>$config{$key}->{'event'}, location=>128, priority=>0, volume=>255);
The type option indicates the type of sound (0 for an event, 1 for a state). The sound option tells it what type of sound it should play (in this case either red-hat or sun-microsystems). The remainder of the settings are described in the Net::Peep::BC documentation.
type
Second, we send out an e-mail notification. This is done by creating a Net::Peep::Notifier object, which will actually send the e-mail, and giving it a Net::Peep::Notification object properly populated with information that will be included in the e-mail:
my $notifier = new Net::Peep::Notifier; my $notification = new Net::Peep::Notification; $notification->client('ticker'); $notification->status('crit'); $notification->datetime(time()); $notification->message("The price of $key is $price!"); $notifier->notify($notification);
For more information, consult the documentation for these objects.
It is worth noting that this does not imply that we will receive an e-mail every 60 seconds. The notification system sends out a notification when it first receives one, then sends all subsequent notifications in a bundle at regular intervals (you can set the bundling interval in peep.conf) .
We have created a Peep client from scratch! Let us see how it works ....
Simply as an example, I would start the server with
./peepd -S /usr/local/etc/peep.conf --nodaemon
I use the --nodeamon flag so that I can watch the output.
--nodeamon
Then
./ticker --noautodiscovery --server=localhost --port=2001 \ --nodaemon --config=/usr/local/etc/peep.conf
We would be interested in any clients that are created, both out of curiosity and because the code may be useful to others. Our e-mail addresses are given below.
Michael Gilfix <mgilfix@eecs.tufts.edu> Copyright (C) 2001
Collin Starkweather <collin.starkweather@colorado.edu>
Many thanks to the folks at SourceForge for creating a robust development environment to support open source projects such as Peep.
If you are not familiar with SourceForge, please visit their site at
http://www.sourceforge.net
perl(1), peepd(1), logparser, sysmonitor, pinger, peck, keytest.
This software is issued under the Gnu General Public License.
For more information, write to Michael Gilfix (mgilfix@eecs.tufts.edu).
This version of Peep is open source; you can redistribute it and/or modify it under the terms listed in the file COPYING included with the full Peep distribution which can be found at
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
For those interested in a robust network and systems monitoring tools, your humble author has found Big Brother to be a valuable resource which is complementary to Peep. Big Brother is an open source product and there are a large number of user-contributed plug-ins which make it ideal for a variety of needs.
You can find more information on Big Brother at
http://www.bb4.com
Those who enjoy Peep may also enjoy checking out logplay, which is similar in concept but fills a different niche.
You can find more information on logplay at
http://projects.babblica.net/logplay
Logplay is not under active development at the time, though many ideas from the project are being incorporated into Peep with the assistance of the author, Rando Christensen, who has generously donated his time in many productive discussions.
Please contact me at
collin.starkweather@colorado.edu
if you have any questions.
client ticker class morgenstern port 1999 config # Stock symbol Stock exchange Event Max Min RHAT nasdaq red-hat 4.0 3.6 SUNW nasdaq sun-microsystems 9.0 8.0 end config notification notification-hosts morgenstern notification-recipients collin.starkweather@colorado.edu notification-level warn end notification end client ticker events # Event Type | Path to Sound File | # of sounds to load ... red-hat /usr/local/share/peep/sounds/misc/events/rooster.* 1 sun-microsystems /usr/local/share/peep/sounds/misc/events/doorbell.* 1 end events
Note the PODs at the beginning of the script. When the script is run with the help flag
./ticker --help
the client will display whatever PODs are included with the script.
#!/usr/bin/perl =head1 NAME ticker - A stock monitoring client written for Peep: The Network Auralizer. =head1 USAGE ./ticker --help ./ticker --noautodiscovery --server=localhost --port=2001 --nodaemon If you have any problems, try turning on debugging output with something like --debug=9. =head1 CONFIGURATION To use this client, include a section like the following in peep.conf: client ticker class home port 1999 config # Stock symbol Stock exchange Event Max Min RHAT nasdaq red-hat 4.0 3.6 SUNW nasdaq sun-microsystems 9.0 8.0 end config notification notification-hosts localhost notification-recipients bogus.user@bogusdomain.com notification-level warn end notification end client ticker and another section in the events block with something like events #Event Type | Path to Sound File | # of sounds to load ... red-hat /usr/local/share/peep/sounds/misc/events/rooster.* 1 sun-microsystems /usr/local/share/peep/sounds/misc/events/doorbell.* 1 end events =head1 AUTHOR Collin Starkweather <collin.starkweather@colorado.edu> Copyright (C) 2001 =head1 SEE ALSO perl(1), peepd(1), Net::Peep, Net::Peep::Client, Net::Peep::BC, Net::Peep::Notifier, Net::Peep::Notification, Finance::Quote http://www.sourceforge.net =cut # Always use strict :-) use strict; use Net::Peep::BC; use Net::Peep::Log; use Net::Peep::Client; use Net::Peep::Notifier; use Net::Peep::Notification; use Finance::Quote; use vars qw{ %config $logger $client $quoter $conf }; # The Net::Peep::Log object will allow us to print out some things in # a nicely formatted way so we can tell ourselves what we're doing ... $logger = new Net::Peep::Log; # Instantiate a Peep client object. The client object handles most of # the dirty work for us so we don't have to worry about things such as # forking in daemon mode or parsing the command-line options or the # Peep configuration file. Its a very sophisticated object with many # useful functions. For more information, type # # perldoc Net::Peep::Client $client = new Net::Peep::Client; $quoter = new Finance::Quote; # First we have to give the client a name $client->name('ticker'); # Now we initialize the client. If the initialization returns a false # value, we display documentation for the script. $client->initialize() || $client->pods(); # Now we assign a parser that will parse the 'ticker' section of the # Peep configuration file $client->parser( \&parse ); # Now we tell the client to get the information from the configuration # file. It returns a Net::Peep::Conf, the Peep configuration object, # which contains information from the configuration file. $conf = $client->configure(); # Register a callback which will be executed every 60 seconds. The # callback is simply a function which checks the price of the stock # and peeps every time it exceeds the maximum or minimum price that # has been set. $client->callback( \&loop ); # Start looping. The callback will be executed every 60 seconds ... $client->MainLoop(60); sub parse { # Parse the config section for the ticker client in the Peep # configuration file # We'll use a regular expression to extract the ticker information # and stuff it into a data structure (the global variable %config) # This subroutine will be used to parse lines from peep.conf such # as the following and store the information in %config: # RHAT nasdaq red-hat 4.0 3.6 # SUNW nasdaq sun-microsystems 9.0 8.0 for my $line (@_) { if ($line =~ /^\s*([A-Z]+)\s+(\w+)\s+([\w\-]+)\s+([\d\.]+)\s+([\d\.]+)/) { my ($symbol,$exchange,$event,$max,$min) = ($1,$2,$3,$4,$5,$6); $config{$symbol} = { event=>$event, exchange=>$exchange, max=>$max, min=>$min }; } } } # end sub parse sub loop { for my $key (sort keys %config) { $logger->log("Checking the price of [$key] ..."); # Fetch some information about the stock including the price my %results = $quoter->fetch($config{$key}->{'exchange'},$key); my $price = $results{$key,'price'}; $logger->log("\tThe price of [$key] is [$price]."); if ($price > $config{$key}->{'max'} or $price < $config{$key}->{'min'}) { $logger->log("\tThe price is out of bounds! Sending notification ...."); # The price is out of bounds! We'll start peeping ... my $broadcast = Net::Peep::BC->new('ticker',$conf); $broadcast->send('ticker', type=>0, sound=>$config{$key}->{'event'}, location=>128, priority=>0, volume=>255); # In case we're away from our desk, we'll also send out an # e-mail notification. Don't want to miss the action! my $notifier = new Net::Peep::Notifier; my $notification = new Net::Peep::Notification; $notification->client('ticker'); $notification->status('crit'); $notification->datetime(time()); $notification->message("The price of $key is $price!"); $notifier->notify($notification); } } } # end sub loop
To install Net::Peep, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Net::Peep
CPAN shell
perl -MCPAN -e shell install Net::Peep
For more information on module installation, please visit the detailed CPAN module installation guide.