C++ SLAC Filter Throttle

The following functions set up specific throttles within the SLAC filter. Throttles take effect as soon as they are set up, and may be temporarily disabled as a group with the cmlogFilterSLAC::throttleOff() function, or individually permanently removed by calling throttleRemove with an appropriate index obtained via throttleShow().

They take the form:

  int cmlogFilterSLAC::setThrottle(char     *ctag,
				   int       limit,
				   double    deltaTime,
				   <CTYPE>   val)

where supported <CTYPE> values are:

     BYTE		-- unsigned 8-bit ints/chars
     short		-- signed 16-bit ints
     unsigned short	-- unsigned 16-bit ints
     long		-- signed 32-bit ints
     unsigned long	-- unsigned 32-bit ints
     float		-- 32-bit floats
     double		-- 64-bit floats
     char *		-- char array (ie. string)

Arguments are:

char* ctag

A string containing a tag name. In the SLAC CMLOG environment, message fields have tags such as "facility", "verbosity", "severity", etc (see Common/cmlogUtil.h). Message strings that are passed to functions like logMsg() etc. all end up in the field labeled "text", so if you want to throttle something in that field, specify tag "text". See the sample code below.

int limit
double deltaTime
	

These parameters specify how many messages (limit) we want to allow through in a specified time period (deltaTime seconds). Only "limit" number of messages with matching "tag" and "val" fields will be logged during a given deltaTime period, and a count is maintained of how many messages were dropped. After the period is up, a summary message is output to the log and another "limit" messages are allowed through. "Limit" may equal zero, in which case only summary messages are output. An alternative is to call throttleOn() or throttleOff() to temporarily suspend *all* throttling. An alternative is to use throttleShow() to obtain a numbered list of current throttles, and then calling throttleRemove() with the appropriate index.

<CTYPE> val
	

This is the actual value to throttle on. must match the type of data in the field; a string "5" won't match an integer 5, for instance. For this reason, for example, field "text" can only be throttled with a "char* val"; the SLAC filter will treat this "val" as a substring, and any message that contains "val" as a part will be subject to throttling. For instance, the call:

	      filter -> setThrottle ("text", 1, 10.0, "abc");

will subject all of the following messages to potential throttling:

	      "abc"
	      "myApp: flabcounter overflow (399)"
	      "Danger, Will Robinson!  Frabcous snark!"

While int- and string-valued throttles use exact matches to determine if specific messages are to be filtered out, float and double include a fudge factor in their comparisons. This "epsilon" is currently computed to be 10^(-5) of the specified throttle value... for instance, for a float or double "val" of 100.0, a message will need to match within +/- 0.001 to be considered for filtering, while for 1.e+8 an absolute difference less than 1000.0 will do.

The following format will set a throttle to be a "wildcard" throttle on the "text" tag:

	      filter -> setThrottle ("text", 1, 10.0, "");

This throttle will only allow 1 message per 10.0 seconds for all messages with a valid "text" tag. The "wildcard" will match for any defined data for that tag of any data type.

Return values:

	CMLOG_SUCCESS
	CMLOG_ERROR