pshandler.h File Reference

Detailed Description

The pshandler will "watch" the system's processes. You can watch for processes creation/destruction, specifying which processes to watch with a regex. You many generate events when processes fall within a specified range of percent memory or percent cpu used. NOTE: a process' percent memory used is calculated by taking the the RSS size and dividing it by the main memory size, so this is a measure of percent RAM used. The 'up' and 'down' events are useful to monitor running programs to generate notification and/or other response to processes stopping (and starting, but that is less common). The 'count' events are useful if you are interested in alerts when the number of a specific processes gets too high or low and when you are keep stats on activity. You may have multiple regex's, each generating its own events. This avoids reading the process table for each regex, rather it is is read one time for all. You may optionally specify a subsitution string that behaves similar to 'sed' to customize the generated events. If you supply a substitution string, rather than copying the original complete matching string, the substitution string is used, replacing all occurances of the special charcters \[0-9] with the associated substring matches. Note: \0 matches the whole expression, while \1,\2 through \9 are substring matches 1, 2 through 9. For example, say you are watching a process with an ugly or uninformatative name, you can change the name reported in the event by supplying a subsitution string and specifying substrings in the regex (i.e., regex is "/usr/local/bin/httpd" and substitution is "Web server is down! (\0)"). Regex's are POSIX 1003.2 "extended" form.

Wire keywords (standard handler keywords documented in Wire )

match: up-event down-event count-event regexp subst if either up-event, down-event or count-event are empty strings they are ignored (optional)
mem: mem-event min-percent max-percent if a process is using between [min,max] percent of system memory then generate mem-event (optional)
cpu: cpu-event min-percent max-percent if a process is using between [min,max] percent of system cpu then generate cpu-event (optional)

You my have multiple match: lines. Matches are applied in the order they are declared. You may only have 1 mem: line and 1 cpu: line. Up/down/count example:


// generate events for httpd coming up/down and report total count
set up create event { name: "up"  priority: 1 }
set down create event { name: "down"  priority: 1 }
set count create event { name: "count"  priority: 1 }

create handler ps { 
	match: $up $down $count "httpd" ""
	cycletime: 5 
}

Memory example:


// generate events if for processes using too much memory 
set fatpig create event { name: 'Over 90% mem'  priority: 1 }

create handler ps { 
	mem: $fatpig 90 100
	cycletime: 5 
}

Cpu example:


// generate events if for processes using too much cpu
set cpuhog create event { name: 'Over 90% cpu'  priority: 1 }

create handler ps { 
	mem: $cpuhog 90 100
	cycletime: 5 
}

Match events generated:

Event Name	Type	Description
up	AW_EVENT_TYPE_STRING	Process with matching name is up, send process name
down	AW_EVENT_TYPE_STRING	Process with matching name is that was up is now down, send pid:cmdline
count	AW_EVENT_TYPE_INT32	The number of processes matching the regex

Mem events generated:

Event Name	Type	Description
mem	AW_EVENT_TYPE_STRING	If process' memory usage is in range, send pid:cmdline

Cpu events generated:

Event Name	Type	Description
cpu	AW_EVENT_TYPE_STRING	If process' cpu usage is in range, send pid:cmdline

Events accepted:

Type	Description
Any	Generate an event of type requested

