This document gives an example of how to use the New Relic REST API (v2) to find out the average available memory for a specific server ID and API key. The time range used in the examples is one week, and not the default value of 30 minutes.
Available memory is the amount of physical memory a host has installed, as reported by the system. To view the available memory in the New Relic Servers Overview page, mouse over a data point on the Physical memory chart. Currently the UI does not allow you to display the average available memory over a range of time.
When acquiring data with the API, the values returned may be affected by the time period you specify and the way the data is stored. For more information, see Extracting metric timeslice data.
Average system memory used
To obtain the average memory used on the host for the selected time period, use the metric name System/Memory/Used/bytes and the value average_value. For example:
curl -X GET "https://api.newrelic.com/v2/servers/${YOUR_SERVER_ID}/metrics/data.xml" \
-H "X-Api-Key:${YOUR_API_KEY}" -i \
-d 'names[]=System/Memory/Used/bytes&values[]=average_value&from=2014-01-06T18:26:59+00:00&to=2014-01-13T18:26:59+00:00&summarize=true'
This will return JSON data in the following form:
"metrics": [
{
"name": "System/Memory/Used/bytes",
"timeslices": [
{
"from": "2014-01-15T18:26:59+00:00",
"to": "2014-01-15T18:26:59+00:00",
"values": {
"average_value": 7970000000, <---<<<
}
}
]
}
The average_value gives the average value for the time period between the "from" and "to" times. (This is not the complete data return; it is only the relevant section.)
Average swap space used
To obtain the average swap space used on the host for the selected time period, use the metric name System/Swap/Used/bytes and value average_value. For example:
curl -X GET "https://api.newrelic.com/v2/servers/${YOUR_SERVER_ID}/metrics/data.xml" \
-H "X-Api-Key:${YOUR_API_KEY}" -i \
-d 'names[]=System/Swap/Used/bytes&values[]=average_value>&from=2014-01-06T18:26:59+00:00&to=2014-01-13T18:26:59+00:00&summarize=true'
Average total memory and swap available
To find the average memory available for a specified time period, use the metric System/Memory/Used/bytes and the value average_exclusive_time. For example:
curl -X GET "https://api.newrelic.com/v2/servers/${YOUR_SERVER_ID}/metrics/data.xml" \
-H "X-Api-Key:${YOUR_API_KEY}" -i \
-d 'names[]=System/Memory/Used/bytes&values[]=average_exclusive_time&from=2014-01-06T18:26:59+00:00&to=2014-01-13T18:26:59+00:00&summarize=true'
To find the average swap space available for the specified time period, use the metric System/Swap/Used/bytes and the value average_exclusive_time. For example:
curl -X GET "https://api.newrelic.com/v2/servers/${YOUR_SERVER_ID}/metrics/data.xml" \
-H "X-Api-Key:${YOUR_API_KEY}" -i \
-d 'names[]=System/Swap/Used/bytes&values[]=average_exclusive_time&from=2014-01-06T18:26:59+00:00&to=2014-01-13T18:26:59+00:00&summarize=true'
Currently the average_exclusive_time will return values that are a factor of 1000 greater than expected.
Average percentage of memory used
The percentage of memory used in a specified time period is calculated as:
Percent memory used = (average_value / average_exclusive_time) * 100
To obtain the average values needed for this equation for a selected time period, use the metric name System/Memory/Used/bytes and obtain the values average_value and average_exclusive_time. For example:
curl -X GET "https://api.newrelic.com/v2/servers/${YOUR_SERVER_ID}/metrics/data.xml" \
-H "X-Api-Key:${YOUR_API_KEY}" -i \
-d 'names[]=System/Memory/Used/bytes&values[]=average_value&values[]=average_exclusive_time&from=2014-01-06T18:26:59+00:00&to=2014-01-13T18:26:59+00:00&summarize=true'
This will return data in the following form. However, currently the average_exclusive_time will return values that are a factor of 1000 greater than expected. This will cause a problem because that value is used as the denominator in this calculation.
"metrics": [
{
"name": "System/Memory/Used/bytes",
"timeslices": [
{
"from": "2016-06-15T16:00:00+00:00",
"to": "2016-07-15T16:00:00+00:00",
"values": {
"average_value": 7970000000, <---<<<
"average_exclusive_time": 11700000000000 <---<<<
}
}
]
}
]
Value names
The data for total memory available returned by these API calls appears in the average_exclusive_time value. Although this value has time in the title, in this context it indicates bytes.
The mapping for memory metric values are:
<average_value>: Indicates average memory used<average_exclusive_time>: Indicates total memory available
Currently the average_exclusive_time will return values that are a factor of 1000 greater than expected.
Convert bytes (API) to megabytes (UI)
Data stored and returned by the API for average memory used is in bytes, but it appears on the app server's Overview page in terms of megabytes (based on 1024 being a kilobyte). To match the values obtained from your API calls with the values that appear in the UI, use these calculations:
Average used memory = <average_value> / (1024)**2 Total memory = <average_exclusive_time>/ (1024)**2
Currently the average_exclusive_time will return values that are a factor of 1000 greater than expected. This will cause a problem because that value is used as the denominator in this calculation.
For more help
Additional documentation resources include:
- Using the API Explorer (using the API Explorer's user interface to get data in and data out of New Relic)
- Parts of the API Explorer (a quick reference for how to use each section of the API Explorer)