ball_rule

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Usage

Purpose

Provide an object having a pattern, thresholds, and attributes.

Classes

• ball::Rule: a pattern, thresholds, and attribute sets

See also

ball_ruleset

Description

This component implements a type, ball::Rule, that consists of a pattern, four threshold levels, and a set of attributes. The pattern indicates the names of the categories for which the rule will become relevant. The four threshold levels determine what actions will be performed on log records when their severity level equals or exceeds any of these threshold levels. The attribute set is a collection of unique attribute name/value pairs.

Note that multiple attributes with the same name are permitted so long as they correspond to different values.

This component participates in the implementation of "Rule-Based Logging". For more information on how to use that feature, please see the package level documentation and usage examples for "Rule-Based Logging".

Usage

The following code fragments illustrate how to create a rule and add attributes.

We create a rule whose pattern is WEEKEND* and whose threshold levels are all ball::Severity::e_OFF except the pass-through level. A pass-through level of ball::Severity::e_INFO indicates that whenever the rule is active and the severity is equal to or exceeds ball::Severity::e_INFO, log records will be passed to the observer:

ball::Rule rule("WEEKEND*",              // pattern
                ball::Severity::e_OFF,   // record level
                ball::Severity::e_INFO,  // pass-through level
                ball::Severity::e_OFF,   // trigger level
                ball::Severity::e_OFF);  // triggerAll level

Create some attributes and then add one to the rule:

ball::ManagedAttribute p1("myLib.uuid", 4044457);
ball::ManagedAttribute p2("myLib.name", "John Smith");
rule.addAttribute(p1);

Attributes can be looked up by the hasAttribute method:

assert(true  == rule.hasAttribute(p1));
assert(false == rule.hasAttribute(p2));

We then add the other attribute:

rule.addAttribute(p2);
assert(true  == rule.hasAttribute(p2));

Attributes can also be removed from the rule by the removeAttribute method:

rule.removeAttribute(p1);
assert(false == rule.hasAttribute(p1));
assert(true  == rule.hasAttribute(p2));

The pattern of a rule can be changed by the setPattern method:

assert(0 == strcmp(rule.pattern(), "WEEKEND*"));
 
rule.setPattern("WEEKDAY*");
assert(0 == strcmp(rule.pattern(), "WEEKDAY*"));

The threshold levels of a rule can also be modified by the setLevels method:

assert(ball::Severity::e_OFF  == rule.recordLevel());
assert(ball::Severity::e_INFO == rule.passLevel());
assert(ball::Severity::e_OFF  == rule.triggerLevel());
assert(ball::Severity::e_OFF  == rule.triggerAllLevel());
 
rule.setLevels(ball::Severity::e_INFO,
               ball::Severity::e_OFF,
               ball::Severity::e_INFO,
               ball::Severity::e_INFO);
 
assert(ball::Severity::e_INFO == rule.recordLevel());
assert(ball::Severity::e_OFF  == rule.passLevel());
assert(ball::Severity::e_INFO == rule.triggerLevel());
assert(ball::Severity::e_INFO == rule.triggerAllLevel());