New Relic REST API

This gem contains the documentation and examples for using the New Relic REST API for RPM customers.

Rails developers can use the ActiveResource helper file found in this gem. Refer to the gem rdocs.

New Relic supports a RESTful API that can be used to list applications within a given account and enumerate the health indicators of each application. The API uses the XML response format. As a convenience, New Relic offers an ActiveResource wrapper API, but developers are welcome to work directly with the XML.

Authentication

New Relic supports an api key-based authentication mechanism. The key is the api key associated with an account and can be obtained using the RPM Account settings for Integrations. This key should be passed as a request header with each request. All API calls described in this document require authentication.

API requests require HTTPS in order to ensure the API key cannot be easily read by a third party.

Request Headers

x-api-key

API key for account, used for authentication (required)

ActiveResource authentication under Rails

NewRelicApi.api_key = '<api key>'

ActiveResource API

The New Relic ActiveResource-based API helper is NewRelicApi. If you are using ActiveResource to access our API you can focus on the documentation and examples contained in the Ruby Documentation.

The remainder of this document will describe our XML API.

View applications

URL

https://rpm.newrelic.com/accounts/:account_id/applications.xml

Method

GET

Restrictions

None

Active Resource Helper

NewRelicApi::Account

Replace :account_id with the your account number. You can see this in the browser URL when you log in to rpm.newrelic.com.

Data Returned

Sample data:

<?xml version="1.0" encoding="UTF-8"?>
<applications type="array"> 
  <application> 
    <id type="integer">123</id> 
    <name>My Application</name> 
    <overview-url><a href="https://rpm.newrelic.com/browser/agent?account_id=1&agent=123%3C">https://rpm.newrelic.com/browser...</a>/overview-url> 
  </application> 
  <application> 
    <id type="integer">124</id> 
    <name>My Application2</name> 
    <overview-url><a href="https://rpm.newrelic.com/browser/agent?account_id=1&agent=124%3C">https://rpm.newrelic.com/browser...</a>/overview-url> 
  </application> 
</applications>

Possible Error Conditions

  • Invalid API Key (403)

Application Summary Metrics

Fetch summary metrics and threshold values (traffic light information) for one application.

URL

https://rpm.newrelic.com/accounts/:account_id/applications/:app_id/threshold_values.xml Replace :account_id and :app_id with the account and application IDs.

Method

GET

Restrictions

This API should be called at most once per minute

Active Resource Helper

NewRelicApi::Account

Data Returned

Note: Application Busy data will only be returned to Gold customers. Errors data will only be returned to Silver and Gold customers.

Sample data:

<?xml version="1.0" encoding="UTF-8"?>
<threshold-values type="array"> 
  <threshold_value name="Apdex" begin_time="Fri Dec 12 01:22:00 +0000 2008" end_time="Fri Dec 12 01:27:00 +0000 2008" formatted_metric_value="0.96 [1.0]*" threshold_value="1" metric_value="0.96"/> 
  <threshold_value name="Application Busy" begin_time="Fri Dec 12 01:22:00 +0000 2008" end_time="Fri Dec 12 01:27:00 +0000 2008" formatted_metric_value="3%" threshold_value="1" metric_value="3"/> 
  <threshold_value name="CPU" begin_time="Fri Dec 12 01:22:00 +0000 2008" end_time="Fri Dec 12 01:27:00 +0000 2008" formatted_metric_value="52.86 %" threshold_value="1" metric_value="52.86"/> 
  <threshold_value name="Memory" begin_time="Fri Dec 12 01:22:00 +0000 2008" end_time="Fri Dec 12 01:27:00 +0000 2008" formatted_metric_value="261.42 MB" threshold_value="1" metric_value="261.42"/> 
  <threshold_value name="Errors" begin_time="Fri Dec 12 01:22:00 +0000 2008" end_time="Fri Dec 12 01:27:00 +0000 2008" formatted_metric_value="0.0 epm" threshold_value="1" metric_value="0.0"/> 
  <threshold_value name="Response Time" begin_time="Fri Dec 12 01:22:00 +0000 2008" end_time="Fri Dec 12 01:27:00 +0000 2008" formatted_metric_value="31 ms" threshold_value="1" metric_value="31"/> 
  <threshold_value name="Throughput" begin_time="Fri Dec 12 01:22:00 +0000 2008" end_time="Fri Dec 12 01:27:00 +0000 2008" formatted_metric_value="14028.6 cpm" threshold_value="1" metric_value="14028.6"/> 
  <threshold_value name="DB" begin_time="Fri Dec 12 01:22:00 +0000 2008" end_time="Fri Dec 12 01:27:00 +0000 2008" formatted_metric_value="46.82 %" threshold_value="1" metric_value="46.82"/> 
