NAME
Synapse::Monitor::Listener
About Synapse's Open Telephony Toolkit
Synapse::Monitor::Listener is a part of Synapse's Wholesale Open Telephony Toolkit.
As we are refactoring our codebase, we at Synapse have decided to release a substantial portion of our code under the GPL. We hope that as a developer, you will find it as useful as we have found open source and CPAN to be of use to us.
What is Synapse::Monitor::Listener all about
In the wholesale telecom business, you need to monitor a lot of stuff. For example, for each egress and ingress route (and there's hundreds of them and thousands of dialcodes), you need to permaently check answer seizure ration, average length of call, MOS, customer credit limit usage, make sure your systems are up and ping-eable, CPU load, etc. etc.
The idea is that you have a collection of scripts / daemons / cron jobs / etc which product Ip<event files>. Events have an associated type (e.g. 'ping'), status (e.g. UNKNOWN, OK, WARNING, DOWN), and indentifier (e.g. ping example-dot-com).
What Synapse::Monitor::Listener does is that it picks up newly created events and can be configured to perform a set of predefined actions when it detects an event change, such as firing an email, suspending a service, blocking an IP address, etc.
Synapse::Monitor::Listener overview and installation
The library is split as follows:
- script synapse-monitor-listener-cli, used to create and set configuration objects.
- script synapse-monitor-listener-service, which is a daemon desgined to be running in the background
- Synapse::Monitor::Listener, listener object, which is designed to choose what action(s) to do with .evt.yml objects / files.
- Synapse::Monitor::Listener::Action, listener action object, which is designed to define and execute arbitrary actions.
You install the package as follows:
perl Makefile.PL
make
make test
make install
synapse-monitor-listener-cli --create-configdir
synapse-monitor-listener-service install
synapse-monitor-listener-service startsynapse-monitor-listener-service should then start on each reboot, runlevels 3-5. You can check that this is the case and that the daemon has been correctly installed using the excellent chkconfig linux tool.
Synapse::Monitor::Listener configuration
Note: Synapse::Monitor::Listener does NOT need restarting once you have changed the configuration.
For the sake of the example - and because this package is designed to be a telephony package after all - let's say we have a bunch of call detail record (or "cdr") files on the filesystem. Each file contains a list of calls, wether they were answered or not, the call duration, etc.
Say we want to check and monitor ASR values, i.e. how many calls were answered on the last 100 calls. We have written a script, called asrcheck.pl, which runs in the background, and which produces notification files looking like this:
---
id: asr-myvoipsupplier-moroccomobilemeditel
state: OK
listener: asr
destination: Morocco-Mobile-Meditel
vendor: myvoipsupplier
notification-email: customer.service@example.com
head-wc: 100
asr: 62Notification files should be placed in /tmp/ and end with .evt.yml. synapse-monitor-listener-service will process these files as they appear and delete them after they have been processed.
The only required fields are "listener", "state", and "id". All the rest is optional but your underlying "action" scpripts could use the extra information. A copy of the file will be passed to them as $ENV{YAML_FILE}.
- id - should be unique across all listeners. i.e. there shouldn't be an "asr" listener called "foo" and an "acd" listener called "foo". Set up your scripts to call your checks "asr-foo" and "acd-foo" instead.
- state - can be any string without spaces. The number of states should be discrete and finite.
- listener - which listener configuration to use on this type of check.
For the sake of the example, say we have 3 possible states:
We need to let Synapse::Monitor::Listener know what to do when there is a state change on this type of notification.
First, let's configure an "asr" listener:
# first of all, create our "ASR listener" object
synapse-monitor-listener-cli type listener create asr "ASR listener"
# DOWN -> OK, or WARN -> OK : cool...
synapse-monitor-listener-cli listener asr action WARN.DOWN OK asr-email-goodjob
# OK -> WARN : send warning email
synapse-monitor-listener-cli listener asr action OK WARN asr-email-warning
# OK -> DOWN or WARN -> DOWN = send "down" email + suspend route
synapse-monitor-listener-cli listener asr action OK.WARN DOWN asr-email-down suspend-routeNow that's done, let's configure matching actions:
# a copy of the YAML notification file will be passed as $ENV{YAML_FILE}, set up your scripts accordingly...
# format is
# synapse-monitor-listener-cli type action create useless-action echo I_AM_USELESS >/dev/null
# to delete an action:
# synapse-monitor-listener-cli action useless-action remove
synapse-monitor-listener-cli type action create asr-email-goodjob synapse-email-notification /etc/synapse-monitor/emails/goodjob.xml
synapse-monitor-listener-cli type action create asr-email-warning synapse-email-notification /etc/synapse-monitor/emails/warning.xml
synapse-monitor-listener-cli type action create asr-email-down synapse-email-notification /etc/synapse-monitor/emails/down.xml
synapse-monitor-listener-cli type action create email-restored synapse-email-notification /etc/synapse-monitor/emails/restored.xml
synapse-monitor-listener-cli type action create suspend-route synapse-suspend-routeThat's it. You don't need to restart the daemon: the configuration changes are picked up immediately.
EXPORTS
none.
BUGS
Please report them to me. Patches always welcome...
AUTHOR
Jean-Michel Hiver, jhiver (at) synapse (dash) telecom (dot) com
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.