Documentation is now available for the Fall 2020 Update release!

Get metric (time series) on a resource

This endpoint is used to retrieve the details of metric behavior at a certain time period.

Leave Feedback

URL

GET https://{api-url}/api/v2/metric/search?tenant={tenantId}&rtype={rtype}&resource={resource}&metric={metric}&startTime={startTime}&endTime={endTime}&timeseries_type={timeSeriesType}

Sample URLs

To retrieve complete metric data that includes metric values at multiple time series:

https://{api-url}/api/v2/metric/search?tenant=client_20&rtype=DEVICE&resource=ab342123-5bfb-434c-aae4-03611ca020d9&metric=system.cpu.utilization&startTime=1536643494&endTime=1536661494

There are three common examples that show how to retrieve metric data based on a specific time series.

  1. Time series type (RealTime):
https://{api-url}/api/v2/metric/search?tenant=client_20&rtype=DEVICE&resource=ab342123-5bfb-434c-aae4-03611ca020d9&metric=system.cpu.utilization&startTime=1536643494&endTime=1536661494&timeseries_type=RealTime
  1. Time series type (CHANGE_DETECTION):
https://{api-url}/api/v2/metric/search?tenant=client_20&rtype=DEVICE&resource=ab342123-5bfb-434c-aae4-03611ca020d9&metric=system.cpu.utilization&startTime=1536643494&endTime=1536661494&timeseries_type=CHANGE_DETECTION
  1. Time series type (FORECAST):
https://{api-url}/api/v2/metric/search?tenant=client_20&rtype=DEVICE&resource=ab342123-5bfb-434c-aae4-03611ca020d9&metric=system.cpu.utilization&startTime=1536643494&endTime=1536661494&timeseries_type=FORECAST

Query variables

Query VariableDescription
tenatID of the client with which a metric is associated with.
resourceID of the resource on which a metric is assigned.
metricName(Optional) Name of the metric to report the metric details.
startTimeSearch for the metric behavior within a specific time stamp with the start time (use the Unix Epoch Time Stamp format).
Example: 1536643494
endTimeThe end time used for the search (use the Unix Epoch Time Stamp format).
Example: 1536643564
metricGroup(Optional) ID of a metric group to which a metric belongs.
resourceGroup(Optional) ID of resource group the metric is applied. Use Get Minimal Details of Device Groups API to retrieve list of resource groups.
component(Optional) Device component name that the metric is assigned.
timeSeriesType(Optional) Metric behavior at a specific time series pattern. Supported values are:
  • "RealTime": Provides details of metric behavior at current time stamp.
  • "CHANGE_DETECTION": Provides details of significant changes on a metric.
  • "FORECAST": Provides forecast details of a metric.

Data resolution

OpsRamp retains the raw metrics data for the most recent seven. Metric roll-ups are computed every half-hour, hourly, and daily. Calculations performed include average, minimum, maximum, and latest. Based on the selected time range, data is dynamically served in raw and rolled-up formats.

Time RangeResolutionTime Series Sections
Up to 24 hoursRawdata (RAW)
Greater than 24 hours to 3 days30-minute rollupdata (AVG), minVals (MIN), maxVals(MAX) and lastVals(LATEST / LAST)
Greater than 3 days to 30 days1-hour rollupdata (AVG), minVals (MIN), maxVals(MAX) and lastVals(LATEST / LAST)
Greater than 30 days1-day rollupdata (AVG), minVals (MIN), maxVals(MAX) and lastVals(LATEST / LAST)
Using "data=raw" query paramRaw (up to 7 days)data (RAW)

Sample responses

To retrieve metric behavior at multiple time series patterns:

[
{
		"resource": 12327,
		"metric": "system.cpu.utilization",
		"metricType": "Guage",
		"unit": "%",
		"unitLabel": "Percentage (%)",
		"component": "system.cpu.utilization",
		"description": "The percentage of elapsed time that the processor spends to execute a non-Idle thread",
		"consolFunc": "AVERAGE",
		"factor": 1,
		"data": {
			"1536643511": 25,
			"1536643571": 65,
			"1536643631": 63,
			"1536643691": 72,
			"1536643751": 91,
			"1536643811": 21,
			"1536643871": 77,
			"1536643931": 54,
			"1536643991": 50,
			"1536644051": 42
		},
		"timeSeriesType": "RealTime"
	},
	{
		"resource": 12327,
		"metric": "system.cpu.utilization",
		"metricType": "Guage",
		"unit": "%",
		"unitLabel": "Percentage (%)",
		"component": "system.cpu.utilization",
		"description": "The percentage of elapsed time that the processor spends to execute a non-Idle thread",
		"consolFunc": "AVERAGE",
		"factor": 1,
		"data": {
			"1536643511": -88,
			"1536643571": -84,
			"1536643631": -63,
			"1536643691": -14,
			"1536643751": -88,
			"1536643811": -59,
			"1536643871": -90,
			"1536643931": -97,
			"1536643991": -6,
			"1536644051": -90
		},
		"timeSeriesType": "CHANGE_DETECTION"
	},
	{
		"resource": 12327,
		"metric": "system.cpu.utilization",
		"metricType": "Guage",
		"unit": "%",
		"unitLabel": "Percentage (%)",
		"component": "resource.availability",
		"description": "The percentage of elapsed time that the processor spends to execute a non-Idle thread",
		"consolFunc": "AVERAGE",
		"factor": 1,
		"timeSeriesType": "CHANGE_DETECTION"
	},
	{
		"resource": 12327,
		"metric": "system.cpu.utilization",
		"metricType": "Guage",
		"unit": "%",
		"unitLabel": "Percentage (%)",
		"component": "system.cpu.utilization",
		"description": "The percentage of elapsed time that the processor spends to execute a non-Idle thread",
		"consolFunc": "AVERAGE",
		"factor": 1,
		"data": {
			"1536643511": 174,
			"1536643571": 251,
			"1536643631": 268,
			"1536643691": 261,
			"1536643751": 265,
			"1536643811": 172,
			"1536643871": 187,
			"1536643931": 159,
			"1536643991": 286,
			"1536644051": 139
		},
		"timeSeriesType": "FORECAST"
	},
	{
		"resource": 12327,
		"metric": "system.cpu.utilization",
		"metricType": "Guage",
		"unit": "%",
		"unitLabel": "Percentage (%)",
		"component": "resource.availability",
		"description": "The percentage of elapsed time that the processor spends to execute a non-Idle thread",
		"consolFunc": "AVERAGE",
		"factor": 1,
		"timeSeriesType": "FORECAST"
	}
]

To retrieve metric behavior at current time stamp in real time:

[
{
	"resource": 12327,
	"metric": "system.cpu.utilization",
	"metricType": "Guage",
	"unit": "%",
	"unitLabel": "Percentage (%)",
	"component": "system.cpu.utilization",
	"description": "The percentage of elapsed time that the processor spends to execute a non-Idle thread",
	"consolFunc": "AVERAGE",
	"factor": 1,
	"data": {
		"1536643511": 25,
		"1536643571": 65,
		"1536643631": 63,
		"1536643691": 72,
		"1536643751": 91,
		"1536643811": 21,
		"1536643871": 77,
		"1536643931": 54,
		"1536643991": 50,
		"1536644051": 42,
		"1536644111": 77,
		"1536644171": 53,
		"1536644231": 47,
		"1536644291": 26,
		"1536644351": 58,
		"1536644411": 84,
		"1536644471": 26,
		"1536644531": 97,
		"1536644591": 66,
		"1536644651": 88,
		"1536644711": 68,
		"1536644771": 67
	},
	"timeSeriesType": "RealTime"
}
]

To retrieve significant changes on a metric (using CHANGE_DETECTION):

[{
		"resource": 12327,
		"metric": "system.cpu.utilization",
		"metricType": "Guage",
		"unit": "%",
		"unitLabel": "Percentage (%)",
		"component": "system.cpu.utilization",
		"description": "The percentage of elapsed time that the processor spends to execute a non-Idle thread",
		"consolFunc": "AVERAGE",
		"factor": 1,
		"data": {
			"1536643511": -88,
			"1536643571": -84,
			"1536643631": -63,
			"1536643691": -14,
			"1536643751": -88,
			"1536643811": -59,
			"1536643871": -90,
			"1536643931": -97,
			"1536643991": -6,
			"1536644051": -90,
			"1536644111": -15,
			"1536644171": -11,
			"1536644231": -94,
			"1536644291": -66,
			"1536644351": -96,
			"1536644411": -15,
			"1536644471": -12,
			"1536644531": -63,
			"1536644591": -41,
			"1536644651": -23,
			"1536644711": -66,
			"1536644771": -24,
			"1536644831": -31,
			"1536644891": -71,
			"1536644951": -17,
			"1536645011": -36,
			"1536645071": -28,
			"1536645131": -33,
			"1536645191": -72,
			"1536645251": -35
		},
		"timeSeriesType": "CHANGE_DETECTION"
	},
	{
		"resource": 12327,
		"metric": "system.cpu.utilization",
		"metricType": "Guage",
		"unit": "%",
		"unitLabel": "Percentage (%)",
		"component": "resource.availability",
		"description": "The percentage of elapsed time that the processor spends to execute a non-Idle thread",
		"consolFunc": "AVERAGE",
		"factor": 1,
		"timeSeriesType": "CHANGE_DETECTION"
	}
]

To forecast values of a metric (using FORECAST):