*/ /**** moved below comment out of above because the "wire" interface does not allow you to set these currently ****/ /* Options:

AW_PSHANDLER_GROUP : Watch a group of processes defined by matching the regex. Only send 'up' events when the first match appears and only send 'down' events when the last match disappears. This is useful for applications like Apache which fork/kill child processes regularly.
AW_PSHANDLER_COUNTONCHANGE : Only send 'count' events when the count of the processes matching the regex changes. By default, the 'count' events are generated every cycle. This option is useful is you are interested in notification if the number of processes gets below or above a certain number (used with the rfilterhandler).

#include <dirent.h>
#include "monitor.h"
#include "wire.h"
#include "regexmatch.h"

Go to the source code of this file.

Data Structures

struct aw_pshandler_cpufilter_t

Filters processes for those with cpu (as decimal) in range and generates event. More...

struct aw_pshandler_events_t

Events generated. More...

struct aw_pshandler_memfilter_t

Filters processes for those with mem (as decimal) in range and generates event. More...

struct aw_pshandler_pidlist_s

struct aw_pshandler_regex_t

Specifies a regex and associated events. More...

struct aw_pshandler_state_t

State of handler during probing. More...

struct aw_pshandler_t

Handler object. More...

struct aw_pshandler_watcher_t

Compiled regex, associated events and state. More...

struct aw_pshandler_watchlist_s

Defines

#define AW_PSHANDLER_DEFAULT_FLAGS ( AW_PSHANDLER_GROUP | AW_PSHANDLER_COUNTONCHANGE)

Typedefs

typedef aw_pshandler_pidlist_s aw_pshandler_pidlist_t

typedef aw_pshandler_watchlist_s aw_pshandler_watchlist_t

Enumerations

enum aw_pshandler_flag_t { AW_PSHANDLER_GROUP = 0x1, AW_PSHANDLER_COUNTONCHANGE = 0x2 }

Functions

aw_pshandler_t * aw_create_pshandler (u_int32_t nregexs, aw_pshandler_regex_t *regexs, aw_pshandler_memfilter_t *memfilter, aw_pshandler_cpufilter_t *cpufilter, int32_t(*regevent)(aw_handler_t *h, aw_address_t *eventid, u_int32_t index), int32_t(*regmaskevent)(aw_handler_t *h, aw_address_t *eventid, u_int32_t index), const aw_alarm_sched_t *sched, aw_logger_t *logger)

Create a ps handler.

void aw_free_pshandler (aw_pshandler_t *p)

Free handler and all associated resources.

aw_handler_t * aw_wire_pshandler (aw_wire_mkhandler_args_t *args)

Create a ps handler using "wire". See header doc for keyword documentation.

Define Documentation

#define AW_PSHANDLER_DEFAULT_FLAGS ( AW_PSHANDLER_GROUP | AW_PSHANDLER_COUNTONCHANGE)

Default settings

Typedef Documentation

typedef struct aw_pshandler_pidlist_s aw_pshandler_pidlist_t

typedef struct aw_pshandler_watchlist_s aw_pshandler_watchlist_t

Enumeration Type Documentation

enum aw_pshandler_flag_t

Flag values.
Enumeration values:

AW_PSHANDLER_GROUP

AW_PSHANDLER_COUNTONCHANGE

Function Documentation

aw_pshandler_t* aw_create_pshandler ( u_int32_t nregexs,

aw_pshandler_regex_t * regexs,

aw_pshandler_memfilter_t * memfilter,

aw_pshandler_cpufilter_t * cpufilter,

int32_t(* regevent)(aw_handler_t *h, aw_address_t *eventid, u_int32_t index),

int32_t(* regmaskevent)(aw_handler_t *h, aw_address_t *eventid, u_int32_t index),

const aw_alarm_sched_t * sched,

aw_logger_t * logger

)

Create a ps handler.
aw_create_pshandler

Parameters:

nregexs How many regex strings

regexs Array of regex strings

memfilter Filter for those processes with mem in range

cpufilter Filter for those processes with cpu in range

regevent Function pointer for event registration

regmaskevent Function pointer for event mask registration

sched Run schedule

logger Logger object

Returns:
Handler object

void aw_free_pshandler ( aw_pshandler_t * p )

Free handler and all associated resources.
aw_free_pshandler

Parameters:

p The handler

aw_handler_t* aw_wire_pshandler ( aw_wire_mkhandler_args_t * args )

Create a ps handler using "wire". See header doc for keyword documentation.
aw_wire_pshandler


Data Structures
struct	aw_pshandler_cpufilter_t
	Filters processes for those with cpu (as decimal) in range and generates event. More...
struct	aw_pshandler_events_t
	Events generated. More...
struct	aw_pshandler_memfilter_t
	Filters processes for those with mem (as decimal) in range and generates event. More...
struct	aw_pshandler_pidlist_s
struct	aw_pshandler_regex_t
	Specifies a regex and associated events. More...
struct	aw_pshandler_state_t
	State of handler during probing. More...
struct	aw_pshandler_t
	Handler object. More...
struct	aw_pshandler_watcher_t
	Compiled regex, associated events and state. More...
struct	aw_pshandler_watchlist_s
Defines
#define	AW_PSHANDLER_DEFAULT_FLAGS ( AW_PSHANDLER_GROUP \| AW_PSHANDLER_COUNTONCHANGE)
Typedefs
typedef aw_pshandler_pidlist_s	aw_pshandler_pidlist_t
typedef aw_pshandler_watchlist_s	aw_pshandler_watchlist_t
Enumerations
enum	aw_pshandler_flag_t { AW_PSHANDLER_GROUP = 0x1, AW_PSHANDLER_COUNTONCHANGE = 0x2 }
Functions
aw_pshandler_t *	aw_create_pshandler (u_int32_t nregexs, aw_pshandler_regex_t regexs, aw_pshandler_memfilter_t memfilter, aw_pshandler_cpufilter_t cpufilter, int32_t(regevent)(aw_handler_t h, aw_address_t eventid, u_int32_t index), int32_t(regmaskevent)(aw_handler_t h, aw_address_t eventid, u_int32_t index), const aw_alarm_sched_t sched, aw_logger_t *logger)
	Create a ps handler.
void	aw_free_pshandler (aw_pshandler_t *p)
	Free handler and all associated resources.
aw_handler_t *	aw_wire_pshandler (aw_wire_mkhandler_args_t *args)
	Create a ps handler using "wire". See header doc for keyword documentation.