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.

You will need to enable API access to your account. To do this, go to Account settings (upper right corner of the New Relic site), and then click on API + web integration. Select API access, and enable it.

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 Professional and Volume customers. Errors data will only be returned to Professional and Volume 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 Professional and Volume customers. Errors data will only be returned to Professional and Volume 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/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/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/accounts/1/applications/1/transactions">5.7 ms</a></td>
      <td class="data"><a href="https://rpm.newrelic.com/accounts/1/applications/1/traced_errors">0.00 %</a></td>
      <td class="data throughput last">
        <a href="https://rpm.newrelic.com/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/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/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/accounts/1/applications/1/transactions">5.7 ms</a></td>
      <td class="data"><a href="https://rpm.newrelic.com/accounts/1/applications/1/traced_errors">0.00 %</a></td>
      <td class="data throughput last">
        <a href="https://rpm.newrelic.com/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 (in the x-license-key header) or an API key (in the x-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[changelog]: A list of changes for this deployment

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

  • deployment[revision]: A revision number (e.g., git commit SHA)

  • 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_API_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_API_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

Metric Names

Fetches all metrics for an application, or allows you to use a regular expression to get a subset of the metrics. These metrics are used to retrieve metric values from the Metric Data API (below). Each metric is returned with a list of fields that are valid for that metric.

URL

https://api.newrelic.com/api/v1/applications/:app_id/metrics.:format Replace :app_id and :format with the application ID and for format use one of (json, xml, csv).

Method

GET

Restrictions

This API should be called at most once per minute.

For partner admins, you can use a slightly different URL to get metric names for your customers (requires partner permissions).

URL

https://api.newrelic.com/api/v1/accounts/:account_id/applications/:app_id/metrics.:format Replace :account_id with the account ID of the customer, :app_id with the application ID for the customer, and :format with one of (json, xml, csv).

Method

GET

Restrictions

This API should be called at most once per minute.

Request Parameters

  • re: A regular expression to filter the metric names by. Optional.

  • limit: The number of metrics to retrieve. Optional. By default the limit is 5000.

Data Returned

Note: Metric names will only be returned to Pro customers.

Sample requests:

api.newrelic.com/api/v1/applications/APPLICATION_ID/metrics.xml?re=WebTransaction&limit=2

Sample data:

<?xml version="1.0" encoding="UTF-8"?>
<metrics type="array">
  <metric name="WebTransaction">
    <fields type="array">
      <field name="average_call_time"/>
      <field name="average_response_time"/>
      <field name="call_count"/>
      <field name="max_call_time"/>
      <field name="min_call_time"/>
      <field name="requests_per_minute"/>
      <field name="throughput"/>
      <field name="total_call_time"/>
    </fields>
  </metric>
  <metric name="WebTransaction/RPMCollector/AgentListener/connect">
    <fields type="array">
      <field name="average_call_time"/>
      <field name="average_response_time"/>
      <field name="call_count"/>
      <field name="max_call_time"/>
      <field name="min_call_time"/>
      <field name="requests_per_minute"/>
      <field name="throughput"/>
      <field name="total_call_time"/>
    </fields>
  </metric>
</metrics>

Fields

Several different values are recorded or computed for each metric. Each value is returned in a ‘field’ in the metric data API response. Each field contains a value having a specific meaning and unit of measurement.

Time values are measured in seconds (s):

  • average_call_time, average_response_time: Average time spent per invocation

  • max_call_time, max_response_time

  • min_call_time, min_response_time

  • total_call_time

  • average_exclusive_time: Average time spent per invocation, exclusive of any time instrumented by other metrics

Some fields imply their units, or have none:

  • call_count, throughput: Number of calls/requests in the given time period

  • requests_per_minute: Number of calls/requests per minute in the given time period

  • count

  • average_value

  • total_value

  • percent

For the error-rate metric (‘Errors/all’)

  • errors_per_minute

For memory metrics (e.g., ‘Memory/Physical’)

  • used: in megabytes (MB)

For instance-counting metrics (e.g., ‘Instance/Busy’):

  • busy_percent: Percentage of total app server instances busy over the given time period

  • instance_count: Count of app server instances reporting in the given time period

Apdex metrics support a particular set of fields:

  • score: Apdex score (e.g., 0.95)

  • s: Percent of responses that are “Satisfied”, or have response times <= the Apdex “T” value

  • t: Percent of responses that are “Tolerated”, or have response times > T and <= 4T

  • f: Percent of responses that are “Frustrated”, or have response times >4T (or are errors)

