Home » System » System_ProcWatch » Manual

Introduction and Features

Intro

Intro – Introduction to System::ProcWatch

What is System::ProcWatch?

System::ProcWatch is a small collection of classes to ease monitoring of system processes based on the Unix program procps (ps).

To use System::ProcWatch you simply have to define a ruleset on which based System::ProcWatch operates. A rule (or job, watch) defines what actions should happen if a condition evaluates to true.

To be continued...

Shell Scripts

You can use System::ProcWatch out of the box, by utilizing the shipped shell scripts procwatch and procwatch-lint.

procwatch

The procwatch command is meant to be used for system diagnosis - run as daemon or by cron.

The usage is best described by the output of procwatch -h:

procwatch-lint

The procwatch-lint is meant to validate procwatchs configurtation files written in XML by utilizing XML::DTD::XmlValidator.

Once again synopsis is best described by the output of procwatch-lint -h:

Configuration

There are three methods to configure your System::ProcWatch application:

• XML string/file
• INI file
• PHP array

Xml string/file

Configuring System::ProcWatch by XML is the preferred way. It is as simple as powerful.

Ruleset: The Root Element

The root element of an XML configuration file/string is the procwatch element. It has one implicit attribute, the version attribute, set to "1.0".

The procwatch element symbolizes our ruleset, and the childs of the root are our rules.

Rules: The Childs of the Root

The direct descendants of the root element procwatch, are the watch elements, which can occur 1 time or more often.

The watch element has one required attribute, the name attribute, which gives the watch (or job, rule) a descriptive name like "httpd-count".

Each watch element symbolizes a single rule, containing a regular expression to search for, one or more conditions to evaluate and one or more actions to be taken.

A Rule

A rule consists of three child elements:

• pattern
• condition
• execute

Rule Element: pattern

The pattern element describes the perl compatible regular expression which should be evaluated against a column of the output of ps.

There is one required attribute, the match attribute, defining the column name of the output of ps in lowercase like "command" or "vsz".

This makes System::ProcWatch highliy versatile and should make it usable with any platforms procps program.

The pattern elements content solely consists of the perl compatible regular expression to match against the column defined in the match attribute. The PCRE MUST contain the start and end delimiter and MAY contain any PCRE modifiers.

Example: <pattern match="command">/sbin\/httpd/</pattern>

Rule Element: condition

The condition element defines conditions that MUST evaluate to TRUE at all so that later defined actions will be executed.

The condition element has one required and one optional attribute, the required one being type, which MUST be one of "presence" or "attr", and the optional one being attr. However, if the type attribute equals to "attr" the attr attribute MUST be present.

The attr attribute represents a column of procps' output like "user" or "%mem".

Conditions

Dependent on the content of the type attribute, syntax and behavior of the condition element differ.

A condition with type "presence" MAY be empty, thus always evaluating to true.

Child Elements of condition may be:

• min Found value MUST exceed defined value.
• max Found value MUST NOT exceed defined value.
• is Found value MUST be equal to defined value.
• isnot Found value MUST NOT be equal to defined value.
• sum The sum of found values MUST NOT exceed defined sum.

You may combine them to define for instance a range from min to max.

Rule Element: execute

The execute element defines actions that should be taken if the condition applies.

It has one required attribute, the type attribute, which MUST equal to one of "shell" or "php".

Obviously the content of the execute element is executed either on the shell through shell_exec() or directly in PHP through eval().

The execute element MAY occur any times.

There are some special variables that will automagically be available in execute statements:

• $msg This contains a general message, what has happened. It is quoted in single quotes for save usage and is available in shell and php executes.
• $pids This contains all PIDs of the processes that have been found. They are enclosed by single quotes and parenthesis. Example: '(433, 444, 455, 466)'
• $procs This is a serialized php array in string format containing all information gained from ps and looks like: array(array('pid' => 344, 'command' => '/usr/sbin/httpd' ...)) It is only available in php executes and can easily be used in function callbacks: <execute type="php">get_procs($procs);</execute>

Example XML configuration file

XML configuration file

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE procwatch SYSTEM "/usr/share/pear/data/System_ProcWatch/procwatch-1_0.dtd">
<procwatch>
<!--

    SOME EXAMPLE CONFIGURATIONS
    ===========================

    This job looks for the count of running httpd processes by
    matching the PCRE "/httpd/" against the COMMAND column of ps.

    If there are less than 10 or more than 30 httpd processes found
    the speicified string is executed on the shell.
-->
  <watch name="httpd-count">
    <pattern match="command">/httpd/</pattern>
    <condition type="presence">
      <min>10</min>
      <max>30</max>
    </condition>
    <execute type="shell">echo $msg $pids &gt;&gt; /var/log/procwatch</execute>
  </watch>

