Alerts

Alerts enable sending notifications to an arbitrary destination when certain conditions are met. Alerts are based on SQL queries. You can configure an alert to be triggered when a SQL query returns any rows. The alert can be configured to send a notification to multiple destinations using web requests. This way, you can for example notify a Slack channel and open a JIRA ticket at the same time.

CloudQuery Platform alerts are not meant to replace your incident management system and therefore they cannot be acknowledged or managed in any way on the CloudQuery Platform. They are rather meant to feed into your incident management system when your infrastructure does not comply with the rules set.

How alerts work

Alerts are a feature of SQL queries meaning a SQL query can be configured to trigger an alert with a certain severity, a message, and a set of notification destinations that are going to be informed when the alert is triggered.

SQL queries that are configured to trigger an alert are evaluated after every sync. If a query returns any rows, the alert is considered to be triggered and the configured destinations are sent a notification.

The alert is triggered only once when the non-zero row count is returned from the query. For the alert to trigger again, the query has to be evaluated to return 0 rows at least once.

Configuring an Alert

Navigate to the SQL Console and write a SQL query, or load a saved query. For example, you might want to get a notification when there are unattached EBS volumes:

SELECT *
FROM aws_ec2_ebs_volumes
WHERE attachments='[]';

Click the Configure Alert button to open the alert configuration.

Specify the Query title. This will be used as the alert message. You will be able to change this and configure additional alert properties later.

If you have not added any notification destinations, click the Add notification destination button. Otherwise select the destinations you want to notify when the alert is triggered.

Click the Save alert button to save this alert configuration.

Configuring Notification Destinations

Notification Destination is a configuration of web request to an HTTP(s) endpoint. Each notification destination has a name, URL, web request body, and optional headers. When an alert is triggered and has a notification destination set, CloudQuery Platform sends an HTTP POST request to the configured URL.

You can add a new alert notification destination either when configuring a new alert, or from the Organization Settings - Notification Destinations page. To add a new destination, click the Add notification destination button.

The following properties can be configured:

Destination name: The name displayed in the list of notification destinations when configuring an alert.

Destination URL: The URL to which the web request will be sent.

Web request body: The body of the POST request sent to the URL. The following placeholders can be used in the body to be replaced by a content from the triggering alert:

{{query_name}} - the name of the query on which the alert is configured.

{{query_url}} - the URL on CloudQuery platform to open to run the query directly and see the results.

{{alert_status}} - the state of the alert. The possible values are triggered and inactive.

{{alert_severity}} - the severity of the alert.

{{alert_message}} - the extra message configured for the alert.

{{alert_violations}} - the count of rows the query returned.

HTTP Headers: Optional HTTP headers to be included in the web request.

You can test sending the notification (the placeholders will not be replaced in this case) using the Send test notification button. Click the Save notification destination to confirm the changes.

Editing a Saved Alert and Managing Alert Queries

To edit a saved alert and see what queries are configured with alerts, navigate to the SQL Console and click the Manage queries button in the top right corner. Switch to the Saved queries with alerts to see the SQL queries configured with an Alert.

Use the dropdown menu on the right to edit the alert. You can change the alert message, severity, and the destinations in the popup. You can also disable the alert so the query isn't evaluated.

Troubleshooting

Here are some common issues you may encounter when setting up and using Alerts.

Notifications are not being sent

Alerts don't send new notifications when they are already triggered. The need to be reset to the 'inactive' state first. Use SQL Console to check the alert query if it is returning any rows. If it is, you may need to fix or update the query to not return any rows and then run a sync (any sync with any integration will do, the alerts are evaluated after each sync).

Try adding a new notification destination to Webhook.site and add this destination to the alert configuration. If you receive an alert notification to this site but not to your destination, the problem may be on the receiving end.

Sometimes it may take a while for data to be processed after a sync. Allow up to 10 minutes after a sync for the alert to be evaluated and the notifications to be sent.

A destination cannot parse the request body

Make sure you add the Content-Type header with the right value. By default, it should be application/json, but you may need to change it if your notification destination requires a different content type.