TUTORIALS

Alerts API

This guide will help you use our alerts API to define, query, and manage your alerts. 


API URL:

https://api.coralogix.com/api/v1/external/alerts


Authentication


API Access


In Settings –> Account, Choose ‘Alerts API Access’ option and generate new API key:

Coralogix API access key

** Note that only admin users have access to the API, So the option above will be visible only to admin users.

The generated API key must be added to the header of each HTTP request to the API, you’ll need to configure it as a ‘Bearer Token’:

  1. GET /api/v1/external/alerts HTTP/1.1
  2. Host: api.coralogix.com
  3. Content-Type: application/json
  4. Authorization: Bearer e4fbfd27-9618-4ecc-bc08-ddf3e9e792f5
  5. Cache-Control: no-cache

“POST” Create New Alert


Body parameters

ParameterDescriptionTypeNote
nameAlert namestring
severityAlert severitystringmust be one of the following options: [“info”, “warning”, “critical”]
expirationAlert expiration datestringMust be a date string in the format: “YYYY-MM-DD”
is_activeA boolean that determines whether the alert is active or notboolean
log_filterAn object that represents the filter definition of the alertobjectEach property of that object is described below
log_filter.filter_typeType of the log filter stringmust be one of the following options: [“text”, “template”]
log_filter.severityAn array of log severities that we interested inarrayMust be chosen from the following options: [“debug”, “verbose”, “info“, “warning”, “error“, critical”]
log_filter.textThe log text that we wanted to be notified on. can be in an “advanced” format for more accurate results.string(case sensitive)required when choosing log_filter.filter_type as “template”
log_filter.application_nameAn array that contains log’s application names that we want to be alerted onarray
log_filter.subsystem_nameAn array that contains log’s subsystem names that we want to be notified onarray
log_filter.computer_nameAn array that contains log’s computer names that we want to be notified onarray
log_filter.categoryAn array that contains log’s categories that we want to be notified onarray
log_filter.class_nameAn array that contains log’s class names that we want to be notified onarray
log_filter.ip_addressAn array that contains log’s IP addresses that we want to be notified onarray
log_filter.method_nameAn array that contains log’s method names that we want to be notified onarray
conditionAn object that specifies a condition for triggering the alertobjectEach property of that object is described below
condition.condition_typeType of the conditionstringmust be one of the following options: [‘less_than’, ‘more_than’, ‘immediate’]
condition.thresholdThe number of log occurrences that is needed to trigger the alertnumber
condition.timeframeThe bounded time frame for the threshold to be occurred within, to trigger the alertstringmust be one of the following options: [‘5Min‘, 10Min’, ‘20Min’, ‘30Min’, ‘1H’, ‘2H’, ‘3H’, ‘4H’, ‘6H’, ‘12H’, ‘24H’]
notificationsAn object that specifies which notifications channels to use when an alert was triggeredobjectEach property of that object is described below
notifications.emailsAn array of email address to notify when the alert was triggeredarray
notifications.integrationsAn array of integration channels to notify when the alert was triggeredarrayEach item in the array is the alias name of the integration

Example

/*

This is an example payload for alert creation via the API.
The response of that request returns an alert_id.

  You can save this id in case you want to update the alert later on.

*/

{

   “name”: “Security Alert”,

   “severity”: “info”,

   “expiration”: “2019-01-01”,

   “log_filter”: {

        “filter_type”: “text”,

        “severity”: [“error”, “critical”],

        “text”: “authentication failed”,

        “application_name”: [“production”],

        “subsystem_name”: [“my-app”, “my-service”],

   },

   “condition”: {

      “condition_type”: “more_than”,

        “threshold”: 100,

        “timeframe”: “10Min”

   },

   “notifications”: {

      “emails”: [[email protected], [email protected]],

        “integrations”: [“security-slack”, “security-pagerduty”]

   }

}


Result Format

 201 Created:

{

  “status”: “success”,

  “message”: “Alert created successfully”,

  “alert_id”: “uuid”

}

 400 Bad Request:

{

  “status”: “invalid alert”,

  “message”: “Non valid value was received for field”,

  “errors”: [“err_reason1”, “err_reason2”]

}

 403 Forbidden:

{

  “status”: “alerts limit exceeded”,

  “message”: “Company was reached the maximum alerts it can produce”,

  “limit”: “company’s alerts limit” //Usually it’s 500

}

“PUT”, Update Alert


Body parameters

ParameterDescriptionTypeNote
idThe UUID that identifies the alert on the systemstring
Alerts fieldsYou can add to the request every field that you want to update.
See the body params of the POST request above

Example:

/*

  This is an example payload for updating an alert the API.

  In the case below, We just want to update the name of the alert.

*/

{

   “id”: “2fb2fbd5-ab07-4315-bbd7-1fb5b4323183“,

   “name”: “New Name!”

}


Result Format

 200 OK:

{

  “status”: “success”,

  “message”: “Alert updated successfully”,

}

 404 Not Found:

{

  “status”: “alert not found”,

  “message”: “Failed to update alert”

}

 400 Bad Request:

{

  “status”: “invalid alert”,

  “message”: “Non valid value was received for field”,

  “errors”: [“err_reason1”, “err_reason2”]

}


“Delete”, Delete Alerts


Body parameters

ParameterDescriptionTypeNote
idThe UUID that identifies the alert on the systemstring

Result Format

 200 OK:

{

  “status”: “success”,

  “message”: “Alert deleted successfully”,

}

 404 Not Found:

{

  “status”: “alert not found”,

  “message”: “Failed to delete alert”

}

 400 Bad Request:

{

  “status”: “invalid id”,

  “message”: “Non valid value was received for field”,

  “errors”: [“invalid_id_err_msg”]

}


“GET”, Query your Alerts


Body parameters

ParameterDescriptionTypeNote
application_nameWill check if it contained in the alert’s log_filter.application_name arraystring(case sensitive)
subsystem_nameWill check if it contained in the alert’s log_filter.subsystem_name arraystring(case sensitive)
severityQuery by alert’s severitystringMust be one of the following options: [“info”, “warning”, “critical”]
from_timestampQuery all alerts that have been created from a specific timestamp until nowtimestamp

Result Format: 

 200 OK:

{

  “total”: results_count, //number

  “alerts”: […alerts],  //array

}

 400 Bad Request:

{

  “status”: “invalid query param”,

  “message”: “Non valid value was received for field”,

  “errors”: [“err_reason1”, “err_reason2”]

} 


Appendix


 How to run a complex query inside the log_filter.text field


Run a complex query, use / before and after your text.

    • To perform a free text search, simply enter a text string. For example, if you are searching your web server logs, enter safari to define an alert on all fields for the term safari (without/around the alert text).
    • To define an alert on a value in a specific field, prefix the value with the name of the field. For example, enter /environment:production/ to define an alert on all the entries that contain the value production in the environment field.
    • To define an alert on a range of numeric values, use the bracketed range syntax [START_VALUE TO END_VALUE]. For example, to define an alert on entries that have 4xx status codes, enter /status.numeric:[400 TO 499]/.
    • To specify more complex alert criteria, use the Boolean operators AND, OR, and NOT. For example, to define an alert on entries that have 4xx status codes and have an extension of PHP, enter /status.numeric:[400 TO 499] AND extension:php/.
  • To define an alert when a regular expression matches a value, wrap your regex with ‘/’ and use it as the expression for the field. For example, to define an alert the regions west-europe-1, west-europe-2, west-us-1, west-us-2, west-us-3 etc., enter /region:/west-(europe|us)-[0-9]+//.

Example: define an alert on logs from your production with status codes 5xx not originating from west-europe or west-us, use this expression:

/environment:production AND status.numeric:[500 TO 599] NOT region:/west-(europe|us)-[0-9]+//

Let's talk about how Coralogix can help you better understand your logs