Oracle Management Cloud Common REST API

Get metric timeseries

get

/serviceapi/entityModel/uds/metrics

Retrieves Metric data in a given time series.

The defined time series can be either raw data points, aggregated data over a time interval, or split intervals defined by the number of periods in seconds.

Time series follow the format: YYYY-MM-DDTHH:MM:SS.SSSZ

Supported functions:

STDDEV
MAX
MEDIAN
MIN
PERCENTILE_DISC
LAST_VALUE
FIRST_VALUE
AVG

Request

Supported Media Types

application/json

Query Parameters

dimension(optional): array

Collection Format: multi

dimension

[0]: string

{
    "name":"dimension",
    "in":"query",
    "description":"dimension",
    "required":false,
    "type":"array",
    "items":{
        "type":"string"
    },
    "collectionFormat":"multi",
    "x-example":"cpuId=1"
}

endTime: string

the end time
entityName: string

the entity name
entityType: string

the entity type
function(optional): string

the aggregate function
limit(optional): integer(int32)

the number of entries in the result to be returend in one REST call

Default Value: 2000
metric: string

the metric
metricGroup(optional): string

the metric group
offset(optional): integer(int32)

the offset into the result list when doing a query with limit

Default Value: 0
period(optional): string

the period for aggregation in seconds
startTime: string

the start time

Response

Supported Media Types

application/json

200 Response

successful operation

Root Schema : UdsTimeseries

Type: object

Describes a metric Timeseries.

Show Source

dataPoints: array dataPoints

The data points of the metric query
dimension(optional): object dimension

Additional Properties Allowed: additionalProperties

The dimension
endTime: string

The end time

Example: 2018-06-23T18:44:30
entityName: string

The entity name

Example: my_entity_name
entityType: string

The entity type

Example: my_entity_type
function(optional): string

Allowed Values: [ "MAX", "MIN", "AVG", "MEDIAN", "STDDEV" ]

The aggregate function

Example: MIN
metric: string

The metric

Example: my_metric
metricGroup(optional): string

The metric group

Example: my_metric_group
period(optional): integer(int64)

The aggregate time period in seconds

Example: 30
startTime: string

The start time

Example: 2018-06-23T17:35:00

{
    "type":"object",
    "required":[
        "dataPoints",
        "endTime",
        "entityName",
        "entityType",
        "metric",
        "startTime"
    ],
    "properties":{
        "dataPoints":{
            "type":"array",
            "description":"The data points of the metric query",
            "items":{
                "type":"array",
                "items":{
                    "type":"object"
                }
            }
        },
        "dimension":{
            "type":"object",
            "description":"The dimension",
            "additionalProperties":{
                "type":"string"
            }
        },
        "endTime":{
            "type":"string",
            "example":"2018-06-23T18:44:30",
            "description":"The end time"
        },
        "entityName":{
            "type":"string",
            "example":"my_entity_name",
            "description":"The entity name"
        },
        "entityType":{
            "type":"string",
            "example":"my_entity_type",
            "description":"The entity type"
        },
        "function":{
            "type":"string",
            "example":"MIN",
            "description":"The aggregate function",
            "enum":[
                "MAX",
                "MIN",
                "AVG",
                "MEDIAN",
                "STDDEV"
            ]
        },
        "metric":{
            "type":"string",
            "example":"my_metric",
            "description":"The metric"
        },
        "metricGroup":{
            "type":"string",
            "example":"my_metric_group",
            "description":"The metric group"
        },
        "period":{
            "type":"integer",
            "format":"int64",
            "example":30,
            "description":"The aggregate time period in seconds"
        },
        "startTime":{
            "type":"string",
            "example":"2018-06-23T17:35:00",
            "description":"The start time"
        }
    },
    "description":"<p>Describes a metric Timeseries.</p>"
}

Nested Schema : dataPoints

Type: array

The data points of the metric query

Show Source

Array of: array items

{
    "type":"array",
    "description":"The data points of the metric query",
    "items":{
        "type":"array",
        "items":{
            "type":"object"
        }
    }
}

Nested Schema : dimension

Type: object

Additional Properties Allowed

Show Source

string

{
    "type":"object",
    "description":"The dimension",
    "additionalProperties":{
        "type":"string"
    }
}

The dimension

Nested Schema : items

Type: array

Show Source

