Use your performance data anywhere with the new data API

By Posted in Engineering 20 June 2011

When I started working at New Relic, one thing that impressed me was the care the team takes in the presentation of performance data. We don’t hesitate to say no to new features that would distract you from the most important information to focus on.

But what if you want to display or use your data in a different way? Or correlate it with data you have elsewhere? What if you want to make your own real-time charts? Fortunately, that’s all quite easy now, with the (new) New Relic Data API.

The New Relic Data API allows you to:

  1. Look up Apdex, throughput, database, web services, and enduser data programmatically.
  2. Access both historical and near-real-time data.
  3. Make widgets, mini-apps, dashboards, and integrate New Relic into third party applications.

Maple Leaf Flag

Let me introduce you to our hero, Bill. Bill’s company is expanding into Canada (a very worthwhile endeavor!). They want to know how their new marketing efforts affect the number of visitors they get from Canada. They can see most of this data in New Relic already, but they’re creating a new dashboard for this project, which has all the data they’re looking for in all the same place. Will our hero be able to save the day? Although this example focuses on end-user data like number of visits, you can also do the same with all the performance data from New Relic.

First of all, Bill considers using embeddable charts, but realizes it doesn’t provide the exact view he’s looking for. And he also wants to include internal data in the same dashboard.

After reading the documentation on the New Relic API, Bill figures out that there are basically only two steps he needs to take to get the New Relic data he needs for his dashboard:

  1. First, he needs to look up the metrics he wants data for.
  2. Then he needs to look up the data for that metric.

At first, Bill is a little confused by this term “metric”. What the heck is a metric? Fortunately, he sees the Metric Names API, which allows him to look up the definitions of metrics. Here are some examples of metrics:

  1. Web transactions
  2. Database transactions
  3. Enduser (real user monitoring) Apdex
  4. Apdex scores
  5. Enduser (real user monitoring) data for regions.
  6. External calls to other web services

He also learns than the metric names have this pattern:

MetricType/Path/For/Transaction

And he is surprised to learn that they don’t map directly to URLs. For example, on his particular application, these two URLs:

http://www.fake-bacon.com/accounts/1
http://www.fake-bacon.com/accounts/2

Will both translate to a path that looks like:

/accounts/*

And the metrics will look like:

Apdex/accounts/*
Controller/accounts/*

On some platforms, they may not look like the URL at all, and may map more directly to the code instead.

Bill happens to be handy with curl, so he goes to the command line and begins typing.

curl -H "x-api-key:BILLS_API_KEY" https://api.newrelic.com/api/v1/applications/12345/metrics.json

But he doesn’t have an API Key, and hasn’t enabled API access. He first goes to the account settings link:

account-settings

He selects the API+web integration tab:

api-integration

and clicks on “Enable API access”.

api-key

and copies the API key. Then, he tries again:

curl -H "x-api-key:BILLS_API_KEY" https://api.newrelic.com/api/v1/applications/12345/metrics.json

Success! He gets back a long list of metrics, each line looking like this:

{"fields":["average_exclusive_time",
"average_response_time","call_count","calls_per_minute",
"max_response_time","min_response_time"],
"name":"ActiveRecord/save"}

What this means is that for the “ActiveRecord/save” metric, the fields available are:

  1. Average response time
  2. Average exclusive time. Exclusive time is time spent in that method, but not in code instrumented by New Relic called from that method.
  3. Call count
  4. Calls per minute
  5. Maximum response time
  6. Minimum response time

Every metric type may have a different list of fields available.

Bill has two applications, one in Ruby, and one in Java. Though the set of metrics is slightly different for each, he’s pleased to learn just how much information is available, right at his fingertips.

Bill wants to compare the visits per minute from Canada and the US. He can retrieve this in one query using the Metric Data API:

curl -H "x-api-key:BILLS_API_KEY" https://api.newrelic.com/api/v1/applications/1441/data.json
?begin=2011-06-13T15:00:00Z
&end=2011-06-13T15:05:00Z
&metrics[]=EndUser/Visit/Country/US
&metrics[]=EndUser/Visit/Country/CA
&field=calls_per_minute
&summary=1 

and he gets a machine-readable reply back that looks like this:

[{"calls_per_minute":2.60869565217391,"name":"EndUser/Visit/Country/CA"},{"calls_per_minute":51.1705685618729,"name":"EndUser/Visit/Country/US"}]

He could also leave off the summary=1, and he’d get a series of values, not rolled up, like:

[{"calls_per_minute":6.0,"begin":"2011-06-13T15:00:00Z","end":"2011-06-13T15:01:00Z","name":"EndUser/Visit/Country/CA"},
{"calls_per_minute":0.0,"begin":"2011-06-13T15:01:00Z","end":"2011-06-13T15:02:00Z","name":"EndUser/Visit/Country/CA"},
{"calls_per_minute":2.0,"begin":"2011-06-13T15:02:00Z","end":"2011-06-13T15:03:00Z","name":"EndUser/Visit/Country/CA"},
{"calls_per_minute":4.0,"begin":"2011-06-13T15:03:00Z","end":"2011-06-13T15:04:00Z","name":"EndUser/Visit/Country/CA"},
{"calls_per_minute":1.0,"begin":"2011-06-13T15:04:00Z","end":"2011-06-13T15:05:00Z","name":"EndUser/Visit/Country/CA"},
{"calls_per_minute":41.0,"begin":"2011-06-13T15:00:00Z","end":"2011-06-13T15:01:00Z","name":"EndUser/Visit/Country/US"},
{"calls_per_minute":54.0,"begin":"2011-06-13T15:01:00Z","end":"2011-06-13T15:02:00Z","name":"EndUser/Visit/Country/US"},
{"calls_per_minute":59.0,"begin":"2011-06-13T15:02:00Z","end":"2011-06-13T15:03:00Z","name":"EndUser/Visit/Country/US"},
{"calls_per_minute":44.0,"begin":"2011-06-13T15:03:00Z","end":"2011-06-13T15:04:00Z","name":"EndUser/Visit/Country/US"},
{"calls_per_minute":57.0,"begin":"2011-06-13T15:04:00Z","end":"2011-06-13T15:05:00Z","name":"EndUser/Visit/Country/US"}]

 

statueBill builds his dashboard, and it proves to be so useful, his co-workers erect a statue of him in the office.

I hope you enjoy the Data API, and I hope you have as much fun using it as I had writing it. Let us know if you have any questions or feedback, and let us know how you use it. We plan on making even more updates to the API and we’d love to have your help in guiding its future directions.

And if you have a statue made of you, please send a photo our way!

 

Software Engineer

Tell us your thoughts Or Send us an internal high five

Talk to @newrelic