Version: @(#) $Id: system_monitor.php,v 1.6 2010/10/25 06:15:27 mlemos Exp $
System Monitor
Manuel Lemos (mlemos-at-acm.org)
Copyright (C) Manuel Lemos 2005 - 2010
@(#) $Id: system_monitor.php,v 1.6 2010/10/25 06:15:27 mlemos Exp $
Monitor and control the usage of resources in the current machine.
Use the Throttle function to check whether the system resources usage is on a level considered excessive. It can check whether the available disk space on given partitions is too low. It can also check whether the average CPU load is too high.
Use the ThrottleExecute function to execute a given program and monitor the system resources while the program is executing. This function can suspend the execution of the program automatically if the system resources usage is too high. Then it can wait for a while and resume the execution of the program when the system resources usage lowers to acceptable levels again.
This is useful to prevent that a resource consuming program drags the system and slows down other programs that should be executing with greater priority.
string
''
Store the message that is returned when an error occurs.
Check this variable to understand what happened when a call to any of the class functions has failed.
Just set this variable to an empty string to clear the error condition.
int
0
Available disk space limit of the given disk partitions under which the system resources usage should be considered excessive.
Set this variable to 0 if you do not wish that the class checks the available disk space when evaluating if the system is under excessive resource usage.
array
array()
List of partitions to be checked for available disk space.
Set this to strings with the path of the disk partitions to be checked.
string
'the partition {PARTITION} has only {FREE} bytes of free space'
Define the format of a human readable message to store in the throttle_message variable when the disk space on a monitored partition is too low.
Change this variable only if the default message format is not convenient or you need it in a different idiom.
int
0
Limit of the system average CPU load below which the load is not considered excessive.
Set to a non-zero value if you want the class to monitor the system CPU load. The recommended value is twice as much the number of CPU cores available on the machine. For instance, if the machine has 2 cores, set this variable to 4.
int
60
Period in seconds over which the CPU load average will be measured.
Currently this class only supports Linux. Under Linux it is only available the CPU load average values during 1, 5 and 15 minutes. If you change the default value of this variable, the class will monitor the CPU load of the period above the value that you specify.
string
'the CPU load in the last {PERIOD} seconds was of {LOAD}'
Define the format of a human readable message to store in the throttle_message variable when the CPU load is to high.
Change this variable only if the default message format is not convenient or you need in in a different idiom.
string
''
Human readable message that describes the reason why the system resources were considered too high.
Check this variable to get a human readable message for presenting to users in order to explain why there is currently an excessive usage of system resources.
int
18
Number of the signal to send to a program to resume its execution after it has been suspend.
Change this value if it is not the correct value for the SIGCONT signal under your system.
int
19
Number of the signal to send to a program to suspend its execution.
Change this value if it is not the correct value for the SIGSTOP signal under your system.
string
'.'
Path of the directory to store temporary files.
When the class captures the output of a program, it creates temporary files in the specified directory. Change this variable if you want to create temporary files in a specific directory.
bool Throttle(
Check the system resources usage and tell when the CPU usage is too high or when the available disk space is too low.
Set the variable disk_free_space_limit to a non-zero value if you want to check the disk space usage. In that case, also set the variable disk_space_partitions with the path of the disk partitions to be checked.
Set the variable cpu_load_limit to a non-zero value if you want to check the usage of the machine CPUs.
The cause argument will return a number associated with the cause of excessive system resources use, if any.
cause - Return the cause of an eventual excessive use of system resources. Currently it may return 3 possible values:
THROTTLE_CAUSE_NONE
Currently there is no excessive use of system resources.
THROTTLE_CAUSE_DISK_SPACE
Currently the disk space of one of the partitions specified in the variable disk_space_partitions is under the limit defined by the variable disk_free_space_limit.
THROTTLE_CAUSE_CPU_LOAD
Currently the average CPU load is over the limit specified in the variable cpu_load_limit.
This function returns 1 if the system resources usage could be checked successfully. Otherwise, check the variable error to determine what error occurred.
bool ThrottleExecute(
Execute a given program command but pause its execution when the CPU usage is too high or when the available disk space is too low.
Pass the command to execute in the parameters argument associative array. Check that argument description to learn how to capture the command output.
parameters - Pass the command to be executed, execution options and return result values. Currently it supports the following options:
'Command'
Command line to be executed including any command parameters.
'CaptureOutput'
Specify that the program output should be captured and how. This parameter may have two values: 'string' to tell the function to return the command output as a single string, and 'array' to tell to return the command output as an array of strings with all the output lines. The command output is returned in the 'Output' parameter.
'PollInterval'
Period of time to wait between consecutive checks for the system resources usage. It defaults to the value of the cpu_load_period.
'OnStop'
Callback function to invoke when the command execution is suspended. That function is called passing as argument an associative array. It may have a single parameter named 'Cause' which identifies the reason why the program was stopped. The possible values of that parameter are the same defined for the cause argument of the Throttle. The callback function should return 0 in case there was an error, or 1 otherwise.
'OnContinue'
Callback function to invoke when the command execution is resumed. That function is called passing as argument an associative array which currently is always empty. The callback function should return 0 in case there was an error, or 1 otherwise.
'Status'
Return the status value returned from the execution of the command.
'Output'
Return the output of the command. It may be a string or an array depending on the value of the 'CaptureOutput' option.
This function returns 1 if the command was executed successfully.Otherwise, check the variable error to determine what error occurred.