Array of: object items

{
    "type":"array",
    "items":{
        "type":"object"
    }
}

Nested Schema : items

Type: object

Examples

There are multiple possibilities to retrieve metric data by time series. In all cases the result is a list of time points in the following format:

{
  "entityType": "myHostType",
  "entityName": "myHostEntity",
  "metric": "cpuUser",
  "dimension": {
    "cpuId": "0"
  },
  "startTime": "2018-10-11T01:00:00.000Z",
  "endTime": "2018-10-12T12:00:00.000Z",
  "dataPoints": [
    [
      "2018-10-11T13:14:15.001Z",
      20
    ]
  ],
  "function": "AVG",
  "period": 300
}

In the above function, period and dimension are only returned if these options are used. See the following example use cases:

Get all time points from a single entity:

curl -u ${OMC_USERNAME}:${PASSWORD} -X GET "https://serverurl/serviceapi/entityModel/uds/metrics?entityType=myHostType&entityName=myHostEntity&startTime=2018-10-11T01:00:00.000Z&endTime=2018-10-12T12:00:00.000Z&metric=cpuUser"

The output shows two results:

{
  "entityType": "myHostType",
  "entityName": "myHostEntity",
  "metric": "cpuUser",
  "startTime": "2018-10-11T01:00:00.000Z",
  "endTime": "2018-10-12T12:00:00.000Z",
  "dataPoints": [
    [
      "2018-10-11T13:14:15.001Z",
      20
    ],
    [
      "2018-10-11T13:14:15.001Z",
      10
    ]
  ]
}

Get all time points for a given dimension cpuId=0:

curl -u ${OMC_USERNAME}:${PASSWORD} -X GET "https://serverurl/serviceapi/entityModel/uds/metrics?entityType=myHostType&entityName=myHostEntity&startTime=2018-10-11T01:00:00.000Z&endTime=2018-10-12T12:00:00.000Z&metric=cpuUser&dimension=cpuId=0"

The result shows the dimension and a single data point:

{
  "entityType": "myHostType",
  "entityName": "myHostEntity",
  "metric": "cpuUser",
  "dimension": {
    "cpuId": "0"
  },
  "startTime": "2018-10-11T01:00:00.000Z",
  "endTime": "2018-10-12T12:00:00.000Z",
  "dataPoints": [
    [
      "2018-10-11T13:14:15.001Z",
      20
    ]
  ]
}

Get the aggregated average in dimension cpuId=0 in a one day interval:

curl -u ${OMC_USERNAME}:${PASSWORD} -X GET "https://serverurl/serviceapi/entityModel/uds/metrics?entityType=myHostType&entityName=myHostEntity&startTime=2018-10-11T01:00:00.000Z&endTime=2018-10-12T12:00:00.000Z&metric=cpuUser&dimension=cpuId=0&function=AVG"

The result shows the dimension and the function used:

{
  "entityType": "myHostType",
  "entityName": "myHostEntity",
  "metric": "cpuUser",
  "dimension": {
    "cpuId": "0"
  },
  "startTime": "2018-10-11T01:00:00.000Z",
  "endTime": "2018-10-12T12:00:00.000Z",
  "dataPoints": [
    [
      "2018-10-11T13:14:15.001Z",
      20
    ]
  ],
  "function": "AVG"
}

Get the aggregated average in intervals of 600 seconds:

curl -u ${OMC_USERNAME}:${PASSWORD} -X GET "https://serverurl/serviceapi/entityModel/uds/metrics?entityType=myHostType&entityName=myHostEntity&startTime=2018-10-11T01:00:00.000Z&endTime=2018-10-12T12:00:00.000Z&metric=cpuUser&dimension=cpuId=0&function=AVG&period=600"

The result shows that there are two data points, one at 13:15:00 and the other at 13:20:00:

{
  "entityType": "myHostType",
  "entityName": "myHostEntity",
  "metric": "cpuUser",
  "dimension": {
    "cpuId": "0"
  },
  "startTime": "2018-10-11T01:00:00.000Z",
  "endTime": "2018-10-12T12:00:00.000Z",
  "dataPoints": [
    [
      "2018-10-11T13:15:00.000Z",
      23
    ],
    [
      "2018-10-11T13:20:00.000Z",
      44
    ]
  ],
  "function": "AVG",
  "period": 300
}