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

API Access

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

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

The generated Alerts & Rules 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’. You should also add to the header Content-Type as application/json.

  1. Authorization: bearer YOUR_API_KEY
  2. Content-Type: application/json

“POST” Create New Alert

Body parameters

ParameterDescriptionTypeNote
nameAlert namestring
severityAlert severitystringmust be one of the following options: [“info”, “warning”, “critical”]
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.textThe query_string query that we wanted to be notified on. can be in an “advanced” format for more accurate results.string(case sensitive)
log_filter.categoryAn array that contains log’s categories that we want to be notified onarray
log_filter.filter_typeType of the log filter stringmust be one of the following options: [“text”, “ratio”]
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.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.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 alertobject or string with null value that represents 'immediate' alertEach property of that object is described below
condition.condition_typeType of the conditionstringmust be one of the following options: [‘less_than’, ‘more_than’, ‘more_than_usual’]
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’]
condition.group_byThe field to 'group by' onstringthe name of the key, if nested than specify full path
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",
  "is_active": true,
  "log_filter": {
    "text": "authentication failed",
    "category": null,
    "filter_type": "text",
    "severity": ["error", "critical"],
    "application_name": [
      "production"
    ],
    "subsystem_name": [
      "my-app",
      "my-service"
    ],
    "computer_name": null,
    "class_name": null,
    "ip_address": null,
    "method_name": null
  },
  "condition": {
    "condition_type": "more_than",
    "threshold": 100,
    "timeframe": "10MIN",
    "group_by": "host"
  },
  "notifications": {
    "emails": [
      security@mycompany.com,
      mgmt@mycompany.com
    ],
    "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 Forbidden201 Created
{
  "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. Note, if you are updating an alert and you set 'condition.group_by' to be empty string or null, it will update the alert and remove the 'group by' field if exists.

Example:

This is an example payload for updating an alert via 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

201 Ok
{
  "status": "success",
  "message": "Alert updated successfully"
}
400 Bad Request
{
  "status": "invalid alert",
  "message": "Non valid value was received for field",
  "errors": [
    "err_reason1",
    "err_reason2"
  ]
}
404 Not Found
{
  "status": "alert not found",
  "message": "Failed to update alert"
}

“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"
}
400 Bad Request
{
  "status": "invalid id",
  "message": "Non valid value was received for field",
  "errors": [
    "invalid_id_err_msg"
  ]
}
404 Not Found
{
  "status": "alert not found",
  "message": "Failed to delete alert"
}

“GET”, Query your Alerts

Query parameters

ParameterDescriptionTypeNote
applicationNameWill check if it contained in the alert’s log_filter.application_name arraystring(case sensitive)
subsystemNameWill 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”]
fromTimestampQuery all alerts that have been created from a specific timestamp until nowstring - ISO format

"2020-06-07T17:30:00.000Z"

** Note – You should pass the query parameters for ‘GET’ request through its URL in the following manner:

https://api.coralogix.com/api/v1/external/alerts?severity=warning&applicationName=metro-prod&subsystemName=metro-web&fromTimestamp=2020-06-07T17:30:00.000Z

This URL will get in response all the alerts with ‘warning’ severity (alert level not log level), application metro-prod, subsystem metro-web, and were created after 17:30 on June 7th. The fromTimestamp should be a string in ISO format, you don’t have to specify the hour, date like &fromTimestamp=2020-06-07 will suffice to get all alerts that were created since June 7th 2020.

If you use none you will get in response all of your alerts.

Result Format: 

200 Ok
{
  "total": results_count, //number
  "message": [alerts..] //array
}
400 Bad Request
{
  "status": "invalid query param",
  "message": "Non valid value was received for field",
  "errors": [ 
    "err_reason1", 
    "err_reason2" 
  ]
}

Export all alerts to a new Coralogix team

In case you opened a new Coralogix team and you want to import all of your alerts from another team, first GET all the alerts from the first Coralogix team. In response, you will receive a JSON that includes all of your alerts. Copy it. Second, you will need to create a POST request (don’t forget to also change the API key to a key you generated from the new Coralogix team you opened) and paste the response from the former action as your POST request body. You will also need to change the URL for the request and add /bulk, e.g. https://api.coralogix.com/api/v1/external/alerts/bulk.

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

Start solving your production issues faster

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

Managed, Scaled and Compliant ELK Stack

No credit card required

Get a personalized demo

Jump on a call with one of our experts and get a live personalized demonstration