You can set up alerts which will trigger on a variety of signals, based on the conditions you define.
The alert's title, how it will appear in emails, webhook notifications, and in the alerts view.
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).
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.
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.
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).
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.
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.
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 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
).
The measure is what the condition applies to.
The condition body contains an operator (>
or <
), a value, and possibly another field, based on whether the comparison field is populated or not.
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.
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 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 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.
Fig. 3 General setup view
This section allows you to fine-tune the alert's behavior and appearance.
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.
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.
Fig. 6 General view
Fig. 7 Alert setup view
Fig. 8 Delivery view
Fig. 9 Access view
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:
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.
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:
localhost
)