</threshold-values>

Possible Error Conditions

  • Invalid API Key (403)

  • Unknown Application (404)

Application Summary Metrics (All applications)

Fetch summary metrics and threshold values (traffic light information) for all applications.

URL

https://rpm.newrelic.com/accounts.xml?include=application_health

Method

GET

Restrictions

This API should be called at most once per minute

Active Resource Helper

NewRelicApi::Account

Data Returned

Note: Application Busy data will only be returned to Gold customers. Errors data will only be returned to Silver and Gold customers.

Sample data:

<accounts type="array">
  <account> 
    <id>1</id> 
    <name>New Relic Administration</name> 
    <applications type="array"> 
      <application> 
        <id type="integer">5</id> 
        <name>My Application</name> 
        <threshold-values type="array"> 
          <threshold_value begin_time="Fri Nov 21 20:03:00 +0000 2008" formatted_metric_value="0.96 [1.0]*" name="Apdex" end_time="Fri Nov 21 20:08:00 +0000 2008" threshold_value="1" metric_value="0.96"/> 
          <threshold_value begin_time="Fri Nov 21 20:03:00 +0000 2008" formatted_metric_value="3%" name="Application Busy" end_time="Fri Nov 21 20:08:00 +0000 2008" threshold_value="1" metric_value="3"/> 
          <threshold_value begin_time="Fri Nov 21 20:03:00 +0000 2008" formatted_metric_value="2.59 %" name="CPU" end_time="Fri Nov 21 20:08:00 +0000 2008" threshold_value="1" metric_value="2.59"/> 
          <threshold_value begin_time="Fri Nov 21 20:03:00 +0000 2008" formatted_metric_value="151.62 MB" name="Memory" end_time="Fri Nov 21 20:08:00 +0000 2008" threshold_value="1" metric_value="151.62"/> 
          <threshold_value begin_time="Fri Nov 21 20:03:00 +0000 2008" formatted_metric_value="0.0 epm" name="Errors" end_time="Fri Nov 21 20:08:00 +0000 2008" threshold_value="1" metric_value="0.0"/> 
          <threshold_value begin_time="Fri Nov 21 20:03:00 +0000 2008" formatted_metric_value="947 ms" name="Response Time" end_time="Fri Nov 21 20:08:00 +0000 2008" threshold_value="1" metric_value="947"/> 
          <threshold_value begin_time="Fri Nov 21 20:03:00 +0000 2008" formatted_metric_value="2.4 cpm" name="Throughput" end_time="Fri Nov 21 20:08:00 +0000 2008" threshold_value="1" metric_value="2.4"/> 
          <threshold_value begin_time="Fri Nov 21 20:03:00 +0000 2008" formatted_metric_value="0.52 %" name="DB" end_time="Fri Nov 21 20:08:00 +0000 2008" threshold_value="1" metric_value="0.52"/> 
        </threshold-values> 
      </application> 
    </applications> 
  </account> 
</accounts>

Possible Error Conditions

  • Invalid API Key (403)

Dashboard HTML fragment (All applications)

New Relic provides an HTML fragment of the dashboard view of RPM. CSS styles are included, and images linked absolutely, which enables callers to embed the response directly in their applications. Authentication is through setting the appropriate API key header as outlined above, or through the regular login cookie. When using the regular login cookie, the logged-in user's default account's applications will be shown.

URL

https://rpm.newrelic.com/application_dashboard

Method

GET

Restrictions

This API should be called at most once per minute

Active Resource Helper

None available currently

Data Returned

Sample data:

<div id="newrelic-rpm-2">
  <div id="newrelic-rpm-2-content">
    <style type="text/css" media="screen">
       ...embeded styles...
    </style>

