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’:

alerts api https


“POST” Create New Alert


Parameters

Body Params

name:

required

string

Alert name

severity:

required

string

Alert severity. must be one of the following options:

[“info”, “warning”, “critical”].

expiration:

 

string

Alert expiration date.

Must be a date string in the format: “YYYY-MM-DD” 

is_active:

 

Boolean

A boolean that determines whether the alert is active or not.

log_filter:

 

Object

An object that represents the filter definition of the alert.

Each property of that object is described below.

log_filter.filter_type:

 

String

The type of the log filter must be one of the following options:

[“text”, “template”].

log_filter.severity:

 

Array<string>

An array of log severities that we interested in,

Must be chosen from the following options:

[“debug”, “verbose”, “info“, “warning”, “error“, critical”].

log_filter.text:

required when using “template” filter type 

String(case sensitive)

The log text that we wanted to be notified on.

The text also can be in an “advanced” format for more accurate results. See this guide for more information.

log_filter.application_name:

 

Array<string(case sensitive)>

An array that contains log’s application names that we want to be alerted on.

log_filter.subsystem_name:

Array<string(case sensitive)>

An array that contains log’s subsystem names that we want to be notified on.

log_filter.computer_name:

Array<string(case sensitive)>

An array that contains log’s computer names that we want to be notified on.

log_filter.category:

array<string(case sensitive)>

An array that contains log’s categories that we want to be

notified on.

 

log_filter.class_name:

 

Array<string(case sensitive)>

An array that contains log’s class names that we want

to be notified on.

 

log_filter.ip_address:

 

Array<string(case sensitive)>

An array that contains log’s IP addresses that we want

to be notified on.

log_filter.method_name:

Array<string(case sensitive)>

An array that contains log’s method names that we want to be notified on

 condition: Object

An object that specifies a condition for triggering the alert.

Each property of that object is described below.

condition.condition_type:

String

The type of the condition must be one of the following options:

[‘less_than’, ‘more_than’, ‘immediate’]

 

condition.threshold:

 

Number

The number of log occurrences that is needed to trigger the alert.

 

condition.timeframe:

 

String

The bounded time frame for the threshold to be occurred within, to trigger the alert. must be one of the following options:

[‘5Min‘, 10Min’, ‘20Min’, ‘30Min’, ‘1H’, ‘2H’, ‘3H’, ‘4H’, ‘6H’, ‘12H’, ‘24H’]

 notifications:

Object

An object that specifies which notifications channels to use when

an alert was triggered.

Each property of that object is described below.

 

notifications.emails:

 

Array<string>

An array of email address to notify when the alert was triggered.

 notifications.integrations: Array<string(case sensitive)>

An array of integration channels to notify when the alert was triggered.

Each 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


Parameters

Body Params

id:

required

string

The UUID that identifies the alert on the system.

Alerts fields:

 

You 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


Parameters

Body Params

id:

required 

String

The UUID that identifies the alert on the system.


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


Parameters

Query Params

application_name:

 

string(case sensitive)

Will check if it contained in the alert’s log_filter.application_name array.

subsystem_name:

 

string(case sensitive)

Will check if it contained in the alert’s log_filter.subsystem_name

array.

severity:

 

string

Query by alert’s severity. Must be one of the following options:

[“info”, “warning”, “critical”].

from_timestamp:

timestamp

Query all alerts that have been created from a specific timestamp until now.


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”]

} 


Appendics


 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]+//

 Signup to Coralogix

WordPress Lightbox