Since we released the Alerting Public Preview in December, we’ve seen a fantastic amount of active usage of the feature – and some complex querying to go with it! It’s been great working with all of you and gathering feedback on what’s been working well, and what needs improvement.
We’ve also gotten great help from our community. Here are some really useful articles from some of our MVPs and partners:
- Cameron Fuller’s article on setting up Heartbeat alerts: http://blogs.catapultsystems.com/cfuller/archive/2016/01/29/approaches-available-to-provide-heartbeat-alerts-in-oms/
- Tao Yang’s overview of OMS Alerts: http://blog.tyang.org/2015/12/03/oms-alerting-walkthrough/
- Rich Lilly’s article on using OMS Alerts to track environment configuration changes: http://www.acloudabove.com/2016/02/26/using-oms-log-analytics-alert-unplanned-software-changes/
Currently, we are in the midst of acting on all that great feedback. Over the next few weeks, you’ll be seeing a steady rollout of new capabilities– starting today with WebHook support for OMS Alerts.
What’s a WebHook?
A WebHook is just an HTTP callback URL. When an Alert fires, you can choose to send the alert to a URL of your choosing. Many services create unique URL’s to talk to a specific part of the product – like a Slack channel or an incident management table. In the same way that a REST API became a standard way for you to talk to applications, a WebHook is becoming the standard way for applications to talk to you when an event occurs.
Why do I want to use WebHooks with OMS?
Using WebHooks allows you to do things like send a message to Slack, raise an incident in an ITSM tool or integrate with your own custom tool. In short, you want to use WebHooks with OMS because it’s going to make integrating into your existing workflow really easy– no code required! I’ll run you through the basics of how to use WebHooks, as well as an example of sending the details of the alert to a Slack channel.
To use a WebHook, you need to provide one mandatory field (Webhook URL) and one optional field (custom JSON payload):
- Webhook URL: This is the destination URL you want called when the alert fires (i.e. a Slack channel). Many services supply WebHooks in different ways. In many cases, even if a service doesn’t support WebHooks directly, you can still use their public API – just provide any authentication or other required fields in the custom JSON payload below.
- Custom JSON Payload: This optional field lets you add more data when we send the alert to your destination. Sometimes you will need to use this field to include authentication tokens, incident IDs, etc. Just use JSON formatted text.
OK, I’m totally sold on WebHooks. Can you show me how to send a message to Slack?
In this example, I’m going to alert when I have too many event log errors in my environment. So I’ll execute the following query:
Type=Event EventLevelName=error
1. Configure your alert
If you haven’t already, enable the Alerting preview by navigating to Settings -> Preview Features.
I’m not going to go through all the details of how to set up an alert – for that, you can check out my post from December here– but here’s my configuration:
- Check for this alert every 5 minutes
- When the number of results is greater than 100
- Over a 60 minute time window
2. Copy the WebHook URL from Slack
Each service is going to have their own method of generating a WebHook. I’ll show you where to find it in Slack. This is all assuming you already have a Slack account.
Start by clicking the drop down for the channel you want to send a message to.
In the App Directory, search for WebHooks and select “Incoming WebHooks”
Select “Install” next to your team name (because I’ve already set this up, my screen says “Configure”). Select “Add Configuration”, choose the channel you’d like to send the message to and click “Add incoming WebHooks integration”. Copy this WebHook URL, which we will paste into our Alert configuration.
3. Add the WebHook URL to the OMS alert
Simply paste this URL into the “WebHook URL” field in the alert creation pane.
4. Add a custom JSON payload to match what Slack is expecting
Here’s where WebHook support gets really powerful – we are going to add some JSON formatted data to be sent with the alert. These fields are going to match what Slack is expecting. Here’s a really simple example of what you can add to this payload to send a simple message to Slack:
{
“text”:”#alertrulename fired with #searchresultcount results exceeding the threshold of #thresholdvalue”
}
Now just add this to the Custom JSON payload box and click “Save”.
Here’s what this would look like in Slack:
You’ll notice we use the ‘#’ symbol to add properties of the alert like the “name”, “threshold” and “result count” to the message being sent. You can view the full list of ‘#’ parameters here in our documentation.
Slack allows for lots of customization of this payload. You can read all about it here. This is the payload we’ve been using within our dev team:
{
“attachments”: [
{
“title”:”OMS Alerts Custom Payload”,
“fields”: [
{
“title”: “Alert Rule Name”,
“value”: “#alertrulename”
},
{
“title”: “Link To SearchResults”,
“value”: “<#linktosearchresults|OMS Search Results>”
},
{
“title”: “Search Interval”,
“value”: “#searchinterval”
},
{
“title”: “Threshold Operator”,
“value”: “#thresholdoperator”
},
{
“title”: “Threshold Value”,
“value”: “#thresholdvalue”
}
],
“color”: “#F35A00″
}
]
}
Which corresponds to this message in Slack:
That was super detailed and helpful. Where else can I use WebHooks?
Pretty much anywhere! Some services will explicitly support WebHooks in a variety of ways, but even if your product doesn’t have WebHook support, in many cases you can just leverage that products API. Typically, that just means including some important parameters in your custom JSON payload field.
With WebHook support for OMS, we are laying the foundation of using OMS as a platform that can easily be integrated into your existing workflow. We will continue to add functionality to WebHooks, as we see this as a key tool for powerful integration scenarios – both into and out of OMS.
As always, let us know what you think in the comments here, or feel free to email me directly at alfran@microsoft.com. We’re looking forward to seeing what you can do!