<table id="all_applications" cellspacing="0" class="section agent_display span-16">
  <thead>
    <tr>
      <th class="header">Application</th>
      <th title="Apdex Score is a industry-standard measurement of customer satisfaction. It is calculated essentially as weighted response time. The larger number is your Apdex Score, out of 1, and the smaller number is the threshold for an acceptable response time, in seconds." class="apdex">Apdex Score <a href="http://support.newrelic.com/faqs/general/apdex" target="_blank"><img alt="?" src="https://rpm.newrelic.com/images/v2/12x12/moreinfo.png?1285097852" style="border: 0px none;" /></a></th>
      <th title="Response Time is the average time it took to generate a response to all requests.">Resp. Time</th>
      <th title="Errors is the percentage of your requests that received an error as a response.">Errors</th>
      <th title="Throughput is total number of requests processed by your application per minute." class="throughput last">Throughput<br>(change from <abbr title="24 hours ago">24h</abbr>/<abbr title="7 days ago">7d</abbr>)</th>
    </tr>
  </thead>
  <tbody class="application application_1">  
    <tr class="application_tier data">
      <td class="agent">
        <img alt="Normal" src="https://rpm.newrelic.com/images/v2/16x16/light-green.png?1285097852" />
        <span class="name">
          <a href="https://rpm.newrelic.com/v2/accounts/1/applications/1" class="application">RPM</a>	  
        </span>
        <span class="status reporting">1 Host and 5 Instances</span>
      </td>
      <td class="data apdex">
        <a href="https://rpm.newrelic.com/v2/accounts/1/applications/1/transactions#sort_by%3Dapdex">0.99<sub>0.025</sub></a>
      </td>
      <td class="data"><a href="https://rpm.newrelic.com/v2/accounts/1/applications/1/transactions">5.7 ms</a></td>
      <td class="data"><a href="https://rpm.newrelic.com/v2/accounts/1/applications/1/traced_errors">0.00 %</a></td>
      <td class="data throughput last">
        <a href="https://rpm.newrelic.com/v2/accounts/1/applications/1/transactions#sort_by%3Dthroughput">92 rpm</a>  
        <div class="throughput_history">
          <span class="yesterday" title="Throughput down 2% from 24 hours ago"><strong class="down ">-2%</strong></span>
          <span class="last_week" title="Throughput up 0% from 7 days ago"><strong class="up ">0%</strong></span>
        </div>  
      </td>
    </tr>
  </tbody>
</table>

<script type="text/javascript" charset="utf-8">

  // Link catching via event delegation

  var getTarget = function(x){
    x = x || window.event;
    return x.target || x.srcElement;
  };

  var linkCatcher = function(event){
    var target = getTarget(event);

    var link = findLink(target);
    if(link !== null){
      window.open(link.href);
      return false;
    }
  };

  var findLink = function(el){
    while(el.nodeName.toLowerCase() !== "body"){
      if(el.nodeName.toLowerCase() === 'a'){
        return el;
      }
      else {
        el = el.parentNode;
      }
    }
    return null;
  };

  var table = document.getElementById("all_applications");
  table.onclick = linkCatcher;
</script>

  </div>
</div>

Possible Error Conditions

  • Invalid API Key (403)

Dashboard HTML fragment (One application)

URL

https://rpm.newrelic.com/application_dashboard?application_id=:id Replace :id with application ID.

Method

GET

Restrictions

This API should be called at most once per minute

Active Resource Helper

None available currently

Request Parameters

  • application_id: the ID of the application to view

Data Returned

Sample data:

<div id="newrelic-rpm-2">
  <div id="newrelic-rpm-2-content">
    <style type="text/css" media="screen">
      ...embeded styles...
    </style>