[{
		"resource": 12327,
		"metric": "system.cpu.utilization",
		"metricType": "Guage",
		"unit": "%",
		"unitLabel": "Percentage (%)",
		"component": "system.cpu.utilization",
		"description": "The percentage of elapsed time that the processor spends to execute a non-Idle thread",
		"consolFunc": "AVERAGE",
		"factor": 1,
		"data": {
			"1536643511": 174,
			"1536643571": 251,
			"1536643631": 268,
			"1536643691": 261,
			"1536643751": 265,
			"1536643811": 172,
			"1536643871": 187,
			"1536643931": 159,
			"1536643991": 286,
			"1536644051": 139,
			"1536644111": 177,
			"1536644171": 174,
			"1536644231": 245,
			"1536644291": 274,
			"1536644351": 181,
			"1536644411": 196,
			"1536644471": 233,
			"1536644531": 251,
			"1536644591": 295,
			"1536644651": 171,
			"1536644711": 124,
			"1536644771": 172,
			"1536644831": 184,
			"1536644891": 282,
			"1536644951": 153,
			"1536645011": 261,
			"1536645071": 221
		},
		"timeSeriesType": "FORECAST"
	},
	{
		"resource": 12327,
		"metric": "system.cpu.utilization",
		"metricType": "Guage",
		"unit": "%",
		"unitLabel": "Percentage (%)",
		"component": "resource.availability",
		"description": "The percentage of elapsed time that the processor spends to execute a non-Idle thread",
		"consolFunc": "AVERAGE",
		"factor": 1,
		"timeSeriesType": "FORECAST"
	}
]

Roll-ups enables the viewing of metric behavior in wider time spans.

When OpsRamp receives data points for a given time series, this data is accumulated for specific periods of time. This data is stored in four roll-ups for each interval: average, minimum, maximum, and latest.

To retrieve metric data for a roll-up time series:

[{
		"resource": 4455803,
		"metric": "system.disk.used",
		"metricType": "Guage",
		"unit": "GB",
		"unitLabel": "Utilization",
		"component": "c",
		"description": "Used space on the selected logical disk drive",
		"consolFunc": "AVERAGE",
		"factor": 1.073741824E9,
		"data": {
			"1464332400": 9.3299147E10,
			"1464336000": 9.329949633333333E10,
			"1464339600": 9.3296001E10,
			"1464343200": 9.329189433333333E10,
			"1464346800": 9.3301768E10,
			"1464350400": 9.329687508333333E10,
			"1464354000": 9.330185533333333E10,
			"1464357600": 9.330779758333333E10,
			"1464361200": 9.3306749E10,
			"1464364800": 9.317742475E10,
			"1464368400": 9.308951883333333E10,
			"1464372000": 9.30877715E10
		},
		"minVals": {
			"1464332400": 9.3299147E10,
			"1464336000": 9.3299147E10,
			"1464339600": 9.3291807E10,
			"1464343200": 9.3291807E10,
			"1464346800": 9.3296001E10,
			"1464350400": 9.3296001E10,
			"1464354000": 9.3298098E10,
			"1464357600": 9.3303341E10,
			"1464361200": 9.330439E10,
			"1464364800": 9.3078946E10,
			"1464368400": 9.3081043E10,
			"1464372000": 9.3084189E10
		},
		"maxVals": {
			"1464332400": 9.3299147E10,
			"1464336000": 9.3300195E10,
			"1464339600": 9.3300195E10,
			"1464343200": 9.3292855E10,
			"1464346800": 9.3303341E10,
			"1464350400": 9.3298098E10,
			"1464354000": 9.3305438E10,
			"1464357600": 9.331173E10,
			"1464361200": 9.3308584E10,
			"1464364800": 9.3314875E10,
			"1464368400": 9.3113549E10,
			"1464372000": 9.3091529E10
		},
		"lastVals": {
			"1464332400": 9.3299147E10,
			"1464336000": 9.3300195E10,
			"1464339600": 9.3291807E10,
			"1464343200": 9.3292855E10,
			"1464346800": 9.3296001E10,
			"1464350400": 9.3298098E10,
			"1464354000": 9.3305438E10,
			"1464357600": 9.3303341E10,
			"1464361200": 9.3308584E10,
			"1464364800": 9.3079994E10,
			"1464368400": 9.31125E10,
			"1464372000": 9.3086286E10
		},
		"timeSeriesType": "CHANGE_DETECTION"
	},
	{
		"resource": 4455803,
		"metric": "system.disk.used",
		"metricType": "Guage",
		"unit": "GB",
		"unitLabel": "Utilization",
		"component": "e",
		"description": "Used space on the selected logical disk drive",
		"consolFunc": "AVERAGE",
		"factor": 1.073741824E9,
		"data": {
			"1464332400": 1.4524367933333334E11,
			"1464336000": 1.45233543E11,
			"1464339600": 1.4523992208333334E11,
			"1464343200": 1.4525320416666666E11,
			"1464346800": 1.4524306775E11,
			"1464350400": 1.4525442708333334E11,
			"1464354000": 1.4525014575E11,
			"1464357600": 1.4525993241666666E11,
			"1464361200": 1.4526447591666666E11,
			"1464364800": 1.4527469975E11,
			"1464368400": 1.4535744991666666E11,
			"1464372000": 1.4534224566666666E11
		},
		"minVals": {
			"1464332400": 1.45242456E11,
			"1464336000": 1.45229873E11,
			"1464339600": 1.45236165E11,
			"1464343200": 1.45229873E11,
			"1464346800": 1.45234067E11,
			"1464350400": 1.4525399E11,
			"1464354000": 1.45241407E11,
			"1464357600": 1.45237213E11,
			"1464361200": 1.45257136E11,
			"1464364800": 1.45244553E11,
			"1464368400": 1.45346265E11,
			"1464372000": 1.45336828E11
		},
		"maxVals": {
			"1464332400": 1.45245602E11,
			"1464336000": 1.45257136E11,
			"1464339600": 1.45240359E11,
			"1464343200": 1.45257136E11,
			"1464346800": 1.45251893E11,
			"1464350400": 1.45256088E11,
			"1464354000": 1.45257136E11,
			"1464357600": 1.45270768E11,
			"1464361200": 1.45269719E11,
			"1464364800": 1.45344168E11,
			"1464368400": 1.45363042E11,
			"1464372000": 1.45359897E11
		},
		"lastVals": {
			"1464332400": 1.45244553E11,
			"1464336000": 1.4523197E11,
			"1464339600": 1.45240359E11,
			"1464343200": 1.45256088E11,
			"1464346800": 1.45250845E11,
			"1464350400": 1.45256088E11,
			"1464354000": 1.45256088E11,
			"1464357600": 1.4523931E11,
			"1464361200": 1.4526867E11,
			"1464364800": 1.45344168E11,
			"1464368400": 1.45356751E11,
			"1464372000": 1.45341022E11
		},
		"timeSeriesType": "FORECAST"
	},
	{
		"resource": 4455803,
		"metric": "system.disk.used",
		"metricType": "Guage",
		"unit": "GB",
		"unitLabel": "Utilization",
		"component": "c",
		"description": "Used space on the selected logical disk drive",
		"consolFunc": "AVERAGE",
		"factor": 1.073741824E9,
		"data": {
			"1464332400": 9.3299147E10,
			"1464336000": 9.329949633333333E10,
			"1464339600": 9.3296001E10,
			"1464343200": 9.329189433333333E10,
			"1464346800": 9.3301768E10,
			"1464350400": 9.329687508333333E10,
			"1464354000": 9.330185533333333E10,
			"1464357600": 9.330779758333333E10,
			"1464361200": 9.3306749E10,
			"1464364800": 9.317742475E10,
			"1464368400": 9.308951883333333E10,
			"1464372000": 9.30877715E10
		},
		"minVals": {
			"1464332400": 9.3299147E10,
			"1464336000": 9.3299147E10,
			"1464339600": 9.3291807E10,
			"1464343200": 9.3291807E10,
			"1464346800": 9.3296001E10,
			"1464350400": 9.3296001E10,
			"1464354000": 9.3298098E10,
			"1464357600": 9.3303341E10,
			"1464361200": 9.330439E10,
			"1464364800": 9.3078946E10,
			"1464368400": 9.3081043E10,
			"1464372000": 9.3084189E10
		},
		"maxVals": {
			"1464332400": 9.3299147E10,
			"1464336000": 9.3300195E10,
			"1464339600": 9.3300195E10,
			"1464343200": 9.3292855E10,
			"1464346800": 9.3303341E10,
			"1464350400": 9.3298098E10,
			"1464354000": 9.3305438E10,
			"1464357600": 9.331173E10,
			"1464361200": 9.3308584E10,
			"1464364800": 9.3314875E10,
			"1464368400": 9.3113549E10,
			"1464372000": 9.3091529E10
		},
		"lastVals": {
			"1464332400": 9.3299147E10,
			"1464336000": 9.3300195E10,
			"1464339600": 9.3291807E10,
			"1464343200": 9.3292855E10,
			"1464346800": 9.3296001E10,
			"1464350400": 9.3298098E10,
			"1464354000": 9.3305438E10,
			"1464357600": 9.3303341E10,
			"1464361200": 9.3308584E10,
			"1464364800": 9.3079994E10,
			"1464368400": 9.31125E10,
			"1464372000": 9.3086286E10
		},
		"timeSeriesType": "RealTime"
	}
]