Configuration management is a central part of alert processing: it allows specifying what type of alert is raised under what conditions. The Alert API manages all configuration aspects: reading, storing, and validation. The related API calls are "getAlertConfig", "setAlertConfig", "addAlert" and "mergeVar". Physically, the configuration is stored in Elastic Search and cached on the file system for better performance.
The configuration is used in the processing workflow for every event, along with profiles, to judge whether an alert should be raised. The configuration comprises three parts: alert configuration, transformation function, and variables. Alert Configuration lists all alerts that have been set up. The transformation function is an optional Javascript code that allows modification of incoming events before alert processing. It is useful, for example, if telephone numbers in events are transformed into a canonical E.164 form. The variables are also optional and may be used to parameterize the transformation function.
The alert configuration format is a map of configured alerts. An annotated fragment retrieved by the "getAlertConfig" API and returned in the HTTP answer body is shown below. The alert map returned by this call is wrapped in "config" to leave a place for additional metadata. Ephemeral alert IDs key the map; they are generated client-side and are case-sensitive alphanumerical. Each alert configuration object includes a reference to the alert type, human-readable description, and alert parameters, both common and specific to the alert type.
{
"config": { // getAlertConfig "wrapper" to separate from future metadata
"ZHkY0m2U": { // ephemeral alert ID
"enable": true, // enable/disable status
"description": "telemarketer", // admin chosen description of the alert
"type": "CKR", // alert type
"id": "ZHkY0m2U" // id (same as the map key)
"parameters": { // alert parameters: some common, some specific to alert-types
"key": {
"value": "attrs.from"
},
"window": {
"value": 10
},
"mrlimit": {
"value": 90
},
"ignore": {
"value": 10
},
"subfilter": {
"value": "attrs.duration<5"
},
"filter": {
"value": "attrs.type~'call-attempt|call-end'"
},
"op": {
"value": ">"
},
"select": {
"value": ""
},
"restfulFmt": {
"value": ""
},
"throttlePeriod": {
"value": 600
},
"series": {
"value": false
},
"severity": {
"value": 2
},
"restfulChannel": {
"value": ""
}
}
},
"ciF8i9Ky": {
"enable": true,
"description": "exp-regs began to change rapidly",
"type": "CSC",
"id": "ciF8i9Ky"
"parameters": {
"key": {
"value": "tls-cn"
},
"restfulFmt": {
"value": ""
},
"filter": {
"value": "attrs.type=\"reg-expired\""
},
"window": {
"value": 5
},
"deviation": {
"value": 80
},
"ignore": {
"value": 10
},
"throttlePeriod": {
"value": 600
},
"severity": {
"value": 2
}
}
},
...
A compact parameter is also supported: instead of using "key": { "value": VALUE, the shortcut "key": VALUE can be used when submitting parameters in `setAlertConfig` API POST call. (Note that `setAlertConfig` does not use the ".config" nesting.)
{
"ZHkY0m2U": { // ephemeral alert ID
"enable": true, // enable/disable status
"parameters": {
"key": "attrs.from", // compact parameter form
"window": 10,
...
The optional transformation function allows custom pre-processing of incoming events. To enable it upload function's code in body of `setalertconfig?subconfig=alerttransform` API POST request. The function is managed as simple text, example of which is shown bellow.
function addDuration(event, myvar) {
if (!(event.attrs.type==="call-attempt")) return;
event.attrs.duration=0;
}
Predefined variables can parametrize the transformation function to allow minor transformation adjustments without touching the transformation code. The variables are passed as an object in the second parameter to the transformation function. A variable can be introduced using the `mergeVar` and retrieved using the `getalertconfig?subconfig=varconfig` API call. The HTTP body returned by getalertconfig is shown in the example below. Like with alert code, it is wrapped in "config" attribute, and mapped by variable name ("foo" and "slack#1" in the example). The variable is further described by value ("bar") and type ("string"), which can be one of string, JSON, boolean, integer, int, IP, URI, and matching expression. Encrypted versions thereof are also reserved for future uses in a privacy context. Special variables are intended for configuring restful and ingestion plugins: such are denoted by "group" attribute, are always of "json" type, and the JSON object includes attributes specific to the respective plugin.
{
"config": {
"foo": {
"value": "bar",
"type": "string"
},
"slack#1": {
"value": {
"slack.uri": "https://hooks.slack.com/services/SDJK3459/JK34JLK/sm48sk5nabb"
},
"type": "json",
"group": "restful:slack"
}
}
}