Using the Uptrends API to control monitors

At Uptrends, we try to improve our product as often as possible, including our main web application (some call it a console, others a portal) to give you the best user experience for analyzing your data, and ease of use when tweaking your monitor settings. However, sometimes you want to be able to access your monitoring software without any human intervention.

More and more users are finding ways to improve their workflow by automating tasks that would otherwise need to be executed manually.

For example, it is quite likely that your Operations department is using an automated deployment process to perform updates to your website (we use Octopus Deploy for that – let us know in the comments what you are using!). Those updates are usually not instantaneous – it takes a while to complete, which means that your website, e-commerce system, or web API is temporarily unavailable or displays different behavior while the update is in progress.

Chances are that your web monitoring solution will pick up on this temporary situation, particularly when your website doesn’t display the usual content on the pages you’re monitoring, or when your web servers are slower to respond than usual. However, your Operations team can do without the distraction of unnecessary alert emails or texts – they’re already aware of the situation anyway.

It would be great to automatically keep your web monitors quiet during deployment, so you don’t have to go in and disable them manually. Connecting to Uptrends via the API is a great way to do that. Most Uptrends accounts come with free access to the API, so let’s see how we can use it to automate this task.

Uptrends’ API is accessed over HTTPS. There are many different ways to do that, depending on the environment you’re operating in. For Octopus Deploy, the obvious way is to fire a Powershell script that sends out the HTTPS request. Other deployment systems – including home-grown ones on Windows, Linux or Mac OS X – may prefer to use the cURL command line tool to generate HTTPS requests. In this post, we’ll provide examples for both Powershell and cURL, but any script environment or programming language that can send HTTPS requests will work.

Before we dive into the code, though, let’s take a look at the key ingredients for calling the API to disable a monitor (and enabling it again afterwards).

Information we’ll put in the request

• The unique ID (called Guid) of the monitor we want to disable. Your script needs to know which monitor(s) you want to disable. For now, we’ll include the Guid in the script itself. You can find the Guid by editing the monitor in Uptrends, and looking at the Guid in the address bar of your browser.
• The URL to call: We’ll access https://api.uptrends.com/v3/probes/{Guid}, where {Guid} is the ID we just picked up.
• The HTTP method to use: We’ll use a PUT request to update our monitor. It is important you specify this method, or your script or programming language will probably perform a GET request instead, which is not the operation we want to perform here.
• The monitor fields we want to update. Since we just want to disable the monitor, we will only need to update the IsActive field, and we’ll give it a value of False. Later on, we’ll send IsActive: True to re-enable the monitor again. We’ll put the field values in a JSON-formatted message in the HTTPS request’s body content.
• We need to tell the API about the fact that we’re using the JSON format, so we’ll specify the appropriate Content-Type header.
• Lastly, login credentials. You’ll need an Uptrends username (usually your email address) that has administrative rights to update your monitors, and the corresponding password. We’ll use the authentication method Basic Authentication to add those credentials to the HTTPS request.

Using Powershell

In the following code segment, the only lines of code you’ll need to change for your situation are at the top, marked with a Specify: comment.

# Specify: your Uptrends login info
$user = "my-email@company.com" 
$pass= "PasswordXYZ"

# Specify: the Guid for the monitor
$monitorGuid = "81661ec0-f297-4a3e-89c2-7e17270d6f85"

# Specify: make the monitor inactive ($false) or active ($true)
$makeActive = $false

# URI to the API method we want to execute. It includes the monitorGuid we're going to update
$uri = "https://api.uptrends.com/v3/probes/$monitorGuid"

# Compile the login info into credentials containing basic authentication
$passwordValue = ConvertTo-SecureString $pass -AsPlainText -Force 
$cred = New-Object System.Management.Automation.PSCredential ($user, $passwordValue)

# Build our body content by including the fields we want to update
$body = @{
  IsActive = $makeActive
}

# Format the body content as a JSON string
$bodyJson = $body | ConvertTo-Json

# Execute the request
$result = Invoke-RestMethod -Uri $uri -Method Put -Credential $cred -ContentType "application/json" -Body $bodyJson

That’s it! Running this script should be enough for disabling your monitor. Don’t forget to run it again afterwards with $makeActive = $true to enable your monitor again.

Using cURL

Obviously the code for a command line tool will be much more condensed, so we’ll break it down in a few pieces to explain the various flags you’ll need to specify.

• -X PUT
  Specifies the HTTP method PUT
• –user yourusername:password
  Your user name and password, separated by a colon character
• -H “Content-Type: application/json”
  The HTTP header for specifying the content type of the body content
• -d “{\”IsActive\”: true}”
  The body content containing JSON-formatted data. Note the backslashes as escape characters in front of the quotes.
• “https://api.uptrends.com/v3/probes/{monitorGuid}”
  The URL we’re sending this request to, containing the Guid of your monitor
• -k
  You may have to use this option if you’re using a version of cURL that doesn’t know about your computer’s SSL libraries and certificate stores. This option will skip SSL verification entirely. See https://curl.haxx.se/docs/sslcerts.html for more options.

With everything put together, you’ll get this command line:

curl -X PUT --user my-email@company.com:PasswordXYZ -H "Content-Type: application/json" -d "{\"IsActive\": true}" "https://api.uptrends.com/v3/probes/81661ec0-f297-4a3e-89c2-7e17270d6f85" -k

Testing our code

Once you’ve sent the HTTPS request through Powershell, cURL, or any other method, it will send back a 200 OK response code if it executed correctly. The change is effective immediately, so you should be able to see the change in your Uptrends account right away. If not, check whether an error came back after sending the request. Check your login credentials if you got a 401 Unauthorized. If the result was a 400 Bad Request, check that the monitor guid was correct. Not sure what’s going on? Feel free to contact Uptrends Support and tell us about your project.

Tip: Suppressing alerts

Quick tip: Perhaps you want to keep recording the uptime of your monitors at all times, to see how much downtime your planned and unplanned updates are causing. In those cases, you want to keep your monitors running but suppress alert messages instead during an update. Rather than using the IsActive field in the content body, use the GenerateAlert field instead. Setting that field to False prevents alerts from being generated.

Conclusion

We’ve looked at how you can use the Uptrends API to disable your monitors, or disable the alerting associated with your monitors. A next step could be to further automate this process by looping through a predefined list of monitors. We’ll look at that in a future blog post.

Take a look at the API documentation to see what else is possible. Perhaps you want to add new monitors automatically when your system creates a new site? Update content checks when your site’s content is updated? Automatically add notes to your monitor as a way to record incidents? There’s a lot you can do – let us know what you would like to work on!