Alerts

Attributes

id (read-only) Unique ID for the alert in our system.
name The name for the alert.
active Boolean indicating whether the alert is active.
direction String indicating Threshold Direction. ‘Above’ means above threshold for the alert to be triggered, ‘below’ means below threshold, and ‘outside bounds’ means outside the bounds of the upper and lower threshold set by ‘out of band’ alerts. See threshold_type in the POST method for more details.
type (read-only) The type of alert (‘Application’, ‘Process’, ‘Server’, ‘Polled Data’, ‘Log’, ‘Server Tag’).
target (read-only) The target of the alert, must be an existing object in the system.
target_id (read-only) The ID of the target of the alert (used when creating the alert).
trigger (read-only) The alert trigger.
trigger_type (read-only) The type of trigger for alert. The trigger type must be set when the alert is created. Some trigger type are only available for certain alert types. For details, see the ‘Alert Creation’ section.
num_of_servers The number of servers that have reached the condition for an alert to be triggered (only used on ‘Server Tag’ alerts).
interval Time to resend an alert (in the unit of minute).
time_above_ threshold Time required for an alert to remain above the threshold before sending alert (in the unit of minute).
threshold Threshold value for alerting (now large enough for any conceivable values). Decimal value for ‘Disk’ alert, for example ’99.999′ and Large integer for all the other alerts.
reg_exp Specifies the regular expression used in alert (only for alert types requires content match).
part_name The name of the part for threshold_part alerts (only used on ‘Disk’ and ‘Disk Busy’ alert. Should be a disk name, for example ‘C:’).
ip_details A comma separated integer list which indicates the list of port number used in Port Accessed alert. For example, ’23,8080,50010′.
last_triggered (read-only) The last time this alert was triggered.
in_incident (read-only) Boolean indicating whether the alert is currently in an incident.
users A list of users to which the alert will be sent. A valid user id or email must be provided for each user. There are currently three options for each user, ["sendemail", "sendsms", "pushnotification"].
subscribers The REST API subscribers that will be called when this alert triggers or resolved. When an alert is triggered or is resolved, we will call this API with a GET (default) or POST request and urlencoded data like:

alert_id={ALERT_ID}&alert_history_id={ID}&status={TRIGGERED or RESOLVED}.

