Custom impact function
The EXTERNAL option is a slot value of impact_function. An external impact computation function is implemented as an MRL action acting on the BMC_BaseElement data class. This action must return a component status that is assigned to the impact_status value of the CI. The action must exist in the bin directory of the cell KB and be listed in the .load file.
The format of an external impact computation action can be one of the following two code snippets:
[arg1: STRING($ARG1),...]:
MC_SM_COMPONENT($C)
{
...
action_return(0,<impact_status>);
}
}
END
or:
[arg1: STRING($ARG1),...]:
MC_SM_COMPONENT($C)
{
...
action_return(0,<impact_status>/<true_impact_status>);
}
}
END
where:
- < function name > is the name of the external impact function.
- < impact_status > is an MRL expression that gives the impact status of the CI.
- < true_impact_status > is an MRL expression that gives the minimum status that must be propagated by a relationship for that relationship to be considered a "true impact" relationship. If only the < impact_status > value is returned, then the < true_impact_status > is considered equal to the < impact_status > value, and this value is used (as in the case of an in-built impact function).
The sim_impact_function group is mandatory.
The BMC_STATUS_COMPUTATION data class references an external impact function by setting the following slots:
ext_impact_function = [<function_name>,<arg1 value>,...]
If the impact function is defined with arguments, the values of these arguments come after the function name in the ext_impact_function slot. If there are no arguments, the list contains only the function name.
If the status model specifies an external action, this action is called, and the status returned by this action is set to the impact_status. An error message is displayed, and the HIGHEST_VAL computation method is reverted to if one of the following condition, is satisfied:
- The action does not exist.
- The action exists but there is a mismatch in the number or type of arguments.
- The action fails.
Primitives for the custom impact function
To compute the impact status, additional primitives or functions are available. Many of these primitives fail if called outside of an impact function computation action.
sim_number_of_propagating_relationships/1
$NUM = sim_number_of_propagating_relationships();
Returns the number of relationships ($NUM) that propagate a status (excluding disabled relationships with propagated_status=NONE). Fails outside an impact status computation action.
sim_weight_of_propagating_relationships/1
$SUM = sim_weight_of_propagating_relationships();
Returns the sum ($SUM) of the weight of all relationships that propagate a status (excluding disabled relationships with propagated_status=NONE). Fails outside an impact status computation action.
sim_number_and_weight_of_propagating_relationships/2
Returns the number of relationships that propagate a status and the sum ($SUM) of all their weight (excluding disabled relationships with propagated_status=NONE). Fails outside an impact status computation action.
sim_total_propagated_status_val/1
$SUM = sim_total_propagated_status_val();
Returns the sum ($SUM) of all the numeric values of the propagated status of relationships (excluding disabled relationships with propagated_status=NONE). Fails outside an impact status computation action.
sim_total_propagated_weighted_status_val/1
$SUM = sim_total_weighted_propagated_status_val();
Returns the sum ($SUM) of all the numeric values of the propagated status multiplied by the weight of each relationship (excluding disabled relationships with propagated_status=NONE). Fails outside an impact status computation action.
sim_highest_propagated_status/1
$S=sim_highest_propagated_status();
Returns the highest status ($S) propagated to the current CI. Fails outside an impact status computation action.
sim_lowest_propagated_status/1
$S=sim_lowest_propagated_status();
Returns the lowest status ($S) propagated to the current CI (excluding disabled relationships with propagated_status=NONE). Fails outside an impact status computation action.
sim_number_of_propagated_status/2
$NUM=sim_number_of_propagated_status($STATUS);
Returns the number of times ($NUM) a specific status ($STATUS) is propagated. Fails outside an impact status computation action.
sim_weighted_propagated_status/2
$SUM=sim_weighted_propagated_status($STATUS);
Returns the sum ($SUM) of all the weight of the relationships that propagate a specific status ($STATUS). Fails outside an impact status computation action.
sim_number_of_ge_propagated_status/2
$NUM=sim_number_of_ge_propagated_status($STATUS);
Return the number of times ($NUM) a status greater than or equal to a certain value ($STATUS) is propagated. Fails outside an impact status computation action.
sim_weighted_ge_propagated_status/2
$SUM=sim_weighted_ge_propagated_status($STATUS);
Returns the sum ($SUM) of all the weight of the relationships that propagate a status greater than or equal to a certain value ($STATUS). Fails outside an impact status computation action.
sim_quorum_propagated_status/2
$STATUS=sim_quorum_propagated_status($QUORUM);
Returns the minimum status ($STATUS) that is at least propagated by a ($QUORUM) percentage of relationships. Fails outside an impact status computation action.
sim_quorum_weighted_propagated_status/2
$STATUS=sim_quorum_weighted_propagated_status($QUORUM);
Returns the minimum status ($STATUS) that is propagated by a ($QUORUM) percentage of weighted propagated status. This means that each propagated status is multiplied by its respective weight. Fails outside an impact status computation action.
sim_nearest_status/2
$STATUS=sim_nearest_status($NUM);
Returns the closest status ($NUM) corresponding to a numerical value ($NUM). In case $NUM is just in the middle of two status numerical values, the lower status is selected.
sim_round_down_status/2
$STATUS=sim_round_down_status($NUM);
Returns the highest status ($STATUS) whose numerical value is not larger than $NUM. If no such status exists, the lowest status (NONE=1) is returned.
sim_round_up_status/2
$STATUS=sim_round_up_status($NUM);
Returns the lowest status ($STATUS) whose numerical value is not lower than $NUM. If no such status exists, the highest status (UNAVAILABLE) is returned.
Examples
The following section lists some examples for the custom impact function.
Weighted average up
Function definition
MC_SM_COMPONENT($C)
# impact status is the rounded up weighted average of the propagated status
{
sim_weight_of_propagating_relationships($W1);
sim_total_propagated_weighted_status_val($TW1);
action_return(0,sim_round_up_status($TW1/$W1));
}
END
BMC_STATUS_COMPUTATION data
model_name=WeightedAverageUp;
impact_function=EXTERNAL;
ext_impact_function=[WeightedAverageUp];
self_function=HIGHEST_VAL;
consolidate_function=HIGHEST_VAL;
no_alert_status=OK;
END
Example
Consider a CI impacted by four active relationships, three propagating OK with weight = 200 and one propagating WARNING with weight = 100. The impact_status value is computed as follows:
- sim_weight_of_propagating_relationships($W1) => 3*200 + 100 = 700
- sim_total_propagated_weighted_status_val($TW1) => 3*30*200 + 100 * 50 = 23000
- $TW1/$W1 = 32.85
- The computed impact status is sim_round_up_status (32.85...) => INFO (40).
Weighted quorum
Function definition
['quorum': INTEGER($QUORUM)]
: MC_SM_COMPONENT($C)
# impact staus is the minimal status propagated by a quorum of "weighted" relationships.
# each relationship counts as n relationships in this quorum computation where
# n is the StatusWeight of each relationship
{
action_return(0,sim_quorum_weighted_propagated_status($QUORUM));
}
END
BMC_STATUS_COMPUTATION data
model_name=WeightedQuorum_51;
impact_function=EXTERNAL;
ext_impact_function=[WeightedQuorum,51];
self_function=HIGHEST_VAL;
consolidate_function=HIGHEST_VAL;
no_alert_status=OK;
END
Example
Consider a CI impacted by three active relationships propagating:
- MINOR with weight 200
- WARNING with weight 100
- CRITICAL with weight 100
The computation is as follows:
MINOR is considered propagated 200 times, WARNING 100 times, and CRITICAL 100 times totaling 400 which will be the virtual propagated_status value.
51% of 400 is 204. There are 400 providers that propagate at least MINOR but only 200 that propagate at least WARNING. Therefore, the impact status returned by sim_quorum_weighted_propagated_status($QUORUM) is MINOR.
By contrast, a standard CLUSTER CI using a simple QUORUM of 51 returns WARNING because the relationship weight is not taken into account with the standard QUORUM algorithm. In this case, 66% of the relationship providers propagate the status to be at least WARNING.
OK unless n propagated status
Function definition
['threshold': INTEGER($NUM),'status': MC_SM_COMPONENT_STATUS($STATUS)]
: MC_SM_COMPONENT($C)
{
# impact status = OK
# unless at there are at least $NUM propagated status >= $STATUS,
# in that case impact status is $STATUS
if ( sim_number_of_ge_propagated_status($STATUS) >= $NUM) then
{
action_return(0,$STATUS);
}
else
{
action_return(0,'OK');
};
}
END
BMC_STATUS_COMPUTATION data
model_name=OK_unless_2_UNAVAILABLE;
impact_function=EXTERNAL;
ext_impact_function=[OK_unless_n_status,2,UNAVAILABLE];
self_function=HIGHEST_VAL;
consolidate_function=HIGHEST_VAL;
no_alert_status=OK;
END
Example
With the BMC_STATUS_COMPUTATION model above, the impact status will be OK unless there are at least two UNAVAILABLE propagated status values, in which case, impact_status will be UNAVAILABLE.
OK unless percentage of propagated status
Function definition
['percentage': INTEGER($PERCENT),'status': MC_SM_COMPONENT_STATUS($STATUS)]
: MC_SM_COMPONENT($C)
{
# impact status = OK
# unless at there is a percentage of at least $PERCENT propagated status >= $STATUS,
# in that case impact status is $STATUS
if ( (100 * sim_number_of_ge_propagated_status($STATUS) /sim_number_of_propagating_relationships()) >= $PERCENT) then
{
action_return(0,$STATUS);
}
else
{
action_return(0,'OK');
};
}
END
BMC_STATUS_COMPUTATION data
model_name=OK_unless_50%_UNAVAILABLE;
impact_function=EXTERNAL;
ext_impact_function=[OK_unless_xpercent_status,50,UNAVAILABLE];
self_function=HIGHEST_VAL;
consolidate_function=HIGHEST_VAL;
no_alert_status=OK;
END
Example
With the BMC_STATUS_COMPUTATION model above, the impact status will be OK unless 50% of propagated status values are UNAVAILABLE, in which case, impact_status will be UNAVAILABLE.
Highest unless n OK
Function definition
['number of OK propagated status': INTEGER($NUM)]
: MC_SM_COMPONENT($C)
#impact status is the highest propagated status unless
# there is at least $NUM OK propagated status
{
if ( sim_number_of_propagated_status(OK) >= $NUM) then
{
action_return(0,'OK');
}
else
{
action_return(0,sim_highest_propagated_status());
};
}
END
BMC_STATUS_COMPUTATION data
model_name=Highest_unless_1_OK;
impact_function=EXTERNAL;
ext_impact_function=[Highest_unless_n_OK,1];
self_function=HIGHEST_VAL;
consolidate_function=HIGHEST_VAL;
no_alert_status=OK;
END
Example
With the BMC_STATUS_COMPUTATION model above, the impact status will be the highest propagated status unless there is one OK propagated status.
Highest or Lowest
Function definition
['minimum_status': MC_SM_COMPONENT_STATUS($MIN_STATUS), 'threshold': INTEGER($NUM)]
: MC_SM_COMPONENT($C)
# if there are at least $NUM propagated_status with at least $MIN_STATUS
# the impact status is the highest propagated status and any relationships
# propagating a status >= $MIN_STATUS is considered a true_impact relationship
# Otherwise the impact status is lowest propagated status (in that case all relationships are considered as true impact)
{
if ( sim_number_of_ge_propagated_status($MIN_STATUS) >= $NUM) then
{
action_return(0,sim_highest_propagated_status() || '/'|| $MIN_STATUS);
}
else
{
action_return(0,sim_lowest_propagated_status());
};
}
END
BMC_STATUS_COMPUTATION data
model_name=Highest_Or_Lowest;
impact_function=EXTERNAL;
ext_impact_function=[HiOrLo,MINOR,2];
self_function=HIGHEST_VAL;
consolidate_function=HIGHEST_VAL;
no_alert_status=OK;
END
Example
In the BMC_STATUS_COMPUTATION model above, the impact status will be either the lowest propagated status or the highest propagated status provided that there are at least two propagated_status >= MINOR values.
Consider a case in which there are one WARNING, one MINOR, and one UNAVAILABLE propagated status values. Here, the impact status will be UNAVAILABLE. However, any relationship propagating MINOR must be considered a true impact relationship and not just the relationship propagating UNAVAILABLE.
If the MINOR relationship was propagating WARNING, impact_status would be WARNING (the lowest).