In Data Flow, under Integrations, Choose ‘API Keys’ option and generate new API key under Alerts, Rules and Tags 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.
Authorization: bearer YOUR_API_KEY
Content-Type: application/json
“POST” Create New Alert
Body parameters
Parameter
Description
Type
Note
name
Alert name
string
severity
Alert severity
string
must be one of the following options: [“info”, “warning”, “critical”]
is_active
A boolean that determines whether the alert is active or not
boolean
log_filter
An object that represents the filter definition of the alert
object
Each property of that object is described below
log_filter.text
The 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.category
An array that contains log’s categories that we want to be notified on
array
log_filter.filter_type
Type of the log filter
string
must be one of the following options: ["text", "ratio", "unique_count", "relative_time", "metric"]
For 'new_value' alerts the value should be "text"
log_filter.severity
An array of log severities that we interested in
array
Must be chosen from the following options: [“debug”, “verbose”, “info“, “warning”, “error“, critical”]
log_filter.application_name
An array of strings that includes the different matches for application names filters
array
There are 4 types of matching criteria: 'Is', 'Start With', 'Includes', 'Ends With'
E.g.
log_filter.application_name: ["production", "filter:startsWith:prod", "filter:contains:duct", "filter:endsWith:ion"]
log_filter.subsystem_name
An array of strings that includes the different matches for subsystem names filters
array
There are 4 types of matching criteria: 'Is', 'Start With', 'Includes', 'Ends With'
E.g.
log_filter.subsystem_name: ["my-nice-app", "filter:startsWith:my", "filter:contains:nice", "filter:endsWith:app"]
log_filter.computer_name
An array that contains log’s computer names that we want to be notified on
array
log_filter.class_name
An array that contains log’s class names that we want to be notified on
array
log_filter.ip_address
An array that contains log’s IP addresses that we want to be notified on
array
log_filter.method_name
An array that contains log’s method names that we want to be notified on
array
log_filter.alias
A string of text for Query 1 alias. Relevant to ratio alerts only
string
log_filter.ratioAlerts
An array containing an object representing Query 2 for ratio alerts
array
Keys supported in Query2 object are:
- application_name
- subsystem_name
- severity
- text
- alias
-group_by - array of strings with group by fields. If the root alert has defined `group_by` it has to be the same or empty. If root alert doesn't have `group_by` you can choose specific `group_by` for `Query 2`.
The description of the keys is same as above
condition
An object that specifies a condition for triggering the alert
object or string with null value that represents 'immediate' alert
Each property of that object is described below
condition.condition_type
Type of the condition
string
must be one of the following options: [‘less_than’, ‘more_than’, ‘more_than_usual’, ‘new_value’]
For 'unique_count' alerts, the value should be "more_than"
For 'metric' alerts, the value can be one of [‘less_than’, ‘more_than’]
condition.unique_count_key
Unique count key name
string
Select from list of keys.
condition.threshold
The number of log occurrences that is needed to trigger the alert
number
condition.timeframe
The bounded time frame for the threshold to be occurred within, to trigger the alert
string
must be one of the following options: [‘5Min‘, 10Min’, ‘20Min’, ‘30Min’, ‘1H’, ‘2H’, ‘3H’, ‘4H’, ‘6H’, ‘12H’, ‘24H’]
For 'new_value' alerts you should send one of the following options:
[‘12H’, ‘24H’, ‘48H’, ‘72H’, ‘1W’, ‘1M’, ‘2M’, ‘3M’]
For 'relative_time' alerts you should send one of the following options:
['HOUR', 'DAY']
condition.relative_timeframe
timeframe to compare with (relevant on with 'Time Relative Alers'
string
string must be one of the following options: ['HOUR', 'DAY', 'WEEK', 'MONTH']
condition.group_by
The field to 'group by' on
string or array
The name of the key, if nested then specify the full path.
Relevant only for: 'more than', 'more than usual', 'new value', 'unique count', and 'metric' alerts.
Using an array for the group_by property will aggregate by multiple labels.
For 'new_value' alerts it must contain a value
condition.group_by_lvl2
The subsequent field to 'group by' on
string
The name of the key, if nested then specify the full path.
Relevant only for: 'more than' alert.
condition.metric_field
The name of the metric field to alert on
string
Required for Metric alert type only
condition. metric_source
The source of the metric. Either 'logs2metrics' or 'prometheus'
string
Required for Metric alert type only
condition. arithmetic_operator
0 - avg, 1 - min, 2 - max, 3 - sum, 4 - count, 5 - percentile (for percentile you need to supply the requested percentile in arithmetic_operator_modifier)
number
Required for Metric alert type only
condition. arithmetic_operator_modifier
for percentile(5) arithmetic_operator you need to supply the value in this property
number
Required for Metric alert type only
condition. sample_threshold_percentage
The metric value must cross the threshold within this percentage of the timeframe (sum and count arithmetic operators do not use this parameter since they aggregate over the entire requested timeframe), increments of 10, 0<=value<=90
number
Required for Metric alert type only
condition. non_null_percentage
the minimum percentage of the timeframe that should have values for this alert to trigger. increments of 10, 0<=value<=100
number
Required for Metric alert type only
condition. swap_null_values
If set to true, missing data will be considered as 0, otherwise, it will not be considered at all
boolean
Required for Metric alert type only
notifications
An object that specifies which notifications channels to use when an alert was triggered
object
Each property of that object is described below
notifications.emails
An array of email address to notify when the alert was triggered
array
notifications.integrations
An array of integration channels to notify when the alert was triggered
array
Each item in the array is the alias name of the integration
notify_every
the supress time for the Alert
number (in seconds)
By default, when creating an Alert through the UI or with the API, notify_every will be populated with 60(sec) for immediate, more and more than alerts. For less than alert it will be populated with the chosen time frame for the less condition (in seconds).
You may choose to change the suppress window so the alert will be suppressed for a longer period.
description
alert description
string
notif_payload_filter
An array that contains log fields out of the log example that we want to be included with the alert notification
array
meta_labels
An array can contain objects with structure {“key”: “MY_KEY”, “value”: “MY_VALUE”}, or ‘:’ delimited strings with pattern “MY_KEY:MY_VALUE”.
array
‘key’ must be only letters or digits, but can include ‘_’, or ‘-’. both ‘key’ and ’value must be no longer than 255
log_filter.tracing.fieldFilters
An array that contain filter for Application, Subsystem, serviceName
array
log_filter.tracing.fieldFilters:[{"field":"field*"},"filters":["fields":["value1","value2",…],"operator":"operator*"]]
options for "field" (meta fields):
"field":applicationName", "subsystemName","serviceName"
Options for "Operator" field: "operator":"equal","startsWith","contain","endsWith"
log_filter.tracing.tagFilters
An array that contains filters for tags
array
log_filter.tracing.tagFilters:[{"field":"tag to monitor"},"filters":["fields":["value1","value2",…],"operator":"operator*"]]
Options for "Operator" field: "operator":"equal","startsWith","contain","endsWith"
log_filter.tracing.conditionLatency
Numeric value for latency (will monitor value above the parameter set)
numeric
log_filter.tracing.conditionLatency
cleanup_deadman_duration
This parameter sets a value for Advanced "Auto retire values" parameter
string or null
This is an optional parameter only relevant for Standard Alerts with the condition Less-than with GroupBy
The value should be one of the following:
[null, '5min', '10min', '1h', '2h', '6h', '12h', '24h']
Create alert scenario:
When omitted from the alert payload, the value defaults to null (Auto retire is disabled)
Update alert scenario:
When omitted from the alert payload, the previous value of this parameter will be retained
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.
201 Created
{
"status": "success",
"message": "Alert created successfully",
"alert_id": [
"261e2741-8437-4397-926f-02d7390622a7"
],
"unique_identifier": [
"ba4c6eae-c3d9-4bb3-a670-faf35a488413"
]
}
Note: As you can see two IDs are created:
alert_id is the ID for tracking exactly that alert with all those parameters
unique_identifier is the ID for tracking that alert even if later any parameters will be changed
The difference will be explained with the example in the PUT part. Both can be used with PUT and DELETE requests.
400 Bad Request
{
"status": "invalid alert",
"message": "Non valid value was received for field",
"errors": [
"err_reason1",
"err_reason2"
]
"warnings": []
}
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
Parameter
Description
Type
Note
id
The UUID that identifies the alert on the system
string
Mandatory if there is not the "unique_identifier" field
unique_identifier
An alert unique identifier
string
Mandatory if there is not the "id" field
Alerts fields
You 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.
Note: If you are updating one of the following fields, a new Alert is created behind the scene and the id of the alert thus changes. You should consider that when performing updates for your alerts via the API as the id is mandatory in PUT requests. You can also use unique_identifier instead which is not changed during any operation.
400 Bad Request
{
"status": "invalid alert",
"message": "Non valid value was received for field",
"errors": [
"err_reason1",
"err_reason2"
],
"warnings": []
}
404 Not Found
{
"status": "alert not found",
"message": "Failed to update alert"
}
Example 2:
This is an example payload for updating an alert via the API. In the case below, we want to update the condition timeframe for our more than Alert. We updated from 5MIN to half an hour. As described in the prior note, this will generate a new alert and the response will reveal to us the new alert id for future use but the unique_identifier is still the same.
400 Bad Request
{
"status": "invalid alert",
"message": "Non valid value was received for field",
"errors": [
"err_reason1",
"err_reason2"
],
"warnings": []
}
404 Not Found
{
"status": "alert not found",
"message": "Failed to update alert"
}
“Delete”, Delete Alerts
Body parameters
One of those two IDs are required:
Parameter
Description
Type
Note
unique_identifier
An alert unique identifier
string
Mandatory if there is not the "id" field
id
The UUID that identifies the alert on the system
string
Mandatory if there is not the "unique_identifier" field
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": [
"id => \"bb56345b-22be-4570-ba08-3320a8821accc\" is not a valid uuid"
],
"warnings": []
}
404 Not Found
{
"status": "alert not found",
"message": "Failed to delete alert"
}
“GET”, Query your Alerts
Query parameters
Parameter
Description
Type
Note
applicationName
Will check if it contained in the alert’s log_filter.application_name array
string(case sensitive)
subsystemName
Will check if it contained in the alert’s log_filter.subsystem_name array
string(case sensitive)
severity
Query by alert’s severity
string
Must be one of the following options: [“info”, “warning”, “critical”]
fromTimestamp
Query all alerts that have been created from a specific timestamp until now
string - ISO format
"2020-06-07T17:30:00.000Z"
id
Query by alert's id
string
uniqueIdentifier
Query by alert's unique_identifier
string
** Note – You should pass the query parameters for ‘GET’ request through its URL in the following manner:
<Base API Endpoint>?severity=<severity>&applicationName=<application_name>&subsystemName=<subsystem_name>&fromTimestamp=<YYYY-MM-DDThh:mm:ss.000Z
<Base API Endpoint>?id=<id>
<Base API Endpoint>?uniqueIdentifier=<unique_identifier>
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]+//
Oh no!We didn’t find anything for “”,
