Alerts
You can set up alerts which will trigger on a variety of signals, based on the conditions you define.
What is an alert
Fields and properties
Name
The alert's title, how it will appear in emails, webhook notifications, and in the alerts view.
Severity
The severity can be any of the following: success
, info
, error
, or warning
. It will affect the way the alert is displayed (its colors and icon, namely).
Data cube
The data cube this alert should read from. This is automatically populated if you create an alert from the data cube view, otherwise it defaults to the first available data cube.
Check every
This controls the frequency at which this alert will be evaluated. Setting it to one hour, for instance, will make the alerts daemon check the alert against its data cube every hour.
Time frame
The time frame is the window that the alert will evaluate against. Setting it to one day will make the alerts daemon gather data for the last day (at the moment the alert is evaluated) and check the alert against it. It usually makes sense for the time frame to be equal to or greater than the evaluation frequency (Check every
field), which is what the UI will try to do (changing the evaluation frequency might affect the time frame input, however you're free to set it back to a value of your choice).
Filters
When the alerts daemon gathers data for an alert to be evaluated, it can filter it (exactly like you can filter data when exploring the data cube view). This is where you can can define such filters. You can't define a time filter because an alert is always evaluated on a dynamic time frame.
Look at
The alert's type allows you to evaluate either top level measures (all the additions on the Wikipedia data cube, for example), or individual values on a split (additions in various languages on the Wikipedia data cube, for example). When picking dimension values
for this field, you'll get a chance to specify what dimension you want to evaluate, and its sorting criteria.
Comparison
You can either set an alert to trigger based on an absolute condition (when a certain measure reaches a certain value, for example) or based on a relative condition (when a measure grows by more than a certain delta, for example). This can be achieved by first specifying a comparison period.
Conditions
Conditions are what the alerts daemon uses to determine whether an alert will trigger or not. There can be one or more conditions, and in the latter case, you can choose between looking to all the conditions to be true, or at least one (All conditions
vs. Any condition
).
Measure
The measure is what the condition applies to.
Condition body
The condition body contains an operator (>
or <
), a value, and possibly another field, based on whether the comparison field is populated or not.
Access
Recipients
The recipients field contains a list of users and/or roles who will have read access to this alert, i.e., who will see the alerts and possibly receive emails (based on the email configuration) but who won't be able to modify it.
The emails are not sent to roles, only to users.
Admins
The admins field contains a list of users and/or roles who will have a write access to this alert. This means that they will see the alert and its feed (although they won't receive any emails if they're not also in the recipients) and will be able to edit the alert.
If checked, the alerts daemon will send an email to the users in the recipients
field each time the alert triggers.
Webhooks
Webhooks are a way to integrate alerts with another service. Alerts have built-in support for both Slack and custom webhooks. For Slack webhooks, the payload is predefined, and all that is needed is a webhook URL (see Generating a Slack webhook URL). For custom webhooks, you can customize what is sent and how it is sent to the service you want to connect to your alert configuration.
Creating an alert
Creating an alert can either be initiated from the data cube view:
Fig. 1 Creating an alert from the data cube view
or from the alerts view:
Fig. 2 Creating an alert from the alerts view
When creating an alert from the data cube view, the alert will be pre-filled based on the current view you were on (timeframe, splits and measures will have an impact on the alert), although you'll be able to modify everything before actually creating the alert.
General setup
Fig. 3 General setup view
This section allows you to fine-tune the alert's behavior and appearance.
Delivery options
Depending on your Pivot configuration, this view may not be available. If you are running Pivot in userless (
default-user
) mode, and don't support either email or webhooks, this view will be hidden, and you will directly create the alert once you're done with the general setup.
Fig. 4 Delivery options view
This section allows you to define the outputs of an alert, that is, the ways an alert occurrence will surface to you or your users: emails and webhooks. It also contains a list of recipients and administrators for this alert.
Editing an alert
You can edit an Alert configuration by clicking on the ellipsis button for an alert in the alerts view:
Fig. 5 Alerts view
Alternatively, you can click on an alert (which will take you to the alert's feed) and then edit the alert from there.
General
Fig. 6 General view
Alert setup
Fig. 7 Alert setup view
Delivery
Fig. 8 Delivery view
Access
Fig. 9 Access view
Generating a Slack webhook URL
Alerts support sending info to a Slack webhook. You can generate a webhook URL by following steps 1 to 3 of this tutorial, and then pasting the URL into a new webhook as shown below:
Fig. 10 New webhook form
You can also define a webhook as custom
and customize its payload, i.e., what will be sent to the service targeted by the URL. This payload contains a variety of keys that will be interpolated as follows:
- title (the alert's title as defined in its configuration)
- summary (a brief summary of what triggered the alert)
- link (a relative link to the event that triggered the alert, relative to the Pivot installation)
- triggerDate (the timestamp — in seconds)
- color (the color related to the alert's type — blue for info, green for success, red for error and yellow for warning)
- severity (the alert's type as defined in its configuration)
- footer (the alert's sender, either Imply or the user who sent the test notification)
For reference, here's what the default Slack payload looks like:
{
"attachments": [
{
"fallback": "<title>",
"color": "<color>",
"title": "<title>",
"title_link": "<link>",
"text": "<summary>",
"ts": <triggerDate>
}
]
}
A user need the
ManageAlertsWebhooks
permission to modify an alert's webhooks.
Configuring emails
When triggered, an alert can send an email to its recipients if Pivot is configured to send emails.
To specify a custom alert email template, provide an entry in the emailTemplates
block with name alert
.
emailTemplates:
- name: 'alert'
subject: '${title} has triggered'
html: |
<h2>Oh my look, an alert: ${title}</h2>
<p>
${summary}
</p>
<p>
Learn more: http://localhost:9095${link}
</p>
In this template, certain strings will be interpolated with the following keys:
- title (the alert's title, as defined in its configuration)
- summary (a brief summary of what triggered the alert)
- link (a relative link to the event that triggered the alert, relative to the installation — here it's just
localhost
)