Your data. Anywhere you go.

New Relic for iOS or Android


Download on the App Store    Android App on Google play


New Relic Insights App for iOS


Download on the App Store


Learn more

Close icon

Relic Solution: Using New Relic's REST APIs to migrate legacy alert conditions to new Alerts


#1

Update!

For a short time, the endpoint for listing legacy policies will remain available in case you didn’t get the chance to migrate your policies. Keep reading below to learn how you can use the API to remake your legacy alerts in the new platform!

What’s happening?

Legacy alerting is reaching End Of Life (EOL); Come May 15th you’ll no longer be able to access legacy alerts, and your legacy policies will be removed. (See more about this here)
Before then you’ll need to set up policies in new Alerts, and this post is built to help you with that.

Is there some way to automagically migrate legacy alerts to new Alerts?

No. We believe that alert policies and configurations, especially notification preferences are an account specific thing. There are a number of newer features in New Alerts as well, including more notification channel options, and generally more condition configuration options. Since that is the case there is not a direct mapping of legacy to new Alerts. As such, we could not build a migration script that would work for everyone.

In addition to that; we see frequently that customers have an unnecessarily huge number of legacy policies, often attached to applications that are no longer reporting. Providing a script to transfer these conditions over to new Alerts will get you off to a bad start with new Alerts. Why not take this opportunity to clean up your policies? After all, if you’re being paged throughout the night, you want it to be for something you need to worry about. Not an old condition that doesn’t relate to you anymore.

Ok - then how do I move my alerts from legacy alerts to new Alerts?

There are 2 options here;

  • Either you can manually create new policies using the UI, with one window open on the legacy policies, and another window with new alerts, allowing you to mirror your conditions.
  • Or - you could use New Relic’s APIs. This post is going to go into a lot more detail on this.

Which of these options you choose is entirely up to you. If you have a small number of legacy alert policies it may be quicker/easier to simply create policies & conditions via the UI.

Creating policies in the UI is reasonably simple - there are cues along the way to guide you in the set up, but just in case you need some help, check out these docs:

The UI is fine, but I have a lot of policies, does the API help me?

Sure! While New Relic don’t provide a script to automate alert migration, with the API you may be able to automate the process. We’ll go through the API calls you’ll need to do that.

How to get my legacy alert policies?

List Legacy Alert Policies:

curl -X GET 'https://api.newrelic.com/v2/alert_policies.json' \
     -H 'X-Api-Key:{Your_Account_API_Key}' -i \
     -G -d 'filter[enabled]=true'

Notice that in this API call I am only pulling data on the enabled policies - In my transition to new Alerts I am trying to clean up the junk in my legacy policies, I no longer need those disabled policies.

The returned data then is the JSON package containing the information on your enabled policies.

I am going to recreate the application_apdex condition here - With just one condition here, I’ll manually transfer this using the following API calls.

For the application apdex conditions here we can see that I have both a warning (caution) and critical threshold. I am going to take note of that data, to use later.

  • Caution Threshold - 0.9 if at that level for 10 minutes
  • Critical Threshold - 0.85 if at that level for 5 minutes

Further down in that JSON is some more crucial data - the application IDs of the APM App assigned to this policy - and the notification channel IDs associated.

I’m going to need this information before moving on to create my new policies - So I’ll be taking note of that at this point.

So now we have the conditions we’d like to recreate, and we have the notification channel IDs of the legacy policy. However, we don’t know what those channel IDs map to, so let’s get them next.

Listing legacy alert channels:

curl -X GET 'https://api.newrelic.com/v2/notification_channels/2822392.json' \
     -H 'X-Api-Key:{Your_Account_API_Key}' -i

Notice that in this call I’m just pulling the info on one notification channel, when running through this yourself you may need to run the query against all of your notification channel IDs.

What results is data on my test channel, using webhooks to post to Slack.

(This Slack URL was used for this post and is already deactivated - please do not share your own private URLs)

You can run the same API query with the other notification channel IDs, in this case I’ll stick with just one, so you can see the process.

With our conditions, and now our notification channels, it’s time to move over to new Alerts.

How to I mimic those legacy policies in new Alerts?

First we’ll need a new policy to put our conditions into; Use the API POST call below to create that policy

Create New Policies:

curl -X POST 'https://api.newrelic.com/v2/alerts_policies.json' \
     -H 'X-Api-Key:{Your_*Admin*_API_Key}' -i \
     -H 'Content-Type: application/json' \
     -d \
'{
  "policy": {
    "incident_preference": "PER_CONDITION",
    "name": "Replica - Default legacy policy"
  }
}'

