###############
BAM expressions
###############

The BAM module of Centreon Broker work together with Centreon BAM to
compute (among other things) Business Activites availabilities. To
compute these availabilities, which can be quite complex, Centreon
Broker can use *expressions*. And these expressions can be used as
KPIs that impact BAs whether they're true or not.

Expressions are expressed in a programming-language-like syntax that
contain basic operators and function calls.

Operators
---------

============= ========================================
Operator      Action
============= ========================================
==            Boolean equality check.
!=            Boolean inequality check.
||            Boolean OR.
&&            Boolean AND.
!             Boolean negate.
>             Strictly greater than.
>=            Greater or equal to.
<             Strictly less than.
<=            Less than or equal to.
\+             Add.
\-             Substract.
\*             Multiply.
/             Divide.
%             Modulus.
============= ========================================

Functions
---------

================ =========================== =======================================
Function         Action                      Example
================ =========================== =======================================
HOSTSTATUS()     Get the numeric status of a HOSTSTATUS('Central-Server')
                 host.
SERVICESTATUS()  Get the numeric status of a SERVICESTATUS('Central-Server', 'Ping')
                 service.
AVERAGE()        Compute the average value   AVERAGE(36, 42, 26)
		 of its arguments.           AVERAGE(METRICS('rta'))
COUNT()          Compute the number of its   COUNT(36, 42, 26)
		 arguments.                  COUNT(METRICS('rta'))
MAX()            Compute the maximum value   MAX(36, 42, 26)
		 of its arguments.           MAX(METRICS('rta'))
MIN()            Compute the minimum value   MIN(36, 42, 26)
		 of its arguments.           MIN(METRICS('rta'))
SUM()            Compute the sum of its      SUM(36, 42, 26)
		 arguments.                  SUM(METRICS('rta'))
METRICS()        Get multiple metrics that   METRICS('rta')
                 matches a metric name. Its
		 use is only allowed in
		 aggregation functions. It
                 should not be used directly
                 as an operand.
METRIC()         Get a single metric value.  METRIC('Central-Server', 'Ping', 'rta')
                 It can be used directly     AVERAGE(METRICS('rta'), METRIC('Central-Server', 'Ping', 'my_custom_rta'))
		 as an operand or as an
		 argument to an aggregation
		 function.
CALL()           Call another expression     CALL('MyExpression')
                 from its name (defined in
		 Centreon BAM).
================ =========================== =======================================

Macros
------

To make things clearer, some macros are available.

=============== ===============================================
Macro           Description
=============== ===============================================
OK              OK status' numeric ID. Evaluates to 0.
WARNING         WARNING status' numeric ID. Evaluates to 1.
CRITICAL        CRITICAL status' numeric ID. Evaluates to 2.
UNKNOWN         UNKNOWN status' numeric ID. Evaluates to 3.
UP              UP status' numeric ID. Evaluates to 0.
DOWN            DOWN status' numeric ID. Evaluates to 1.
UNREACHABLE     UNREACHABLE status' numeric ID. Evaluates to 2.
=============== ===============================================

Concrete examples
-----------------

Check if a service is OK.

SERVICESTATUS('Central-Server', 'Ping') == OK

Check if the sum of all traffics exceed a threshold.

SUM(METRICS('traffic_in'), METRICS('traffic_out')) > 100000000
