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

The filters field is where you define filters for alert data gathered by the alerts daemon during alert evaluation. It works the same way filters do in the data cube view. 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.

Email

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)