So if you provide a subscriber of {“url”:”http://example.com/”}, when an alert triggers we would make a GET request to something like:

http://example.com/?alert_id=5&alert_history_id=65&status=TRIGGERED
window_length Only relevant for ‘sudden change’ alerts. Length of the window that we are comparing the current minute data to.
window_units Only relevant for ‘sudden change’ alerts. Units of the window that we are comparing the current minute data to. Must either be ‘h’ for hour or ‘d’ for day.
band_value Only relevant for ‘sudden change’ alerts. The number of standard deviations away from the mean. The mean and standard deviation are dependent on the window_length and window_units of the particular alert.
url (read-only) URL information about the requested item.

Available APIs

/api/alerts

List of all available alerts or create a new one. See above for the attributes each alert has.

GET

Return a list of alerts matching the query.

Arguments

  • limit (optional, default:2500, max:2500) – Sets the page size to a limit set by the user.
  • page (optional, default:0) – Retrieve the specific page of data of size limit.
  • filter_name (optional) – the type of object to filter the alerts. Must be one of “application_id”,”process_id”,”server_id”, “polled_data_id”, “log_id”.
  • filter_id (optional) – The id of the objects, must be integer value.

Argument Examples

  • limit=10 – will get the first page of the first 10 items.
  • limit=25&page=3 – will get the 4th page of size 25 items.

Example

curl --user {EMAIL}:{API_KEY} https://wwws.appfirst.com/api/alerts/?limit=200
{
    "pagination": {
        "count": 2469, 
        "next": null, 
        "previous": null
    }, 
    data: [
        {
            // CPU alert on a collector/server
            "last_triggered": 1262304000,
            "name": "alert example name",
            "target": "/api/v5/servers/1/",
            "target_id": 1,
            "in_incident": true,
            "interval": 5,
            "time_above_threshold": 5,
            "threshold": 90,
            "direction": "above",
            "trigger": "CPU below 90% for 1 min",
            "trigger_type": "CPU",
            "target": "default_collector",
            "active": true,
            "reg_exp": "",
            "part_name": "",
            "ip_details": "",
            "type": "Server",
            "id": 1,
            "users": '[{"pushnotification": true, "sendsms": true, "id": 1, "sendemail": false}]',
            "subscribers": null,
            "window_length": 0,
            "window_units": "h",
            "band_value": 0,
            "url": "/api/v5/alerts/1/",
        },
        {
            //Memory alert on an application
            "last_triggered": null,
            "name": "My Application Alert",
            "target": "/api/v5/applications/3/",
            "in_incident": true,
            "trigger": "Memory above 20 KB for 1 min",
            "trigger_type": "Memory",
            "target": "my application",
            "target_id": 3,
            "active": true,
            "interval": 5,
            "time_above_threshold": 5,
            "threshold": 20000,
            "reg_exp": "",
            "type": "Application",
            "id": 2,
            "users": '[{"pushnotification": true, "sendsms": true, "id": 1, "sendemail": false}]',
            "subscribers": null,
            "window_length": 0,
            "window_units": "h",
            "band_value": 0,
            "url": "/api/v5/alerts/2/",
        },
        {
            //Log content alert on a log source
            "last_triggered": null,
            "target": null,
            "num_of_servers": 1,
            "ip_details": "",
            "threshold": null,
            "id": 3,
            "reg_exp": "*ERROR*",
            "trigger_type": "Log Content",
            "trigger": "Log Content (Contains Keywords) matches: *ERROR*",
            "time_above_threshold": 1,
            "type": "Log",
            "direction": "above",
            "users": '[{"pushnotification": true, "sendsms": true, "id": 1, "sendemail": false}]',
            "target_id": 1,
            "subscribers": null,
            "active": true,
            "target": "File: /var/log/messages on collector",
            "name": "My Log Alert",
            "part_name": "MAX",
            "interval": 1,
            "in_incident": false,
            "window_length": 0,
            "window_units": "h",
            "band_value": 0,
            "url": "/api/v5/alerts/3/"
        },
        {
            // Disk space alert on an existing Disk partition.
            "last_triggered": null,
            "target": "/api/v5/servers/4/",
            "num_of_servers": 1,
            "ip_details": "",
            "threshold": "99.99",
            "id": 4,
            "reg_exp": "",
            "trigger_type": "Disk",
            "trigger": "Disk (Space) on D: above 99.99 % for 1 min",
            "time_above_threshold": 1,
            "type": "Server",
            "direction": "above",
            "users": '[{"pushnotification": true, "sendsms": true, "id": 1, "sendemail": false}]',
            "target_id": 1,
            "subscribers": null,
            "active": true,
            "target": "collector",
            "name": "a1",
            "part_name": "D:",
            "interval": 1,
            "in_incident": false,
            "window_length": 0,
            "window_units": "h",
            "band_value": 0,
            "url": "/api/v5/alerts/1/"
        },
        {
            // Port Accessesd alert on an application.
            "last_triggered": null,
            "target": "/api/v5/applications/1/",
            "num_of_servers": 1,
            "ip_details": "9999,1111,33333",
            "threshold": null,
            "id": 5,
            "reg_exp": "",
            "trigger_type": "Port Accessed",
            "trigger": "Network (Port Accessed) is anything but 9999,1111,33333",
            "time_above_threshold": 1,
            "type": "Application",
            "direction": "above",
            "users": '[{"pushnotification": true, "sendsms": true, "id": 1, "sendemail": false}]',
            "target_id": 1,
            "subscribers": null,
            "active": true,
            "target": "Tag1",
            "name": "My Port Access Alert",
            "part_name": "MAX",
            "interval": 1,
            "in_incident": false,
            "window_length": 0,
            "window_units": "h",
            "band_value": 0,
            "url": "/api/v5/alerts/5/"
        },
        {
            // Polled data Alert
            "last_triggered": null,
            "target": "/api/v5/polled-data/1/",
            "num_of_servers": 1,
            "ip_details": "",
            "threshold": null,
            "id": 6,
            "reg_exp": "",
            "trigger_type": "Nagios",
            "trigger": "Non-OK status",
            "time_above_threshold": 1,
            "type": "Polled Data",
            "direction": "above",
            "users": '[{"pushnotification": true, "sendsms": true, "id": 1, "sendemail": false}]',
            "target_id": 1,
            "subscribers": null,
            "active": true,
            "target": "Check Http on collector",
            "name": "My Nagios Script Alert",
            "part_name": "MAX",
            "interval": 1,
            "in_incident": false,
            "window_length": 0,
            "window_units": "h",
            "band_value": 0,
            "url": "/api/v5/alerts/6/"
        }
    ]
}

POST

Create a new alert on a target.

Arguments

  • name (required, String, length:1-32) – the name of the alert.
  • type (required, String) – the type of alerts. Must be one of ‘Application’, ‘Process’, ‘Server’, ‘Polled Data’, ‘Log’, ‘Server Tag’.
  • target_id (required, String) – the system id of the target object. It is a comma separated list for ‘Process’ alert (server id, process pid, process creation time and process name, or ‘server_id,pid,creationtime,myname’). and it is an integer value for all the other alert types.
  • trigger_type (required, String) – alert type decides what trigger types are available.
    • ‘Log’ – ['Number of Info', 'Number of Warning', 'Number of Critical', 'Log Content']
    • ‘Polled Data’ – ['Nagios']
    • ‘Process’ – ['Process Termination', 'CPU', 'Memory', 'Average Response Time', 'File Read', 'File Write', 'Inbound Network Traffic', 'Outbound Network Traffic', 'Network Connections', 'Threads', 'Files', 'Registries', 'Page Faults', 'Incident Reports', 'Critical Incident Reports', 'Incident Report Content', 'File Accessed', 'Registry Accessed', 'Port Accessed']
    • ‘Application’ – ['Processes', 'Process Termination', 'CPU', 'Memory', 'Average Response Time', 'File Read', 'File Write', 'Inbound Network Traffic', 'Outbound Network Traffic', 'Network Connections', 'Threads', 'Files', 'Registries', 'Page Faults', 'Incident Reports', 'Critical Incident Reports', 'Incident Report Content', 'File Accessed', 'Registry Accessed', 'Port Accessed']
    • ‘Server’ – ['Server Down', 'CPU', 'Memory', 'Average Response Time', 'Disk', 'Disk Busy', 'Threads', 'Page Faults', 'Processes']
    • ‘Server Tag’ – ['Server Down', 'CPU', 'Memory', 'Average Response Time', 'Disk Busy', 'Threads', 'Page Faults', 'Processes']
  • users (required, String) – a list of users in JSON dumped format. At least one user has to be assigned for a new alert. Each user can be identified by the ‘user_id’ field in User Profile API. Note that using email addresses to identify the user has been deprecated.
  • active (optional, Boolean, default: True) – Whether the alert is active.
  • direction (optional, String, default: above) – Alert threshold direction.
  • threshold (optional) Threshold for the alert to be triggered. Decimal for ‘Disk’ alert, long for all other.
  • threshold_type (optional, String, default: static) The threshold type of alert. Can either be ‘static’ or ‘out of band’. ‘Out of band’ alerts are only applicable to alerts on servers, applications, polled data, and proceses. ‘Out of band’ alerts are also only applicable to the following trigger_types: CPU, Memory, Average Response Time, File Read, File Write, Inbound Network Traffic, Outbound Network Traffic, Network Connections, Threads, Files, Registries, Page Faults, Incident Reports, and Critical Incident Reports.
  • band_value (optional, Float, default: 2.00) The number of standard deviations away from the mean for the given window.
  • window_length (optional, Integer, default: 1) The size of the window. Must be between 1-23 inclusive for hour and 1-31 inclusive for day.
  • window_units (optional, Character, default: ‘h’) The units of the window. Must be either ‘h’ for hour or ‘d’ for day.
  • interval (optional, Integer, default: 10) – Time to resend an alert (in the unit of minutes)
  • time_above_threshold (optional, Integer, default: 1) – Time required for alert to remain above threshold before sending alert (in the unit of minutes)
  • num_of_servers (optional, Integer, default: 1) – The number of servers that have reached the condition for an alert to be triggered.
  • part_name (optional, String, default: “MAX”) – The name of partition for ‘Disk’ and ‘Disk Busy’ alert. Example: “C:”
  • ip_detail (optional, String, default: “”) – The port lists for ‘Port Accessed’ Alert. Example: “23,80″.
  • reg_exp (optional, String, default: “”) – The regular expression for content alert. Example: “ERROR”.

Example

curl --user {EMAIL}:{API_KEY} -d 'name=cpu_alert_on_my_server&threshold=90&type=Process&target_id=1111,1284,1262304000087987676,httpd&trigger_type=CPU&users=[{"id":1, "sendemail": true}]' https://wwws.appfirst.com/api/alerts/

{
    "last_triggered": 1262304000,
    "name": "cpu_alert_on_my_server",
    "target_id": '1111,1284,1262304000087987676,httpd',
    "in_incident": true,
    "interval": 5,
    "time_above_threshold": 5,
    "threshold": 90,
    "direction": "above",
    "trigger": "CPU above 90% for 1 min",
    "trigger_type": "CPU",
    "target": "default process",
    "active": true,
    "part_name": "",
    "ip_details": "",
    "type": "Process",
    "users": '[{"pushnotification": true, "sendsms": true, "id": 1, "sendemail": false}]',
    "id": 1,
    "subscribers": null,
    "window_length": 0,
    "window_units": "h",
    "band_value": 0,
    "url": "/api/v5/alerts/1/",
}

/api/alerts/{alert_id}/

View, update, or subscribe to an alert.

GET

Get info about a specific alert, given by the alert_id in the URL. It takes no additional parameters.

curl --user {EMAIL}:{API_KEY} https://wwws.appfirst.com/api/alerts/1/
 
{
    "id": 609777, 
    "name": "High CPU on e6bf3f881d3b", 
    "type": "Server", 
    "target": "e6bf3f881d3b", 
    "target_id": 265792, 
    "trigger_type": "CPU", 
    "trigger": "CPU above 75.00 % for 3 min", 
    "band_value": 0.0, 
    "threshold": 75.0, 
    "direction": "above", 
    "active": true, 
    "last_triggered": null, 
    "window_length": 0, 
    "window_units": "h", 
    "time_above_threshold": 3, 
    "num_of_servers": 1, 
    "ip_details": "", 
    "reg_exp": "", 
    "users": [
        {
            "pushnotification": true, 
            "sendsms": false, 
            "id": 1, 
            "sendemail": true
        }
    ], 
    "subscribers": null, 
    "part_name": "MAX", 
    "interval": 15, 
    "in_incident": false, 
    "url": "/api/v5/alerts/609777/"
}

PUT

Update the information for a specific alert. You can only update any values that are NOT marked as read-only (name, ip_details, interval, threshold, part_name, time_above_threshold, active, direction, reg_exp, num_of_servers). You can NOT change the target, trigger or type of an alert once it has been created. It only updates values that you include. If you do not include a value it does not get modified. Instead, it returns the modified alert.

Email receivers/users
You can setup up a list of users who will be notified. There are three ways to notify users: email, SMS, mobile push notification. When an alert is triggered, each user is identified by the ‘user_id’ field which can be found by User Profile API. A new user can be created through the User Profile API. Note: using email address to identify a user has been deprecated and will be removed in the next version of API. Simply use a JSON dumped list and set the value of ‘sendemail’, ‘pushnotification’, ‘sendsms’ to ‘True’ or ‘False’. Here’s an example:

{
    "users": '[{"pushnotification": true, 
            "sendsms": true, 
            "id": 1, 
            "sendemail": false}]'
}