<table id="all_applications" cellspacing="0" class="section agent_display span-16">
  <thead>
    <tr>
      <th class="header">Application</th>
      <th title="Apdex Score is a industry-standard measurement of customer satisfaction. It is calculated essentially as weighted response time. The larger number is your Apdex Score, out of 1, and the smaller number is the threshold for an acceptable response time, in seconds." class="apdex">Apdex Score <a href="http://support.newrelic.com/faqs/general/apdex" target="_blank"><img alt="?" src="https://rpm.newrelic.com/images/v2/12x12/moreinfo.png?1285097852" style="border: 0px none;" /></a></th>
      <th title="Response Time is the average time it took to generate a response to all requests.">Resp. Time</th>
      <th title="Errors is the percentage of your requests that received an error as a response.">Errors</th>
      <th title="Throughput is total number of requests processed by your application per minute." class="throughput last">Throughput<br>(change from <abbr title="24 hours ago">24h</abbr>/<abbr title="7 days ago">7d</abbr>)</th>
    </tr>
  </thead>
  <tbody class="application application_1">  
    <tr class="application_tier data">
      <td class="agent">
        <img alt="Normal" src="https://rpm.newrelic.com/images/v2/16x16/light-green.png?1285097852" />
        <span class="name">
          <a href="https://rpm.newrelic.com/v2/accounts/1/applications/1" class="application">RPM</a>	  
        </span>
        <span class="status reporting">1 Host and 5 Instances</span>
      </td>
      <td class="data apdex">
        <a href="https://rpm.newrelic.com/v2/accounts/1/applications/1/transactions#sort_by%3Dapdex">0.99<sub>0.025</sub></a>
      </td>
      <td class="data"><a href="https://rpm.newrelic.com/v2/accounts/1/applications/1/transactions">5.7 ms</a></td>
      <td class="data"><a href="https://rpm.newrelic.com/v2/accounts/1/applications/1/traced_errors">0.00 %</a></td>
      <td class="data throughput last">
        <a href="https://rpm.newrelic.com/v2/accounts/1/applications/1/transactions#sort_by%3Dthroughput">92 rpm</a>  
        <div class="throughput_history">
          <span class="yesterday" title="Throughput down 2% from 24 hours ago"><strong class="down ">-2%</strong></span>
          <span class="last_week" title="Throughput up 0% from 7 days ago"><strong class="up ">0%</strong></span>
        </div>  
      </td>
    </tr>
  </tbody>
</table>

<script type="text/javascript" charset="utf-8">

  // Link catching via event delegation

  var getTarget = function(x){
    x = x || window.event;
    return x.target || x.srcElement;
  };

  var linkCatcher = function(event){
    var target = getTarget(event);

    var link = findLink(target);
    if(link !== null){
      window.open(link.href);
      return false;
    }
  };

  var findLink = function(el){
    while(el.nodeName.toLowerCase() !== "body"){
      if(el.nodeName.toLowerCase() === 'a'){
        return el;
      }
      else {
        el = el.parentNode;
      }
    }
    return null;
  };

  var table = document.getElementById("all_applications");
  table.onclick = linkCatcher;
</script>

  </div>
</div>

Possible Error Conditions

  • Invalid API Key (403)

  • Unknown Application (404)

Deployment Notifications

Unlike other API requests, the deployments API will accept either a license key or an API key in the api-key header. Furthermore, when using the license key, you do not need to enable the API in the account settings. This is the standard mechanism used by the agent to upload deployments from the built in capistrano recipes.

URL

https://rpm.newrelic.com/deployments.xml

Method

POST

Active Resource Helper

NewRelicApi::Account

Request Parameters

Exactly one of the following is required:

  • deployment[app_name]: The value of app_name in the newrelic.yml file used by the application. This may be different than the label that appears in the RPM UI. You can find the app_name value in RPM by looking at the label settings for your application.

  • deployment[application_id]: The application id, found in the URL when viewing the application in RPM.

Following are optional parameters:

  • deployment[description]: Text annotation for the deployment &mdash; notes for you

  • deployment[changelog]: A list of changes for this deployment

  • deployment[user]: The name of the user/process that triggered this deployment

The optional fields may be set to anything you wish, and are not validated. For example, you could set the user to "auto deployment script".

Example

Here's an example using curl:

curl -H "x-api-key:YOUR_LICENSE_KEY_HERE" -d "deployment[app_name]=iMyFace.ly Production" https://rpm.newrelic.com/deployments.xml

If you were to specify the optional description, changelog and user fields, the command would look like this:

curl -H "x-api-key:YOUR_LICENSE_KEY_HERE" -d "deployment[app_name]=iMyFace.ly Production" -d "deployment[description]=This deployment was sent using curl" -d "deployment[changelog]=many hands make light work" -d "deployment[user]=Joe User" https://rpm.newrelic.com/deployments.xml

Copyright

Copyright © 2011 New Relic, Inc.