Possible Error Conditions

  • Invalid API Key (403)

  • Invalid parameters (422) - the response body will be in the requested format and will contain the error message(s).

Metric Data

Returns the data values for metrics collected by New Relic for your application. You can use this API to build your own view of almost any metric data tracked by New Relic.

URL

https://api.newrelic.com/api/v1/accounts/:account_id/data.:format Replace :account_id and :format with your New Relic account ID (found in the URL when you access New Relic), and for format use one of (json, xml, csv).

Method

GET

Restrictions

This API is rate-limited per minute, and the limit is subject to change at any point.

For partner admins, you can use a slightly different URL to get metric data for your customers (requires partner permissions).

URL

https://api.newrelic.com/api/v1/accounts/:account_id/applications/:app_id/data.:format Replace :account_id with the account ID of the customer, :app_id with the application ID for the customer, and :format with one of (json, xml, csv).

Method

GET

Restrictions

This API is rate-limited per minute, and the limit is subject to change at any point.

Request Parameters

  • app or app_id: Application name, or application ID, respectively. The application name must be an exact match. You can pass in an array of apps to query by specifying app[]=First&app=Second or app_id[]=1234&app_id=2345

  • begin: Begin time, in XML UTC format. For example: 2011-04-20T15:47:00Z (note that the New Relic site graphs are NOT in UTC format, so when comparing results, be sure to convert)

  • end: End time, in XML UTC format. For example: 2011-04-20T15:52:00Z

  • metrics: Included one or many times, this lists the metrics you are interested in. If you specify multiple metrics, the request parameter should look like metrics[]=foo&metrics[]=bar (append ‘[]’ to the end of the name of the parameter). You can specify metrics[] even if there is a single metric.

  • field: Each metric supports different fields, such as ‘average_response_time’. If the field is not valid for a given metric, you will get a blank value, and if there are no valid fields for the metrics you request, you will get an error.

  • summary: 1 or 0, defaults to 0. This determines whether you get back a single value aggregated over the entire time period, or a time series. Summary results do not include the begin and end times in the result. Time series results give you a separate row for each time segment.

Data Returned

Note: Metric data will only be returned to Pro customers.

Sample time series request:

api.newrelic.com/api/v1/accounts/ACCOUNT_ID/data.xml?begin=2011-04-20T15:47:19Z&end=2011-04-20T15:52:19Z&metrics[]=ActiveRecord/all&field=average_response_time&app=My%20Application

Sample time series data:

<?xml version="1.0" encoding="UTF-8"?>
<metrics type="array">
  <metric app="My Application" begin="2011-04-20T15:47:00Z" end="2011-04-20T15:48:00Z" name="ActiveRecord/all">
    <field type="integer" name="average_response_time">0</field>
  </metric>
  <metric app="My Application" begin="2011-04-20T15:48:00Z" end="2011-04-20T15:49:00Z" name="ActiveRecord/all">
    <field type="integer" name="average_response_time">0</field>
  </metric>
  <metric app="My Application" begin="2011-04-20T15:49:00Z" end="2011-04-20T15:50:00Z" name="ActiveRecord/all">
    <field type="integer" name="average_response_time">0</field>
  </metric>
  <metric app="My Application" begin="2011-04-20T15:50:00Z" end="2011-04-20T15:51:00Z" name="ActiveRecord/all">
    <field type="integer" name="average_response_time">0</field>
  </metric>
  <metric app="My Application" begin="2011-04-20T15:51:00Z" end="2011-04-20T15:52:00Z" name="ActiveRecord/all">
    <field type="integer" name="average_response_time">0</field>
  </metric>
</metrics>

Sample summary request:

api.newrelic.com/api/v1/accounts/ACCOUNT_ID/data.xml?begin=2011-04-20T15:47:19Z&end=2011-04-20T15:52:19Z&metrics[]=ActiveRecord/all&field=average_response_time&app=My%20Application&summary=1

Sample summary data:

<?xml version="1.0" encoding="UTF-8"?>
<metrics type="array">
  <metric app="My Application" name="ActiveRecord/all">
    <field type="integer" name="average_response_time">0</field>
  </metric>
</metrics>

Possible Error Conditions

  • Invalid API Key (403)

  • Invalid parameters (422) - the response body will be in the requested format and will contain the error message(s).

Copyright © 2011 New Relic, Inc.