One of the most requested features of New Relic Synthetics has been a public REST API. It makes sense—having a sensible API to programmatically manage monitors would be a natural evolution of the product. At its core, Synthetics’ runtime is a sandboxed programming environment, and what could be better for managing this runtime than more programming (via API)?

Well, we’re excited to announce that the Synthetics’ public REST API is now available. To help you make the most of this new feature, we’ve put together a brief tutorial to walk you through the process of creating and managing your first monitor using our newly released API, as well as some of the interesting workflows you can now set up.

Background

Our REST API for Synthetics enables you to:

  • Perform CRUD (Create/Update/Delete) operations on monitors
  • Control monitor state (enabled/disabled and muted/unmuted)
  • Associate monitors with labels
  • Associate monitors with alert policies

Some basics to know when interacting with our API:

  • Authentication is handled the same way as other New Relic APIs with v2 admin tokens in a X-API-KEY header (you can find out how to generate your own tokens here).
  • The API consumes and produces application/JSON

In this blog post we’re going to help you create your first scripted monitor using our shiny new API, start/stop the monitor via the API , and for the bonus round, show you how to add email alert notification to the newly created monitor.

Creating a monitor

To demonstrate how the Synthetics REST API works, let’s create a scripted-browser monitor (type = script_browser) with a 10-minute frequency, from three geographical locations. Let’s name this monitor monitor1. 

Request:

POST https://synthetics.newrelic.com/synthetics/api/v1/monitors
{
   "name" : "monitor1",
   "frequency": 10,
   "locations" : ["AWS_US_EAST_1", "LINODE_US_WEST_1", "AWS_EU_WEST_1"],
   "type": "script_browser"
}

Response:

Status: 201 Created
Location: https://synthetics.newrelic.com/synthetics/api/v1/monitors/d434e319-99d3-4371-94ce-5490db3f0946

Success! Your monitor has been created (good job).

Next we need to attach a monitoring script to that monitor. This is accomplished with a second API call looking up the monitor by the location we received in the previous request:

Request:

POST https://synthetics.newrelic.com/synthetics/api/v1/monitors/d434e319-99d3-4371-94ce-5490db3f0946/script
{
     "scriptText": "JGJyb3dzZXIuZ2V0KCdodHRwczovL25ld3JlbGljLmNvbS9zeW50aGV0aWNzJyk7"
}

Response:

Status: 204 No Content

Wait! What’s all that gibberish for the script text?! Good question (you’re pretty sharp). Our API expects the script body to be base64 encoded so it conforms to the JSON specification. This is one of those important “gotchas” not to forget.

Now, for the reveal, let’s make sure the newly minted monitor shows up in your account.

Getting a list of all your monitors

Let’s do a quick inventory check of the monitors that we’ve created. This is particularly useful if you have thousands of monitors set up globally for all your apps.

Request:

GET https://synthetics.newrelic.com/synthetics/api/v1/monitors

Response:

Status: 200 OK
{
   "monitors": [
      {
         "id": "d434e319-99d3-4371-94ce-5490db3f0946",
         "name": "monitor1",
         "type": "SCRIPT_BROWSER",
         "frequency": 10,
         "locations": [
            "AWS_EU_WEST_1",
            "LINODE_US_WEST_1",
            "AWS_US_EAST_1"
         ],
         "status": "ENABLED",
         "slaThreshold": 7,
         "modifiedAt": "2016-02-19T05:54:52.382+0000",
         "createdAt": "2016-02-19T05:54:52.382+0000",
         "userId": 0,
         "apiVersion": "0.2.2"
      }
   ],
   "count": 1
}

Start/stopping monitors

Let’s say you have a scheduled maintenance window and would like to disable your monitor at the start of that period, and then re-enable it when the maintenance is complete. This is simple with our API; just set your monitor status to disabled.

Request:

PUT https://synthetics.newrelic.com/synthetics/api/v1/monitors/d434e319-99d3-4371-94ce-5490db3f0946
{
   "name" : "monitor1",
   "frequency": 10,
   "locations" : ["AWS_US_EAST_1", "LINODE_US_WEST_1", "AWS_EU_WEST_1"],
   "type": "script_browser",
   "status": "disabled"
}

Response:

Status: 204 No Content

That’s it, the monitor is now disabled and will not run again until you flip its status back to enabled. 

Use cases

So, what can you do with these APIs? Some very useful workflows are now possible:

Integrate your synthetic monitors with your build pipeline. Pushing out new features also means building new testing scripts for them, as well as deploying the corresponding Synthetics monitors with these updated scripts. Keeping all of these in sync can be challenging, but you can now automatically deploy new monitors via API as part of your build process, helping to make sure your deployments and monitoring stay in lockstep for a more seamless release process.

Manage thousands of monitors at scale. We have customers who have created thousands of monitors across their application portfolio, and many of them were looking for a more programmatic way to control their synthetic testing at scale. This API release helps them to set up, configure, and manage their monitors across their environments more quickly and easily.

Align monitoring checks with maintenance windows. No one likes getting an alert for downtime, especially if it turns out that the app was intentionally brought down for scheduled maintenance. You can now use the Synthetics APIs to automatically mute monitors during scheduled maintenance windows, and to automatically unmute them when things are live again. Preventing false-positive alerts can help keep you from being unnecessarily woken up at 2 a.m.!

Wrapping up

These are just a few of the many things that you can do with the new Synthetics APIs. It’s our goal at New Relic to make our products as frictionless and easy to use as possible. We hope that you enjoy using New Relic Synthetics API as much as we enjoyed building it, and we’d love to get your feedback. Try them out today!

For more information, check out the documentation:

 

Background image courtesy of Shutterstock.com.

Rafael is the director of engineering for Synthetics at New Relic. View posts by .

Interested in writing for New Relic Blog? Send us a pitch!