<!--
  This job looks for the amount of physical memory all httpd processes use
  together by matching the PCRE "/httpd/" against the COMMAND column of ps.

  It adds all %MEM columns of ps that match the pattern together and compares
  the reslut to the specified sum. If the result exceeds the sum the specified
  string is executet on the shell.
-->
  <watch name="httpd-usage">
    <pattern match="command">/httpd/</pattern>
    <condition type="attr" attr="%mem">
      <sum>5</sum>
    </condition>
    <execute type="shell">echo $msg $pids &gt;&gt; /var/log/procwatch</execute>
  </watch>

<!--
  This job looks for zombie processes.

  It matches the PCRE "/Z/" against the STAT column of ps and executes the
  specified string on the shell if more than 0 zombies have been found.
-->
  <watch name="ZOMBIES">
    <pattern match="stat">/Z/</pattern>
    <condition type="presence">
      <max>0</max>
    </condition>
    <execute type="shell">echo $msg $pids &gt;&gt; /var/log/procwatch</execute>
  </watch>

<!--
  This job looks for running processes.

  It matches the PCRE pattern "/R/" against the STAT column of ps and executes
  the specified string on the shell if any running processes have been found.
-->
  <watch name="running">
    <pattern match="stat">/R/</pattern>
    <condition type="presence" />
    <execute type="shell">echo $msg $pids &gt;&gt; /var/log/procwatch</execute>
  </watch>

</procwatch>

INI file

Configuring by INI file is effectively the same except that only executes of type "shell" can be defined.

Example INI configuration file

INI configuration file

PHP array

A valid array to configure System::ProcWatch may look similar to the following example.

Example PHP configuration array

PHP configuration array

<?php
$watches = array();

$watches['job1'] = array();
$watches['job1']['pattern'] = array();
$watches['job1']['condition'] = array();
$watches['job1']['execute'] = array();

$watches['job1']['pattern']['command'] = '/httpd/';
$watches['job1']['condition']['presence'] = array('min' => 10, 'max' => 100);
$watches['job1']['execute']['shell'] = array('/usr/bin/mail2admin $msg');

$watches['job2'] = array();
// ...
?>

Constants

Constants – Constants defined in and used by System_ProcWatch

All Constants

Constants defined in ProcWatch.php

This constants are mostly used internally by System_ProcWatch

System_ProcWatch

System_ProcWatch – System_ProcWatch

System_ProcWatch

Monitor processes

Usage:

<?php
1  require_once 'System/ProcWatch.php';
2  require_once 'System/ProcWatch/Config.php';
3
4  $cf =
?>

System_ProcWatch_Config
<?php
::
?>

fromXmlFile
<?php
('/etc/procwatch.xml');
5  $pw = &new
?>

System_ProcWatch
<?php
($cf);
6  $pw->
?>

run
<?php
();
?>

System_ProcWatch::System_ProcWatch

System_ProcWatch::System_ProcWatch() – Constructor

Synopsis

object &new System_ProcWatch ( array $config )

Description

Instantiate a new System_ProcWatch object configured by the supplied configuration array.

Parameter

array $config

config array from System_ProcWatch_Config

System_ProcWatch::run

System_ProcWatch::run() – Run once

Synopsis

void System_ProcWatch::run ( string $ps_args = 'aux' )

Description

Run once.

Parameter

string $ps_args

arguments that should be passed to ps

Throws

Throws no exception.

Note

This function can not be called statically.

System_ProcWatch::daemon

System_ProcWatch::daemon() – Run in daemon mode

Synopsis

void System_ProcWatch::daemon ( int $interval , string $ps_args = 'aux' )

Description

Runs System_ProcWatch in daemon mode with the defined interval of seconds to sleep.

Parameter

integer $interval

seconds to sleep

string $ps_args

ps' arguments

Throws

Throws no exception.

Note

This function can not be called statically.

System_ProcWatch::setConfig

System_ProcWatch::setConfig() – Set configuration

Synopsis

void System_ProcWatch::setConfig ( array $config )

Description

Configure System_ProcWatch with an config array from System_ProcWatch_Config.

Parameter

array $config

config array from System_ProcWatch_Config

Throws

Throws no exception.

Note

This function can not be called statically.

Configuration

System_ProcWatch_Config

System_ProcWatch_Config – System_ProcWatch_Config

System_ProcWatch_Config

Build a configuration array for System_ProcWatch

Usage:

1  $cf =

::

('/etc/procwatch.xml');
2  $pw = &new

($cf);

System_ProcWatch_Config::fromXml

System_ProcWatch_Config::fromXml() – Get config array from XML string

Synopsis

mixed System_ProcWatch_Config::fromXml ( string $xml )

