The alert API is used by GUI and testing apps to manage alert processing configuration (alert configuration, alert impression), retrieve data such as profiles and series, and control and monitor system status.
The API is a simple HTTP request-response protocol. GET requests are parametrized by HTTP query parameters, POST requests contained additionally a JSON body. Authentication is accomplished using a JWT carried in header named by default "x-amzn-oidc-accesstoken".
required JWT payload fields:
{
"sub": "5340085e-0e10-4b3c-8f4b-2fefe517bf6b", // administrator ID
"custom:domainid": "5340085e-0e10-4b3c-8f4b-2fefe517bf6b", // tenant id
"custom:adminlevel": "1", // admin level; 0=site
// 1=tenant,2=end-user
"exp": 1688022158 // expires
}
The configuration management calls allow to retrieve, upload and validate configuration of alert processing. (see more on configuration format)
GET https://localhost:4000/api/alertapi/getalertconfig
retrieves current configuration: alert configuration, the configuration of variables, or the transformation function
Parameters:
(optional) subconfig = NONE | alertconfig | alerttransform | varconfig
See also the configuration format.
POST https://localhost:4000/api/alertapi/setalertconfig
uploads a new configuration: alert configuration, the configuration of variables, or the transformation function.
Parameters:
(optional) subconfig = NONE | alertconfig | alerttransform | varconfig
body: configuration. See also the configuration format.
POST https://localhost:4000/api/alertapi/mergevar
uploads a new configuration variable
Parameters:
body: configuration. See also the configuration format.
Body example:
{
"foo" : {"value":"bar","type":"string"}
}
Parameters:
body: alert configuration with optional alert ID (assigned server-side if not supplied). See also the configuration format.
Body example:
{
"enable": true,
"type": "CSM",
"parameters": {
"key": "attrs.from+attrs.source",
"filter": "attrs.type='call-end'"
}
}
GET https://localhost:4000/api/alertapi/exportalert?alertid=RtBq8pd
export alert as an importable token. It is practical to share an alert configuration between multiple systems.
Parameters:
alertid ... unique ID of an alert (can be seen in `getAlertConfig`)
GET https://localhost:4000/api/alertapi/importalert?compr64=....
Import an alert into alert processing configuration as previously exported using the export facility. An imported alert is always set inactive.
Parameters:
compr64 -- encoded alert configuration. it can be found in export alerts API's answer as "compr64" attribute value.
Alert management allows changes to alert processing profile. Unlike configuration management which creates "static" alert configuration, alert managment is part of profiles and defines how alert processing shall be evaluated for a specific alert-key combination.
GET https://localhost:4000/api/alertapi/supress?alertid=14f49a&keyval=10.0.0.1[&toggle=true|false]
Makes sure that an alert <alertid> is no longer raised for a key. For example, one may set that traffic from a trunk IP shall not cause high-traffic alerts.
Parameters:
alertid ... ID of an alert
key
keyval ... value of alert's key OR ...
keyRef ... opaque key reference
optional: toggle .... set supression status to "true" or "False". only return current status of omitted.
The informational APIs list available API calls, alert types, plugins.
GET https://localhost:4000/api/alertapi/help
lists all available API calls.
no parameters
GET https://localhost:4000/api/alertapi/listalerttypes
Show all supported alert types. Used by GUI when creating new alerts.
GET https://localhost:4000/api/alertapi/listingest
list names and parameters of supported ingestion modules. used bo GUI to configure the respective plugins.
no parameters
GET https://localhost:4000/api/alertapi/listrestful
list names and parameters of supported restful modules. used by GUI to configure the respective plugins.
no parameters
The API calls allow us to change logging levels selectively and observe and reset current statistics.
GET https://localhost:4000/api/alertapi/mlogging?module=alerts/timers.js&level=debug
Set logging level for a respective module.
Parameters:
module -- 2-tier source code filename or "*" for all
level -- debug|info|warn (in the order of decreasing level)
POST https://localhost:4000/api/alertapi/slogging
Enables debugging level for events matching an expression
Parameters: none
Body: JSON to include `expr` parameter with a valid matching expression or empty to disable
Body example:
{
"expr": "attrs.type='reg-new'"
}
curl Example:
curl -X POST 'https://localhost:4000/api/alertapi/slogging' --insecure -d '{"expr":"attrs.type=\"ingest_redishealth\""}'
GET https://localhost:4000/api/alertapi/info
retrieves current status: events break-down , alerts by status, status of backing REDIS memory https://redis.io/docs/latest/commands/memory-stats . Statuses that have not been encountered yet during alert processing are not shown (they do not exist, not even with zeroed values).
Counters will be reset using the resetstats API call.
no parameters
The following status counters are available (in processing order):
"disabled": an alert was not processed because it is disabled.
"typefiltered": an alert was not processed because the received event doesn't contain the expected event type in .attrs.type. Used in some domain-specific alerts.
"auxfilterna": an alert was not processed because the alert's type filter didn't find the expected attributes in the received event.
"auxfiltered": an alert was not processed because the alert's type filter didn't match the received event.
"filterna": an alert was not processed because the custom filter didn't find the expected attributes in the received event.
"filtered": an alert was not processed because the custom filter didn't match the received event.
"nokey": an alert was not processed because the key attribute was not found in the received event.
"lowscore": an alert's score is non-zero but still too low for an alert to be raised. (the score is evaluated on a key-by-key basis)
"userSupressed": an alert's score is above the threshold, but the alert will not be raised because it was suppressed for the given key value using the suppression API.
"throttled": an alert's score is above the threshold, but the alert will not be raised because it was raised recently (throttling period is configurable on an alert-by-alert basis)
"blisted": an alert's score is above the threshold, but the alert will not be raised because it was blacklisted recently
"raised": an alert's score is above the threshold and is scheduled for raising.
"unsent": a raised alert is not sent because of concurrency control. (multiple threads chose to generate the same alert in parallel)
"sent": a raised alert that will be sent.
{
"statusCode":200,
"statusDescription":"info for ba86ac2a-7f13-44b3-ba77-4dc29e6f6305 ",
"data":{
"startedMs":1728300293640,
"startedIso":"2024-10-07T11:24:53.640Z",
"info":"info for tenant ba86ac2a-7f13-44b3-ba77-4dc29e6f6305",
"tenant":{
"startedMs":1728300293640, // timestamp when alert processing started
"startedIso":"2024-10-07T11:24:53.640Z", // the same in ISO format
"resetMs":1728300295345, // timestamp when counters were reset
"resetIso":"2024-10-07T11:24:55.345Z", // the same in ISO format
"events":5, // number of events received
"eventsByType":{ // break-down by event type (attrs.type)
"call-end":4,
"nevermatch":1
},
"alertsById":{ // alert break-down by alert-ID
"123456":{ // alert-ID
"raised":2, // "raised" count for alert "123456"
"sent":2,
"throttled":2,
"filtered":1
},
"OKREG":{
"typefiltered":5
},
"825feda9":{
"filterna":2,
"filtered":2,
"raised":1,
"sent":1
},
...
},
"alertsByStatus":{ // alert break-down by status
"filtered":{ // status "filtered"
"123456":1, // ... encountered once for alert 123456
"CTHR":5,
"BTCR":5,
"BICR":5,
"SM":3,
"2ba92f67":2,
"d7cabb01":3,
"825feda9":2,
"3a7a703a":2,
"9304ba1f":2
},
...
},
"totals": { // processing result totals
"exceptions":0, // number of events completed by an exception
"filtered":30, // total (status x alerts) count
"typefiltered":38,
"filterna":6,
"raised":10,
"sent":10,
"throttled":14
}
},
"meminfo":{ // REDIS-specific memory stats
"peakAllocated":48688992,
"totalAllocated":46126784,
"keysCount":1527,
...
}
}
}
Parameters: none
Profiles represent data collected "on" specific keys registered during event ingestion. The data stored on profiles is essential in evaluating whether an alert shall be raised for a key. The profiles comprise multiple sections specific to each alert processed for the key. See the note in the keys article about how to form query parameters to identify a key correctly. In addition to profiles, there may be series data available as well for some alerts. While the series are stored physically elsewhere, they serve a similar purpose and are identified by key and alert as well.
GET https://localhost:4000/api/alertapi/getprofile?keyval=proxy&keyname=cstm%23attrs.dst_ca_name
retrieves a custom-keyed profiles.
Parameters:
by alert ID and keyval (alert ID implies keyname)
alertId
keyval
by key reference
keyRef
by name and value
keyname ... name of an event attribute chosen as custom key; custom keys MUST be prefixed by "cstm%23"
keyval ... value of the attribute
Tenant profile is retrieved by empty keyname:
GET https://localhost:4000/api/alertapi/getprofile?keyname=cstm%23
⚠️ GET xhttps://localhost:4000/api/alertapi/rmprofile?keyval=proxy&keyname=cstm%23attrs.dst_ca_name
removes a profile permanently. URI broken to avoid a mistaken deletion.
Parameters:
keyname ... name of an event attribute chosen as custom key; it MUST be prefixed by "cstm%23"
keyval ... value of the attribute
Parameters:
by alert ID and keyval
alertId
keyval
by key reference
keyRef
by name and value
keyname ... name of an event attribute chosen as custom key; it MUST be prefixed by "cstm%23"
keyval ... value of the attribute
GET https://localhost:4000/api/alertapi/getseries?alertid=ItX4jNJ&keyval=45.126.184.197
Show collected time series for an alert with enabled series parameters. Currently available: the rate for custom-key rate alert type, ratio for custom-key ratio, the number of parallel calls for custom-key parallel call alert types, and short and long-term averages for sudden-change alert-type. The data in answer represents the series at three levels of aggregation: "real" shows series (a list of timestamp/value pairs) as determined during alert processing, "mid" and "long" represent more extended history at a more coarse resolution.
Series are not technically stored as part of a profile because they leverage a specific REDIS feature. From the non-technical point of view, they play the same role as if they were part of a profile: they represent a key's history, are stored persistently, and are used for alert evaluation. Internally, they are labeled by alert id, tenant id, and aggregation level.
Parameters:
alertid: unique id of an alert.
key:
keyval: value of key for which the series is collected OR ...
keyRef: key reference
Example answer:
{
"statusCode":200,
"statusDescription":"series ratio retrieved",
"data":{
"real":[
{
"timestamp":1728409575000,
"value":100
},
{
"timestamp":1728409590000,
"value":100
},
{
"timestamp":1728409605000,
"value":100
},
...
{
"timestamp":1728416760000,
"value":100
},
{
"timestamp":1728416775000,
"value":100
}
],
"mid":[
{
"timestamp":1728392400000,
"value":100
},
{
"timestamp":1728392700000,
"value":100
},
...
{
"timestamp":1728416400000,
"value":100
}
],
"long":[
{
"timestamp":1728392400000,
"value":100
},
{
"timestamp":1728394200000,
"value":100
},
...
{
"timestamp":1728414000000,
"value":100
}
]
}
}
GET https://localhost:4000/api/alertapi/delseries?alertid=ItX4jNJ&keyval=45.126.184.197
removes series from REDIS databases.
Parameters:
alertid: unique id of an alert.
key:
keyval: value of key for which the series is collected OR ...
keyRef: key reference
GET https://localhost:4000/api/alertapi/delallseries
removes all tenant's series from REDIS databases.
Parameters: none
POST https://localhost:4000/api/alertapi/validateexpr
an API call for testing that validates a matching expression. In the request body, there is the matching expression in the "expr" attribute and a test-event to test against in "event." If the matching expression is invalid or refers to non-existent event attributes, a 404 it returned, matching result otherwise.
invalid expresssion (missing ")
curl --insecure 'http://localhost:80/api/alertapi/validateexpr' -d '{"expr":"attrs.type~\"ingest_redishealth|call-start|call-end", "event": {"attrs":{"type":"call-end" }} }'
{"statusCode":404,"statusDescription":"invalid expression: attrs.type~\"ingest_redishealth|call-start|call-end"}
non-matching expression (equal operator)
curl --insecure 'http://localhost:80/api/alertapi/validateexpr' -d '{"expr":"attrs.type=\"ingest_redishealth|call-start|call-end\"", "event": {"attrs":{"type":"foo" }} }'
{"match":false,"result":false}
matching expression (regexp operator)
curl --insecure 'http://localhost:80/api/alertapi/validateexpr' -d '{"expr":"attrs.type~\"ingest_redishealth|call-start|call-end\"", "event": {"attrs":{"type":"call-end" }} }'
{"match":"(attrs.type:=call-end) ~ ingest_redishealth|call-start|call-end","result":true}
validation expression taking reference to a non-existent attribute (counts as invalid expression)
curl --insecure 'http://localhost:80/api/alertapi/validateexpr' -d '{"expr":"attrs.type~\"ingest_redishealth|call-start|call-end\"", "event": {"attrs":{"type2":"call-end" }} }'
{"statusCode":404,"statusDescription":"invalid expression: attrs.type~\"ingest_redishealth|call-start|call-end\""}
GET https://localhost:4000/api/alertapi/exprvalidator
retrieves JS code to validate a matching expression.
test if an expression is valid
const expr='attrs.type~"ingest_redishealth|call-start|call-end"';
if (ev.parseExpression(expr)===undefined) {
console.log(`SORRY invalid expression: ${expr}`);
}