Subscribing/Callbacks
You can use this method to subscribe to an alert and be notified whenever the alert triggers and/or is resolved. When an alert is triggered and/or resolved, all APIs listed in the subscribers parameter will be called with a HTTP request and url encoded data like:

alert_id={ALERT_ID}&alert_history_id={ID}&status={TRIGGERED or RESOLVED}.

There are two ways to specify a subscriber; using a url, or by providing a dictionary with a url and other optional parameters. If you just provide a url, the default values for the other parameters are used. You can mix and match these two methods in a single call.

{
    "url":"http://example.com/callback/",
    "auth":"base64encoded basic auth string (username:password)", (optional)
    "type": "get or post", (optional, default: get)
    "event": "TRIGGERED or RESOLVED or BOTH" (optional, default: BOTH)
}

So if you provide a subscriber parameter of ["http://example.com/"], when an alert triggers we would make a GET request to something like:


http://example.com/?alert_id=5&alert_history_id=65&status=TRIGGERED

To unsubscribe completely, pass an empty subscribers parameter, such as “subscribers=[]“.

curl --user {EMAIL}:{API_KEY} -X PUT -d "active=False&subscribers=[{\"url\":\"http://example.com/callback/\", \"auth\":\"dXNlcm5hbWU6cGFzc3dvcmQ=\", \"type\":\"post\", \"event\":\"TRIGGERED\"}, \"https://other.example.com/notify/\"]" https://wwws.appfirst.com/api/alerts/1/
{
    "last_triggered": 1262304000,
    "name": "alert example name",
    "target": "/api/v5/servers/1/",
    "target_id": 1,
    "in_incident": true,
    "interval": 5,
    "time_above_threshold": 5,
    "threshold": 90,
    "direction": "above",
    "trigger": "CPU below 90% for 1 min",
    "trigger_type": "CPU",
    "target": "default_collector",
    "active": false,
    "reg_exp": "",
    "part_name": "",
    "ip_details": "",
    "type": "Server",
    "id": 1,
    "users": '[{"pushnotification": true, "sendsms": true, "id": 1, "sendemail": false}]',
 
    "subscribers": [
        {
            "url":"http://example.com/callback/",
            "auth":"dXNlcm5hbWU6cGFzc3dvcmQ=",
            "type":"post",
            "event":"TRIGGERED"
        },
        {
            "url":"https://other.example.com/notify/",
            "type":"get",
            "event":"BOTH"
        }
    ],
    "window_length": 0,
    "window_units": "h",
    "band_value": 0,
    "url": "/api/v5/alerts/1/",
}