Notice that here I am setting the incident preference, if you’re unsure what this is you can check out my colleague Steve’s post explaining this.

Take note of the Policy ID returned when you create that policy - we’ll need that for the next step.

Right now our policy “Replica - Default legacy policy” is an empty shell - we’ll need to put some new conditions in there.

Creating conditions for policies:

curl -X POST 'https://api.newrelic.com/v2/alerts_conditions/policies/228490.json' \
     -H 'X-Api-Key:{Your_*Admin*_API_Key}' -i \
     -H 'Content-Type: application/json' \
     -d \
'{
  "condition": {
    "type": "apm_app_metric",
    "name": "Apdex Low",
    "enabled": "true",
    "entities": [
      "114714081"
    ],
    "metric": "apdex",
    "condition_scope": "application",
    "violation_close_timer": "8",
    "terms": [
      {
        "duration": "5",
        "operator": "below",
        "priority": "critical",
        "threshold": "0.85",
        "time_function": "all"
      },
	{
        "duration": "10",
        "operator": "below",
        "priority": "warning",
        "threshold": "0.9",
        "time_function": "all"
      }
    ]
  }
}'

An explanation of each attribute above can be found here: https://rpm.newrelic.com/api/explore/alerts_conditions/create

Awesome - we now have our policy, and we’ve replicated our condition in there, with both warning and critical thresholds, and that policy is targeting the right application.

But an alert policy isn’t very useful unless it notifies us when an incident occurs. So lets recreate that slack notification channel from legacy alerts.

Creating new notification channels:

curl -X POST 'https://api.newrelic.com/v2/alerts_channels.json' \
     -H 'X-Api-Key:{Your_*Admin*_API_Key}' -i \
     -H 'Content-Type: application/json' \
     -G -d 'policy_ids[]=228490' \
     -d \
'{
  "channel": {
    "name": "Slack_Test",
    "type": "slack",
    "configuration": {
"url": "https://hooks.slack.com/services/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",
"channel": "Test Slack Channel"
}
  }
}'

As you can see here, I am specifying the exact alert policy I want to assign this new channel to. You can leave this bit out if you’d like to create channels now, and assign them to policies later.
Additionally - you’ll notice that here we have a “type”: “slack” notification channel, as opposed to legacy alerts where we used webhooks to post to Slack.

End Result.

Once all the above is done, you can check out the UI to see your policy there. With the condition you’ve just created, and notice that it’s assigned to one notification channel that we’ve just set up.

Final recommendations.

As you work more with new Alerts you’ll notice the differences between it, and the older legacy platform. Some of those differences include more notification channels, and more configurable channels (such as custom webhook payloads). The big difference is the vast array of configurable conditions, all managed in one place. You can have APM, Browser, Mobile, Synthetics, Plugins, etc… alert conditions all within one policy in the UI. You can manage your entire alert set up from one place in an easy to use intuitive UI.

So what next? Well that’s up to you. We definitely encourage you to play with alert configurations to become more familiar with the platform. And at the end of the day, it’s you that’ll be woken up getting paged by a New Relic alert - so make sure you’re alerting on the things you care about.

Finally -

  • This post deals with legacy APM Policies. Note that Mobile and Plugin policies and conditions are not available through the API.
  • If you have legacy notifications configured in your Synthetics monitors, you can use the Synthetics API to GET those emails, or to DELETE those notification channels.
  • Check out the Alerts best practices
  • Clean up your conditions and policies, ditching the messy setups from legacy alerts.
  • Be sure you understand incident preference and set that appropriately.

And always note, if you’re not overly familiar with APIs and running API calls, we do have an API Explorer allowing you to run every call listed in this doc from an easy to use UI.

Let us know in the comments below if you have a better solution to migrating alerts, or if you have questions on this process.


How to convert legacy alert into new relic alert
Migrating to new alert policy
#2

Great idea to check for outstanding Legacy Alerts. But! I just ran the API query, and it tells me the API is not available anymore. Is there any way to search for Legacy Alerts with the working API calls?

{“error”:{“title”:“The alert policies API is deprecated. Please see ‘alerts.newrelic.com’ for the new alerting infrastructure.”}}

Thanks.


#3

Hey @john.f.nixon - that error will show up when you run that API call on an account that no longer has Legacy Alerting access.

It’s possible that someone on your account opted fully into new Alerts.

Note that if your account is fully opted into new alerts, all of your legacy policies would be automatically disabled - so you’ll have no currently active legacy policies.

:smile:

  • Ryan

#4

See also the Alerts Transition Guide.


#5