Description

Parses an XML string into an config array to configure System_ProcWatch with.

Parameter

string $xml

XML string

Return value

Returns config array on success or PEAR_Error on failure.

Throws

Throws PEAR_Error if XML file does not exist or problems parsing the XML string have occured.

See

Configuration by XML file

Note

This function should be called statically.

System_ProcWatch_Config::fromXmlFile

System_ProcWatch_Config::fromXmlFile() – Get config array from XML file

Synopsis

mixed System_ProcWatch_Config::fromXmlFile ( string $file )

Description

Parses an XML file into an config array to configure System_ProcWatch with.

Parameter

string $file

path to XML file

Return value

Returns config array on success or PEAR_Error on failure.

Throws

Throws PEAR_Error if XML file does not exist, or problems parsing the XML file have occured.

See

Configuration by XML file

Note

This function should be called statically.

System_ProcWatch_Config::fromIniFile

System_ProcWatch_Config::fromIniFile() – Get config array from INI file

Synopsis

mixed System_ProcWatch_Config::fromIniFile ( string $file )

Description

Parses an INI file into an array to configure System_ProcWatch with.

INI configuration file

Parameter

string $file

path to INI file

Return value

Returns config array on success or PEAR_Error on failure.

Throws

Throws PEAR_Error if INI file doesn't exist.

See

Configuration by INI file

Note

This function should be called statically.

System_ProcWatch_Config::fromArray

System_ProcWatch_Config::fromArray() – Get config array from an array

Synopsis

mixed System_ProcWatch_Config::fromArray ( mixed $array )

Description

This method in fact does a sanity check on the supplied config array and should only be used for testing purposes.

Parameter

array $array

config array to check

Return value

Returns the same array on success or PEAR_Error on failure.

Throws

Throws PEAR_Error if an invalid configuration array was supplied.

Note

This function should be called statically.

Parser Information

System_ProcWatch_Parser

System_ProcWatch_Parser – System_ProcWatch_Parser

System_ProcWatch_Parser

Fetches output from `ps` and parses it into an associative array

Usage:

1   $ps = &new

();
2   $pd = &$ps->

();

System_ProcWatch_Parser::System_ProcWatch_Parser

System_ProcWatch_Parser::System_ProcWatch_Parser() – Constructor

Synopsis

object &new System_ProcWatch_Parser ( string $ps_args = 'aux' )

Description

Instantiates a new System_ProcWatch parser object with the supplied arguments to pass to ps.

Parameter

string $ps_args

ps' arguments

Throws

Throws no exception.

System_ProcWatch_Parser::getParsedData

System_ProcWatch_Parser::getParsedData() – Get parsed data

Synopsis

array &System_ProcWatch_Parser::getParsedData ( string $ps_args = 'aux' , bool $refresh = false )

Description

This is the main method of this class. It fetches to output of ps, executed on the shell, and returns the parsed data as an 2 dimensional indexed and associatve array.

Parameter

string $ps_args

ps' arguments

boolean $refresh

whether to refresh our data

Return value

Returns array of processes parsed from ps' output.

Throws

Throws no exception.

Note

This function can not be called statically.

System_ProcWatch_Parser::fetch

System_ProcWatch_Parser::fetch() – Fetch ps' data

Synopsis

string System_ProcWatch_Parser::fetch ( string $ps_args = '' )

Description

Fetches the output of ps, executed on the shell.

Parameter

string $ps_args

ps' arguments

Return value

Returns string ps' output.

Throws

Throws no exception.

Note

This function can not be called statically.

System_ProcWatch_Parser::parse

System_ProcWatch_Parser::parse() – Parse

Synopsis

array System_ProcWatch_Parser::parse ( string $data )

Description

Parses the output of ps.

Parameter

string $data

output of ps

Return value

Returns array of processes.

Throws

Throws no exception.

Note

This function can not be called statically.

System_ProcWatch_Parser::getProcByPid

System_ProcWatch_Parser::getProcByPid() – Get info about a process by its PID

Synopsis

array System_ProcWatch_Parser::getProcByPid ( int $pid )

Description

Get information about a process by its PID.

Parameter

integer $pid

the PID of the process

Return value

Returns array with information about the process with the supplied PID.

Throws

Throws no exception.

Note

This function can not be called statically.

System_ProcWatch_Parser::getProcInfo

System_ProcWatch_Parser::getProcInfo() – Get information about processes

Synopsis

array System_ProcWatch_Parser::getProcInfo ( string $pattern , string $search )

Description

Get information about processes matching the defined search.

Parameter

string $pattern

PCRE to match for process

string $search

the ps field/column to search in

Return value

Returns array of processes matching the search.

Throws

Throws no exception.

Note

This function can not be called statically.