Since it only modifies the values that you pass in, you can disable an alert by:

Example

curl --user {EMAIL}:{API_KEY} -X PUT -d "active=False" https://wwws.appfirst.com/api/alerts/1/
{
    "last_triggered": 1262304000,
    "name": "alert example name",
    "target": "/api/v5/servers/1/",
    "target_id": 1,
    "in_incident": true,
    "interval": 5,
    "time_above_threshold": 5,
    "threshold": 90,
    "reg_exp": "",
    "direction": "above",
    "trigger": "CPU below 90% for 1 min",
    "trigger_type": "CPU",
    "target": "default_collector",
    "active": false,
    "part_name": "",
    "ip_details": "",
    "type": "Server",
    "id": 1,
    "users": '[{"pushnotification": true, "sendsms": true, "id": 1, "sendemail": false}]',
    "subscribers": [
        {
            "url":"http://example.com/callback/",
            "auth":"dXNlcm5hbWU6cGFzc3dvcmQ=",
            "type":"post",
            "event":"TRIGGERED"
        },
        {
            "url":"https://other.example.com/notify/",
            "type":"get",
            "event":"BOTH"
        }
    ],
    "window_length": 0,
    "window_units": "h",
    "band_value": 0,
    "url": "/api/v5/alerts/1/",
}

DELETE

Delete an alert.

Example

curl --user {EMAIL}:{API_KEY} -X DELETE https://wwws.appfirst.com/api/alerts/1/