Triggers send alerts when your data in Honeycomb crosses the thresholds that you configure. To learn more about guidelines for using Triggers to alert, visit Guidelines for SLOs and Trigger Alerts.
You can create a trigger within the Triggers page or while using the Query Builder.
Select Triggers (
) in the left navigation bar to reach the Triggers page.
From the Triggers page:
Creating a new trigger from the Triggers page will require entering a query during trigger configuration.
From the Query Builder screen:
), located above Run Query, and select Make Trigger.For this example, we want to know whenever our cart has an error that is considered “slow” and to have the results grouped by userid, http.url, and requestID.
To configure the trigger, define the trigger details, trigger alert threshold, and notification preferences in the Define New Trigger page that appears.
Enter identifying information for your Trigger:
| Field | Description |
|---|---|
| Name | (required) Used in notifications about the trigger. Ensure the name describes clearly what has happened. |
| Description | (optional) Used in notifications about the trigger. Recommended use: indicate next steps or include links back to documentation, so alert receiver will know how to respond. |
| Enabled | Determines whether Trigger is active. Toggle to enable [on] or disable [off]. |
After defining your Trigger information, the next Query Run section displays your Trigger Query. A Trigger Query scopes the conditions for your Trigger threshold.
If you created a new Trigger from Query Builder, your Trigger Query automatically populates and the sample graph appears automatically. If you created a new Trigger from the Triggers page, you must enter a Trigger Query before the sample graph appears.
Create a Trigger Query using VISUALIZE, WHERE, GROUP BY, and HAVING clauses.
Use the Run in Query Builder icon (
) to the right of the available clauses to open your Trigger Query in Query Builder in a new tab.
For inspiration on trigger queries, visit our Trigger Examples.
Use a HAVING clause to filter aggregated results in your Trigger Query. This will allow you to define composite alert conditions, and will only notify when all of those unique conditions are met. This is particularly useful when using GROUP BY on high-cardinality attributes where numerous distinct groups can be generated.
Unlike filters that affect the main graph data, HAVING use does not impact the primary visualization in the Trigger Query preview. Instead, a second graph appears that reflects the HAVING filter’s criteria, as seen in the HAVING example below.
After entering your trigger query, a sample graph appears, which displays how the trigger query and the trigger alert components interact. The sample graph displays the trends for your query with the most recent 16 periods as indicated by markers.
By default, the sample graph’s duration and frequency are both 15 minutes. Navigate to Duration and Frequency in the Alerts section to modify these values and your sample graph will adjust accordingly.
In the example below, the sample graph for a 30 minute frequency with a 120 minute duration shows the previous 1920 minutes (or 32 hours).
In the example below, the top graph shows the results of the Trigger Query and the bottom graph shows the results of applying HAVING COUNT_DISTINCT(app.user.id) > 5 to the Trigger Query.
Next, define the conditions for the trigger alert notification.
Configure the type of calculation needed to notify. Select the named tab to choose between:
Your selection determines the display in the Threshold section.
Threshold indicates what trigger condition generates a notification.
Enter your notification conditions, depending on your Trigger Alert Type.
Compose the condition of your Static Threshold. Your trigger will alert when data meets or crosses this threshold.
> (greater than)=> (greater than or equal to)<(less than)<=(less than or equal to)Set the number of times the Threshold, or trigger condition, should be met consecutively before alerting you.
Use Send an alert after the threshold has been met x times to enter this value.
This value defaults to 1 and cannot be greater than 5.
For example, if the number of times a trigger’s threshold has been met is 3 before alerting and the trigger’s frequency is 5 minutes, then this trigger alerts when its threshold has been met for the past 15 minutes, or 3 cycles of 5 minutes.
x times to enter this value.
This value defaults to 1 and cannot be greater than 5. Configure how frequently alerts occur for your trigger. Use the toggle to choose between:
About Triggered Groups: If you have specified fields in the GROUP BY clause of a trigger, then the trigger will notify all recipients when any new group crosses the trigger threshold.
For example, if a trigger is already in a triggered state, and any new group surpasses the trigger threshold, the trigger will again notify all recipients and include the new groups that have triggered the alert.
Use Continuous alerts:
For example, if a trigger has specified fields in its GROUP BY clause, and “Continuous Alerts” is selected, then the trigger will notify all recipients when any new group crosses the trigger threshold, or if any group still exceeds the threshold. If one or more groups resolve, no resolved alert will be sent.
Duration determines what time range of data that the trigger will check. The default Duration value is 15 minutes.
Use the Event History Latency chart to help determine a duration that captures all your events, even if delayed.
To expand the chart display, select the downward arrow icon (
).
This graph describes the maximum and average amount of delay between the timestamp on the event and when it reached Honeycomb.
For example, if the average event latency is 2 minutes, and you want to run your trigger every 5 min, then choose a 7 minute duration to ensure that delayed events are captured by the trigger. Please note that if your traces span a long time frame, you may see high latency in this chart, even though the traces are arriving as soon as they complete.
Frequency determines how often, in minutes, to evaluate for the Threshold, or trigger, condition.
The default Frequency value is 15 minutes. Consider what is normal within your frequency window so notifications only capture conditions worth alerting.
1 to 1440.
Decimal values are truncated to the preceding full minute.
(3.6 becomes 3.) Use Custom Scheduling to specify a scheduled window in which the trigger will run. For example, you only need alerts during business hours from Monday through Friday.
To enable Custom Scheduling:
The trigger will notify all listed recipients when the measured value crosses the configured threshold. No limitation exists for the number of recipients. By default, Honeycomb will send an alert to recipients once, when the trigger crosses the configured threshold or the Triggered state, and then send a resolved alert once the trigger is back in an OK state.
To add a new recipient, select Add Recipient. Use Go to Integration Center to configure additional trigger recipient integration options, like Slack, PagerDuty, Microsoft Teams, and Webhooks.
After selecting Add Recipient, a form will appear with Recipient options in a dropdown list. By default, you can select Notify by Email and enter email recipients. Additional integration options, like Slack, PagerDuty, Microsoft Teams, and Webhooks, can be selected once configured.
Finally, select Create Trigger to save your trigger configuration.
Once saved, the trigger is immediately active and will run at the next frequency interval, such as on the next 5 minute interval for a 5 minute frequency.
You can enable or disable a trigger by editing the trigger and selecting the Enabled toggle.
You can create a Trigger from a template. Trigger Templates are visible in the right sidebar when creating a new Trigger. Selecting a template populates the Name, Description, and Query in the Trigger form.
Trigger Templates reference fields that are set in your Dataset Definitions. If you select a template that references a field mapping that does not exist in your data, a warning message displays above the Trigger Query section that lists the missing Dataset Definition(s), as seen in the example below. To resolve the issue and fully use the Trigger Template, add the missing field and/or update your Dataset Definitions to include the missing Dataset Definition(s).
| Template | Trigger Name | Trigger Description | Dataset Definitions Required |
|---|---|---|---|
| Latency | Latency is too high | This trigger notifies us if the average duration of root spans is higher than 500ms over the last 15 minutes. In the future, consider using P90 or P95 operators to handle outliers more reliably. | Span Duration Parent Span ID |
| HTTP Errors | Too many HTTP request errors | This trigger notifies us if there are any 400 or 500 level HTTP status requests | HTTP Status Code Parent Span ID |
| General Errors | Too many errors | This trigger notifies us if there are errors | Error |