CGMonitor¶ ↑

A monitor for CommuiGate log files. Basically it tails the most recent CommuniGate or UNIX log files and allows plugins to take actions based on the log entry lines or at specific times.

Author¶ ↑

Payton Swick, 2006-2008

Notes on included code¶ ↑

Copied some code from ActiveSupport for time mathematics. There are also some other libs included which are needed but not necessarily installed on the systems on which this was installed, and Bundler did not exist at the time. This needs to use gems instead.

Plugins¶ ↑

Plugins are ruby files ending with “-plugin.rb” stored in the plugins/ directory. You may choose to activate all the available plugins at start (the default) or specific plugins that you choose. Run with –help for a list of options.

Plugin Action Methods¶ ↑

A Plugin file must define a class which subclasses CGMonitor::Plugin. The Plugin will be evaluated when the CGMonitor starts, and instantiated if the plugin was chosen to be activated. Just after being created, the Plugin#start_up method, if any, will be called. For example:

class Foo < CGMonitor::Plugin
  def start_up
    puts "Let's go!"
  end
end

A Plugin may then implement the method ‘every_line’ (Plugin#every_line) which will be called for each line that is read from the current log file, being passed the line as a String. It can then take any actions you like. For example:

class Foo < CGMonitor::Plugin
  def every_line(line)
    puts "This line is long" if line.size > 120
  end
end

Alternatively a plugin may perform an operation every second or every minute by implementing the methods ‘every_second’ or ‘every_minute’ (Plugin#every_second and Plugin#every_minute). For example:

class Foo < CGMonitor::Plugin
  def every_minute
    puts "Another minute has passed and I'm still waiting."
  end
end

A plugin may also implement the method ‘signal’ (Plugin#signal) which will be called when the cgmonitor process receives a SIGHUP (1) signal. For example:

class Foo < CGMonitor::Plugin
  def signal
    puts "Aah! A signal!"
  end
end

Finally, any clean-up can be performed by overriding the method ‘shut_down’ (Plugin#shut_down) which will be called when the plugin is stopped.

class Foo < CGMonitor::Plugin
  def shut_down 
    puts "We're done here."
  end
end

Plugin Output Methods¶ ↑

There are several helper methods that a Plugin may use including three logging/output methods (Plugin#info_message, Plugin#warning_message, Plugin#error_message) and a built-in emailer method (Plugin#send_email, which will only actually send an email if emailing is enabled when the Monitor was started; also see Plugin#send_email_buffered which will send emails on a schedule).

class Foo < CGMonitor::Plugin
  def every_line(line)
    if line =~ /something important/
      warning_message("Something important is going on.")
      send_email_buffered("Something important is going on.")
    else
      info_message("Just another boring line.")
    end
  end
end

Plugin Configuration¶ ↑

Plugins may also use configuration options specified in the cgmonitor YAML config file (this defaults to cgmonitor.cfg if you are using the init script). This configuration is read on startup and again every time cgmonitor receives an HUP signal (see the Plugin#signal method for more you can do with that).

Options for a plugin are specified under the plugin Class name and can be accessed using the Plugin#my_options accessor (you may also set options using Plugin#my_options=). For example, if the plugin was called TestPlugin, options for this plugin may be defined as:

:TestPlugin: 
  :search_phrase: "testing please"
  :max_count: 16

You could then access those variables as follows:

info_message("Searching for '#{my_options[:search_phrase]}'")

Plugin Example¶ ↑

Here’s an example plugin:

class TestPlugin < CGMonitor::Plugin
  def start_up 
    info_message('Starting the TestPlugin plugin.')
  end
  def every_line(line)
    return unless line =~ /test plugin/
    info_message "this line contains the phrase 'test plugin': #{line}" 
    send_email "this line contains the phrase 'test plugin': #{line}"
  end
end

Installation and Usage¶ ↑

You can use cgmonitor as a command-line program, or you can easily use it as a daemon by using the included init script in the program directory (init/cgmonitor). Here’s one way to install it (if you do not install in /opt/CGScripts/cgmonitor, you will need to edit the init script to change CGMONITOR_HOME).

CGMONITOR_HOME=/opt/CGScripts/cgmonitor
cd $CGMONITOR_HOME; 
sudo ln -s $CGMONITOR_HOME/init.d/cgmonitor /etc/init.d/;
sudo chkconfig --add cgmonitor; # For RedHat distros only.

Then you should probably create a config file, like this:

cat > $GMONITOR_HOME/cgmonitor.cfg
---
email_to: cgmonitor@domain.com
smtp_host: smtp.domain.com
requested_plugins:
  - CGPMcAfeeCounter
  - CGPClamAVCrash
  - CorruptedMailbox
log_paths:
  - /SystemLogs/
daemon: true

To check if cgmonitor is running:

/etc/init.d/cgmonitor status

To start it:

/etc/init.d/cgmonitor start

To stop it:

/etc/init.d/cgmonitor stop

To restart it:

/etc/init.d/cgmonitor restart

To reload the config file (note that this will override any command-line options with the config options):

/etc/init.d/cgmonitor reload

If you’re running as a daemon, all output will go to your computer’s Syslog, usually something like /var/log/messages.