Elements API

About the Elements API

CloudWisdom’s Elements API can be used to create, edit, delete and review elements. Users can also update tags and policies associated with these elements. You can test these endpoints by visiting our Swagger page and by clicking the interactive buttons below.

POST Use this endpoint to find a count of objects based on the fields chosen for aggregation.

Parameters

Parameter

Parameter Type

Data Type

Description

term

path

string

The element field you want to aggregate

elasticsearchQuery

body

JSON

A JSON query

Request URL

https://app.metricly.com/elements/elasticsearch/elementAgg/{term}

CURL

In the following CURL example the term is defined in the request URL as elementType. This means the response body returns a list of element types with totals for each type which match the search criteria. In this example, we are searching for element types that contain west in the element name.

Tip

The term is the field we are looking to find aggregate counts for. Options are elementType for element types, attributes for element attributes ,tags for element tags, and collectors.name for element collectors.

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{ \
   "page": 0, \
   "pageSize": 100, \
   "startDate": "2020-01-27T12:33:28-05:00", \
   "endDate": "2020-01-27T13:33:28-05:00", \
   "elementNames": { \
     "and": false, \
     "items": [ \
       { \
         "literal": false, \
         "contains": true, \
         "item": "west" \
       } \
     ] \
   } \
 }' 'https://app.metricly.com/elements/elasticsearch/elementAgg/elementType'

Swagger Payload

You can use the following template to test this endpoint with Swagger. Select the method icon to open this specific endpoint.

{
   "page": 0,
   "pageSize": 100,
   "startDate": "2020-01-27T12:33:28-05:00",
   "endDate": "2020-01-27T13:33:28-05:00",
   "elementNames": {
     "and": false,
     "items": [
       {
         "literal": false,
         "contains": true,
         "item": "west"
       }
     ]
   }
 }

Response Body

The following response body found 6 total elements with names that contain west in their elementName: 5 S3 buckets and 1 RDS element.

{
  "aggregations": [
    {
      "fieldValue": "S3 Bucket",
      "count": 5
    },
    {
      "fieldValue": "RDS",
      "count": 1
    }
  ]
}

POST Use this endpoint to query elements by datasource, type, and more. Supports filtering.

Parameters

Parameter

Parameter Type

Data Type

Description

elasticsearchQuery

body

JSON

A JSON query.

Request URL

https://app.metricly.com/elements/elasticsearch/elementQuery

CURL

The following CURL example submits a query to find elements of the EC2 type. This example filters metrics and attributes out from the response body.

Tip

The items key here is contextual to its parent object. In this example, an item is the value of an elementType key (EC2). You can search for elementFQNs, elementIds, elementNames —but the items value changes for each. If the response body returns "totalElements": 0, verify that you are submitting an item value matching its parent object.

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{  "sort": { \
     "field": "name", \
     "order": "asc", \
     "missing": "_last" \
   }, \
   "page": 0, \
   "pageSize": 35, \
   "startDate": "2020-01-24T01:00:00-05:00", \
   "endDate": "2020-01-24T02:00:00-05:00", \
   "elementTypes": { \
     "and": false, \
     "items": [ \
       { \
         "literal": true, \
         "contains": true, \
         "item": "EC2" \
       } \
     ] \
   }, \
   "sourceFilter": { \
     "excludes": [ \
       "metrics", \
       "attributes" \
     ] \
   } \
 }' 'https://app.metricly.com/elements/elasticsearch/elementQuery'

Swagger Payload

You can use the following template to test this endpoint with Swagger. Select the method icon to open this specific endpoint.

{  "sort": {
     "field": "name",
     "order": "asc",
     "missing": "_last"
   },
   "page": 0,
   "pageSize": 35,
   "startDate": "2020-01-24T01:00:00-05:00",
   "endDate": "2020-01-24T02:00:00-05:00",
   "elementTypes": {
     "and": false,
     "items": [
       {
         "literal": true,
         "contains": true,
         "item": "EC2"
       }
     ]
   },
   "sourceFilter": {
     "excludes": [
       "metrics",
       "attributes"
     ]
   }
 }

Response Body

{
  "page": {
    "content": [
      {
        "netuitiveTags": {
          "n.analysis.status": null
        },
        "sourceTags": {
          "Name": "test-element-abc1",
          "n.collectors": "EC2"
        },
        "state": {
          "netuitive.metrics.collected.percent": null
        },
        "eventCount": {
          "total": 0,
          "topCategory": null
        },
        "relations": [
          {
            "id": 11a031a5-011a-3976-84be-d0d1cbe281fe",
            "dataSourceId": 31845,
            "fqn": "501119301101:EBS:us-east-1:vol-01ab111bfa2c63111"
          }
        ],
        "fqn": "11179301106:EC2:us-east-1:i-011adb1a4a45ab111",
        "name": "Testing (10.13.10.83)",
        "location": "us-east-1c",
        "id": "91bb19b6-012c-1111-aede-dda4e12c111a",
        "type": "EC2"
      },
      {
        "netuitiveTags": {
          "n.analysis.status": null,
          "n.backfill.status": "false",
          "n.state.maintenance": "false",
          "n.state.maintenance_end": "-1"
        },
        "sourceTags": {
          "Name": "Netuitive-colo: Domain Controller",
          "app": "hq",
          "n.collectors": "EC2"
        },
        "state": {
          "netuitive.metrics.collected.percent": 100
        },
        "eventCount": {
          "total": 0,
          "topCategory": null
        },
        "relations": [
          {
            "id": "c6ccd4ac-ea3f-11be-ac98-11112aecf04c",
            "dataSourceId": 31845,
            "fqn": "502111101106:EBS:us-east-1:vol-9eba111e"
          }
        ],
        "fqn": "112111101106:EC2:us-east-1:i-b4e87f28",
        "lastProcessed": "2020-01-26T16:50:00Z",
        "name": "Domain Controller (10.14.11.30)",
        "location": "us-east-1a",
        "id": "c48df6c2-111c-3542-11be-17b0472a7d12",
        "type": "EC2"
      },     
    ],
    "last": true,
    "totalElements": 2,
    "totalPages": 1,
    "sort": null,
    "first": true,
    "numberOfElements": 2,
    "size": 35,
    "number": 0
  }
}

POST Use this endpoint to preview custom display names for elements within the CloudWisdom UI.

Parameter

Parameter Type

Data Type

Description

elementTemplate

Body

JSON

A naming template to preview using an element of your choice.

Request URL

https://app.metricly.com/elements/name/preview

CURL

The following CURL example displays the element’s name, location, and type. See Element Display Name page for more display options.

Tip

This endpoint requires an elementId. You can obtain an elementId using the /elements/elasticsearch/elementQuery endpoint. See this page for more information on obtaining an elementId.

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{ \
   "elementId": "095a50a0-2b5c-3eb9-b25b-48f81de11038", \
   "template": "${tags.Name} ${meta.location} ${meta.type}" \
 }' 'https://app.metricly.com/elements/name/preview'

Swagger Payload

You can use the following template to test this endpoint with Swagger. Select the method icon to open this specific endpoint.{

{
   "elementId": "095a50a0-2b5c-3eb9-b25b-48f81de11038",
   "template": "${tags.Name} ${meta.location} ${meta.type}"
 }

Response Body

The following response body prints a preview of the element name created by merging ${tags.Name}, ${meta.location}, and ${meta.type}.

{
  "preview": "Element-Name us-east-1c EBS"
}

GET Use this endpoint to obtain one or many metric details associated to an element.

Parameters

Parameter

Parameter Type

Data Type

Description

elementId

path

string

Element Ids can be found in by selecting an element in CloudWisdom and viewing the URL (/#/inventory/6bdf4fd1-1111-1111-1c11-17eb5f628e46).

metricFQN

query

string

The metricFQN can be found by viewing metrics in CloudWisdom.

Request URL

https://app.metricly.com/elements/{elementId}/metrics

CURL

The following CURL example returns a list of all metrics associated to the elementId.

curl -X GET --header 'Accept: application/json' 'https://app.metricly.com/elements/11110956-1111-392f-adbe-71c11115bd40/metrics'

The following CURL example returns the aws.ec2.networkpacketsout metric associated to the elementId.

curl -X GET --header 'Accept: application/json' 'https://app.metricly.com/elements/11110956-1111-392f-adbe-71c11115bd40/metrics?metricFQN=aws.ec2.networkpacketsout'

Response Body

The following response body returns one metric, but many metrics can be returned.

{
  "id": "21110956-1111-392f-adbe-71c81115bd40",
  "metricMeta": [
    {
      "id": "bb2116ed-2868-3c76-b1b6-a4111a4eda2f",
      "fqn": "aws.ec2.networkpacketsout",
      "state": {
        "baselined": true,
        "created": "2017-10-02T13:57:06Z",
        "lastResults": {
          "actual": 5.6,
          "avg": 5.6,
          "min": 4,
          "max": 7,
          "baselineMean": 31.103688690165836,
          "cnt": 5,
          "sum": 28,
          "baselineStddev": 115.32111156038707,
          "baselineUpper": 492.3881349317141,
          "baselineLower": 0
        },
        "historicalMin": 0.8,
        "lastActual": 669.4,
        "updated": "2019-12-20T03:10:00Z",
        "correlated": false,
        "historicalMax": 288606
      },
      "configuration": {
        "validmax": null,
        "sparsedatastrategy": "None",
        "validmin": 0
      }
    }
  ]
}

GET Use this endpoint to grab metric samples in a given rollup frequency for a specific period of time.

Parameters

Parameter

Parameter Type

Data Type

Description

elementId

Path

String

Element Ids can be found in by selecting an element in CloudWisdom and viewing the URL (/#/inventory/6bdf4fd1-1111-1111-1c11-17eb5f628e46)

metricId

Path

String

Metric Ids can be found by viewing metrics in CloudWisdom.

duration

Path

String

Follows ISO8601 duration format. Example options include: PT1h, PT1m, PT10s, P3D.

startTime

Path

Date-Time

Start time for the query. YYYY-MM-DDT00:001Z format (must include time zone).

endTime

Path

Date-Time

End time for the query. YYYY-MM-DDT00:001Z format (must include time zone).

rollup

Path

Array[string]

Determines frequency of metric sampling. Options are: ZERO, PT5M, PT1H, PT24H.

Request URL

https://app.metricly.com/elements/{elementId}/metrics/{metricId}/samples?

CURL

The following CURL example includes a Duration of PT30M and Rollup value of PT5M.

curl -X GET --header 'Accept: application/json' 'https://app.metricly.com/elements/24661111-1111-1111-adbe-71c85255bd40/metrics/bb1111ed-1111-3c76-b1b6-a4111a4eda2f/samples?duration=PT30m&rollup=PT5M'

Response Body

The following response body contains 5 metric samples for the metricIdbb1111ed-1111-3c76-b1b6-a1111a4eda2f.

{
  "samples": [
    {
      "metricId": "bb1111ed-1111-3c76-b1b6-a1111a4eda2f",
      "timestamp": "2019-12-20T16:25:00Z",
      "rollup": "PT5M",
      "data": {
        "actual": 10.2,
        "avg": 10.2,
        "min": 9,
        "max": 13,
        "baselineMean": 53.129704892436585,
        "cnt": 5,
        "sum": 51,
        "baselineStddev": 145.18387878356057,
        "baselineUpper": 633.8652200266789,
        "baselineLower": 0
      }
    },
    {
      "metricId": "bb1111ed-1111-3c76-b1b6-a1111a4eda2f",
      "timestamp": "2019-12-20T16:30:00Z",
      "rollup": "PT5M",
      "data": {
        "actual": 11.6,
        "avg": 11.6,
        "min": 10,
        "max": 13,
        "baselineMean": 52.819651418304396,
        "cnt": 5,
        "sum": 58,
        "baselineStddev": 143.5165646715427,
        "baselineUpper": 626.8859101044752,
        "baselineLower": 0
      }
    },
    {
      "metricId": "bb1111ed-1111-3c76-b1b6-a1111a4eda2f",
      "timestamp": "2019-12-20T16:35:00Z",
      "rollup": "PT5M",
      "data": {
        "actual": 10.8,
        "avg": 10.8,
        "min": 10,
        "max": 12,
        "baselineMean": 52.45982914038505,
        "cnt": 5,
        "sum": 54,
        "baselineStddev": 141.77574214465326,
        "baselineUpper": 619.5627977189981,
        "baselineLower": 0
      }
    },
    {
      "metricId": "bb1111ed-1111-3c76-b1b6-a1111a4eda2f",
      "timestamp": "2019-12-20T16:40:00Z",
      "rollup": "PT5M",
      "data": {
        "actual": 9.8,
        "avg": 9.8,
        "min": 9,
        "max": 11,
        "baselineMean": 53.09643273302771,
        "cnt": 5,
        "sum": 49,
        "baselineStddev": 141.27593059022965,
        "baselineUpper": 618.2001550939463,
        "baselineLower": 0
      }
    },
    {
      "metricId": "bb1111ed-1111-3c76-b1b6-a1111a4eda2f",
      "timestamp": "2019-12-20T16:45:00Z",
      "rollup": "PT5M",
      "data": {
        "actual": 10.4,
        "avg": 10.4,
        "min": 9,
        "max": 12,
        "baselineMean": 53.57279368703339,
        "cnt": 5,
        "sum": 52,
        "baselineStddev": 146.9486822676629,
        "baselineUpper": 641.3675227576849,
        "baselineLower": 0
      }
    }
  ]
}

GET Use this endpoint to get a list of tags associated to a specified metric for a given element.

Parameters

Parameter

Parameter Type

Data Type

Description

elementId

Path

String

Element Ids can be found in by selecting an element in CloudWisdom and viewing the URL (/#/inventory/6bdf4fd1-1111-1111-1c11-17eb5f628e46)

metricId

Path

String

Metric Ids can be found by viewing metrics in CloudWisdom.

Request URL

https://app.metricly.com/elements/{elementId}/metrics/{metricId}/tags

CURL

The following CURL example includes the required elementId and metricId.

  • You can find an elementId while viewing a metric in CloudWisdom by selecting the Card Title > Element Detail.

  • You can find metricIds for an element in your inventory by selecting the Card Title > View all Metrics for this Element.

curl -X GET --header 'Accept: application/json' 'https://app.metricly.com/elements/6bdf4fd1-7134-3959-9c36-17eb5f628e46/metrics/3a1a2fb7-b274-3120-84bd-d7781401894f/tags'

Response Body

The following response body returns a list of tags for the specified metricId. Notice how the response lists tags added from CloudWisdom (netuitiveTags) and from AWS (sourceTags).

{
  "netuitiveTags": {
    "n.statistic": "AVG"
  },
  "sourceTags": {
    "awsDimensions": "{\"LoadBalancer\":\"app/bamboo/5f973fddb1e0c653\"}",
    "awsNamespace": "AWS/ApplicationELB"
  }
}

POST Use this endpoint to post new tags (key-value pairs) to a specified metric.

Parameters

Parameter

Parameter Type

Data Type

Description

User-Agent

Header

String

Default value: none.

elementId

Path

String

Element Ids can be found in by selecting an element in CloudWisdom and viewing the URL ( /#/inventory/6bdf4fd1-1111-1111-1c11-17eb5f628e46)

metricId

Path

String

Metric Ids can be found by viewing metrics in CloudWisdom.

tagWrapper

Body

JSON

Inject a new tag using JSON: “tag-name”:“tag-value”.

Request URL

https://app.metricly.com/elements/{elementId}/metrics/{metricId}/tags

The following CURL example creates the key Color and tag value Blue, associated to the metric specified in the Request URL.

CURL

The following CURL example creates the key Color and tag value Blue, associated to the metric specified in the Request URL.

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'User-Agent: none' -d '{ \
   "netuitiveTag":  \
 { "Color":"Blue"} \
 }' 'https://app.metricly.com/elements/6bdf4fd1-7134-3959-9c36-17eb5f628e46/metrics/3a1a2fb7-b274-3120-84bd-d7781401894f/tags'

Swagger Payload

You can use the following template to test this endpoint with Swagger. Select the method icon to open this specific endpoint.

{
   "netuitiveTag":{
     "Color":"Blue"
   }
 }

Response Body

The following response body returns confirmation that the key:value pair has been created and assigned.

{
  "netuitiveTag": {
    "Color": "Blue"
  }
}

PUT Use this endpoint to update the value of a tag for a specified metric.

Parameters

Parameter

Parameter Type

Data Type

Description

User-Agent

header

string

Default value: none.

elementId

path

string

Element Ids can be found in by selecting an element in CloudWisdom and viewing the URL ( /#/inventory/6bdf4fd1-1111-1111-1c11-17eb5f628e46)

metricId

path

string

Metric Ids can be found by viewing metrics in CloudWisdom.

tagName

path

string

Use this value to update the existing tag.

tagWrapper

body

JSON

Inject a new tag using JSON: “tag-name”:“tag-value”.

Request URL

https://app.metricly.com/elements/{elementId}/metrics/{metricId}/tags/{tagName}

CURL

The following CURL example changes the previously created Color tag’s value to Red. Notice that you must specify the tagName (key) at the end of the Request URL.

curl -X PUT --header 'Content-Type: application/json' --header 'Accept: */*' --header 'User-Agent: none' -d '{ \
   "netuitiveTag":  \
 { "Color":"Red"} \
 }' 'https://app.metricly.com/elements/6bdf4fd1-7134-3959-9c36-17eb5f628e46/metrics/3a1a2fb7-b274-3120-84bd-d7781401894f/tags/Color'

Swagger Payload

You can use the following template to test this endpoint with Swagger. Select the method icon to open this specific endpoint.

{
   "netuitiveTag":{
    "Color":"Red"
  }
 }

Response Body

The following response body has no content; this is typical for a successful call.

No Content

DELETE Use this endpoint to delete a tag (key) from a specified metric.

Parameters

Parameter

Parameter Type

Data Type

Description

User-Agent

header

string

Default value: none.

elementId

path

string

Element Ids can be found in by selecting an element in CloudWisdom and viewing the URL ( /#/inventory/6bdf4fd1-1111-1111-1c11-17eb5f628e46).

metricId

path

string

Metric Ids can be found by viewing metrics in CloudWisdom.

tag

path

string

Used to specify which tag to delete.

Request URL

https://app.metricly.com/elements/{elementId}/metrics/{metricId}/tags/{tagName}

CURL

The following CURL example deletes the Color tag used in the previous examples. Note that tag here is similar to tagName; use the Key string (in this case, Color.)

curl -X DELETE --header 'Accept: */*' --header 'User-Agent: none' 'https://app.metricly.com/elements/6bdf4fd1-7134-3959-9c36-17eb5f628e46/metrics/3a1a2fb7-b274-3120-84bd-d7781401894f/tags/Color'

Response Body

The following response body has no content; this is typical for a successful call. The HTTPS Status Code is 204.

No Content

GET Use this endpoint to get a list of policies associated to an element.

Parameters

Parameter

Parameter Type

Data Type

Description

elementId

path

string

Element Ids can be found in by selecting an element in CloudWisdom and viewing the URL ( /#/inventory/6bdf4fd1-1111-1111-1c11-17eb5f628e46).

Request URL

https://app.metricly.com/elements/{elementId}/policies

CURL

The following CURL example queries for a list of policies related to the elementId 6bdf4fd1-7134-3959-9c36-17eb5f628e46.

curl -X GET --header 'Accept: application/json' 'https://app.metricly.com/elements/6bdf4fd1-7134-3959-9c36-17eb5f628e46/policies'

Response Body

The following response body contains only one policy for the sake of simplicity; typical results provide a full list of all policies associated to an element.

{
  "policies": [
    {
      "id": "02f5b11e-0e11-3bb1-9c1a-fc82a4175111",
      "name": "AWS ALB - Elevated Load Balancer Error Rate",
      "description": "This is an error rate policy looking at errors from the Load Balancer itself.  In this case, we look for both high traffic volumes (> 1000) as well as error rates that are not just higher than normal, but are above a 2% threshold. In those cases, a Critical event will be generated. You may wish to tune either the 1,000 request count threshold, the 2% error threshold, or both, to better suit your environment.",
      "scope": {
        "elementName": null,
        "elementNameRegex": false,
        "elementNameExclude": null,
        "elementNameExcludeRegex": false,
        "fqnIncludes": [],
        "fqnExcludes": [],
        "elementType": null,
        "elementTypes": [
          "ALB"
        ],
        "elementTags": [],
        "elementTagsAll": true,
        "excludedElementTags": [],
        "elementAttributes": [],
        "elementAttributesAll": true,
        "excludedElementAttributes": []
      },
      "duration": 900,
      "anyCondition": false,
      "conditions": [
        {
          "metric": "netuitive.aws.alb.httpcodeelberrorpercent",
          "wildcard": null,
          "metricScopeTags": {},
          "analytic": "baselineDeviation",
          "operator": ">",
          "level": null,
          "level2": null,
          "metricThresholdLevel": null,
          "metricThresholdAnalytic": null
        },
        {
          "metric": "netuitive.aws.alb.httpcodeelberrorpercent",
          "wildcard": null,
          "metricScopeTags": {},
          "analytic": "contextualDeviation",
          "operator": ">",
          "level": null,
          "level2": null,
          "metricThresholdLevel": null,
          "metricThresholdAnalytic": null
        },
        {
          "metric": "netuitive.aws.alb.httpcodeelberrorpercent",
          "wildcard": null,
          "metricScopeTags": {},
          "analytic": "actual",
          "operator": ">=",
          "level": 2,
          "level2": null,
          "metricThresholdLevel": null,
          "metricThresholdAnalytic": null
        },
        {
          "metric": "aws.applicationelb.requestcount",
          "wildcard": null,
          "metricScopeTags": {},
          "analytic": "actual",
          "operator": ">=",
          "level": 1000,
          "level2": null,
          "metricThresholdLevel": null,
          "metricThresholdAnalytic": null
        }
      ],
      "eventConditions": [],
      "checkCondition": null,
      "actions": [
        {
          "type": "event",
          "category": 3
        }
      ],
      "enabled": true,
      "deleted": false,
      "creatorEmail": "techwriter@cloudwisdom.com",
      "lastUpdated": "2018-08-02T22:07:31Z"
    }, <!!! list of more Ids !!!>
  ]
}

GET Use this endpoint to get a list of CloudWisdom and Source tags for a particular element.

Parameters

Parameter

Parameter Type

Data Type

Description

elementId

path

string

Element Ids can be found in by selecting an element in CloudWisdom and viewing the URL ( /#/inventory/6bdf4fd1-1111-1111-1c11-17eb5f628e46).

Request URL

https://app.metricly.com/elements/{elementId}/tags

CURL

The following CURL example queries for a list of tags for an element with the elementId6bdf4fd1-7134-3959-9c36-17eb5f628e46.

curl -X GET --header 'Accept: application/json' 'https://app.metricly.com/elements/6bdf4fd1-7134-3959-9c36-17eb5f628e46/tags'

Response Body

The following response body contains a brief list of tags. Notice how the response lists tags added from CloudWisdom (netuitiveTags) and from the element (sourceTags).

{
  "netuitiveTags": {
    "Cheese": "Brie ",
    "TstMetriclyTag": "Yes",
    "n.analysis.status": null
  },
  "sourceTags": {
    "n.collectors": "ALB"
  }
}

POST Use this endpoint to create a new tag (key-value pair) for the specified element.

Parameters

Parameter

Parameter Type

Data Type

Description

User-Agent

header

string

Default value: none.

elementId

path

string

Element Ids can be found in by selecting an element in CloudWisdom and viewing the URL ( /#/inventory/6bdf4fd1-1111-1111-1c11-17eb5f628e46)

tagWrapper

body

JSON

Inject a new tag using JSON.

Request URL

https://app.metricly.com/elements/{elementId}/tags

CURL

The following CURL example posts a new key-value pair of "Weekday":"Saturday" to the element specified in the request URL. Notice it must be wrapped with netuitiveTag.

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'User-Agent: none' -d '{ \
   "netuitiveTag": { "Weekday":"Saturday"} \
 } \
  \
 \' 'https://app.metricly.com/elements/6bdf4fd1-7134-3959-9c36-17eb5f628e46/tags'

Swagger Payload

You can use the following template to test this endpoint with Swagger. Select the method icon to open this specific endpoint.

{
    "netuitiveTag": {
      "Weekday":"Saturday"
    }
  }

Response Body

The following response body prints confirmation of the tag key:value update.

{
  "netuitiveTag": {
    "Weekday": "Saturday"
  }
}

PUT Use this endpoint to update tag values for the specified element’s tag.

Parameters

Parameter

Parameter Type

Data Type

Description

User-Agent

header

string

Default value: none.

elementId

path

string

Element Ids can be found in by selecting an element in CloudWisdom and viewing the URL (/#/inventory/6bdf4fd1-1111-1111-1c11-17eb5f628e46)

tagName

path

string

Use this value to update the existing tag.

tagWrapper

body

JSON

Inject a new tag using JSON.

Request URL

https://app.metricly.com/elements/{elementId}/tags/{tagName}

CURL

The following CURL example updates the tag key Weekday with a new value,Sunday.

curl -X PUT --header 'Content-Type: application/json' --header 'Accept: */*' --header 'User-Agent: none' -d '{ \
   "netuitiveTag": { "Weekday":"Sunday"} \
 } \
 ' 'https://app.metricly.com/elements/6bdf4fd1-7134-3959-9c36-17eb5f628e46/tags/Weekday'

Swagger Payload

You can use the following template to test this endpoint with Swagger. Select the method icon to open this specific endpoint.

{
    "netuitiveTag": {
      "Weekday":"Sunday"
    }
  }

Response Body

The following response body has no content; this is typical for a successful call.

no content

DELETE Use this endpoint to delete a tag for a given element.

Parameters

Parameter

Parameter Type

Data Type

Description

User-Agent

header

string

Default value: none.

elementId

path

string

Element Ids can be found in by selecting an element in CloudWisdom and viewing the URL (/#/inventory/6bdf4fd1-1111-1111-1c11-17eb5f628e46)

tag

path

string

Used to specify which tag to delete.

Request URL

https://app.metricly.com/elements/{elementId}/tags/{tagName}

CURL

The following CURL example deletes the Weekday tag used in our previous examples.

curl -X DELETE --header 'Accept: */*' --header 'User-Agent: none' 'https://app.metricly.com/elements/6bdf4fd1-7134-3959-9c36-17eb5f628e46/tags/Weekday'

Response Body

The following response body has no content; this is typical for a successful call.

no content

DELETE Use this endpoint to delete specified elements.

Parameters

Parameter

Parameter Type

Data Type

Description

User-Agent

header

string

Default value: none.

Id

path

string

Element Ids can be found in by selecting an element in CloudWisdom and viewing the URL ( /#/inventory/6bdf4fd1-1111-1111-1c11-17eb5f628e46)

Request URL

https://app.metricly.com/elements/{elementId}

CURL

The following CURL example deletes an element with the elementId111a50a0-2b5c-3eb9-b25b-11f81de11038.

curl -X DELETE --header 'Accept: */*' --header 'User-Agent: none' 'https://app.metricly.com/elements/111a50a0-2b5c-3eb9-b25b-11f81de11038'

Response Body

The following response body has no content; this is typical for a successful call.

no content

GET Use this endpoint to get details of a specified element.

Parameters

Parameter

Parameter Type

Data Type

Description

Id

path

string

Element Ids can be found in by selecting an element in CloudWisdom and viewing the URL ( /#/inventory/6bdf4fd1-1111-1111-1c11-17eb5f628e46)

Request URL

https://app.metricly.com/elements/{elementId}

CURL

curl -X GET --header 'Accept: application/json' 'https://app.metricly.com/elements/6bdf4fd1-7134-3959-9c36-17eb5f628e46'

Response Body

The following response body is a shortened example; typical responses are much longer with several metrics and attributes.

{
  "element": {
    "netuitiveTags": {
      "Cheese": "Cheddar",
      "TstMetriclyTag": "Yes",
      "n.analysis.status": null
    },
    "sourceTags": {
      "n.collectors": "ALB"
    },
    "metrics": [
      {
        "netuitiveTags": {
          "n.statistic": "AVG"
        },
        "sourceTags": {
          "awsDimensions": "{\"LoadBalancer\":\"app/bamboo/5f973fddb1e0c653\"}",
          "awsNamespace": "AWS/ApplicationELB"
        },
        "processingFlags": {
          "RAW_AGG": true
        },
        "unit": "Count",
        "dataSourceId": 31845,
        "fqn": "aws.applicationelb.clienttlsnegotiationerrorcount",
        "name": "ClientTLSNegotiationErrorCount",
        "id": "5be97f00-82df-3b63-8751-13a09b1a2269"
      } <!!! more metrics usually listed here !!!>
    ],
    "fqn": "111119301106:ALB:us-east-1:app/bamboo/5f973fddb1e0c111",
    "name": " bamboo - us-east-1",
    "location": "us-east-1",
    "id": "6bdf4fd1-71111-3959-9c36-17eb5f611e11",
    "type": "ALB",
    "attributes": [
      {
        "id": "2e076c28-295d-3827-9638-ef8ecce767a7",
        "dataSourceId": 31845,
        "name": "ipAddressType",
        "value": "ipv4",
        "attributeType": null
      },
      {
        "id": "9124e608-197f-39eb-a35b-15155adc6c9d",
        "dataSourceId": 31845,
        "name": "scheme",
        "value": "internet-facing",
        "attributeType": null
      } <!!! more attributes usually listed here !!!>
      }
    ]
  }
}

GET Use this endpoint to view an element’s relationships.

Parameters

Parameter

Parameter Type

Data Type

Description

id

Path

String

Element Ids can be found in by selecting an element in CloudWisdom and viewing the URL ( /#/inventory/6bdf4fd1-1111-1111-1c11-17eb5f628e46)

levels

Query

Integer

Depth of relationships.

startTime

Query

Date-Time

Start time for the query. YYYY-MM-DDT00:001Z format (must include time zone).

endTime

Query

Date-Time

End time for the query. YYYY-MM-DDT00:001Z format (must include time zone).

Request URL

https://app.metricly.com/elements/{elementId}/relationships?levels={levelNumber}

CURL

The following CURL example gets a list of relationships for an element with the elementId6bdf4fd1-1111-1111-9c36-17eb5f628e46 and a level of 2.

curl -X GET --header 'Accept: application/json' 'https://app.metricly.com/elements/6bdf4fd1-1111-1111-9c36-17eb5f628e46/relationships?levels=2'

Response Body

{
  "relationships": {
    "type": null,
    "label": null,
    "directed": true,
    "nodes": [
      {
        "id": "6bdf4fd1-1111-1111-9c36-17eb5f628e46",
        "label": "ECS-ASG-Spot-GREEN",
        "type": "ASG",
        "metadata": {
          "fqn": "501234301106:ASG:us-west-2:ECS-ASG-Spot-GREEN"
        }
      },
      {
        "id": "0f78c417-4fb1-38e9-9b84-0289fc65c9c0",
        "label": "GREEN-JSLAVE (10.12.52.132)",
        "type": "EC2",
        "metadata": {
          "fqn": "501234301106:EC2:us-west-2:i-04dcebc729b34a9dc"
        }
      },
      {
        "id": "a37b3749-8584-39d4-bcd0-46cfd49eb2fa",
        "label": "vol-0fcbb26fd00e33818",
        "type": "EBS",
        "metadata": {
          "fqn": "501234301106:EBS:us-west-2:vol-0fcbb26fd00e33818"
        }
      },
      {
        "id": "ae12b2f7-1111-11c7-836b-73ed9272ebdd",
        "label": "vol-0e0ec86d83b5bbfa8",
        "type": "EBS",
        "metadata": {
          "fqn": "501111301106:EBS:us-west-2:vol-0e0ec00d83b5bbfa8"
        }
      }
    ],
    "edges": [
      {
        "source": "0f11c417-4fb1-38e9-9b84-0111fc65c9c0",
        "relation": "member of",
        "target": "241464d6-f5df-3111-8aeb-30352c0d1108",
        "directed": true,
        "metadata": {}
      },
      {
        "source": "a37b3749-2222-39d4-bcd2-46cfd49eb2fa",
        "relation": "member of",
        "target": "0f78c227-4fb1-38e9-9b22-0111fc65c9c0",
        "directed": true,
        "metadata": {}
      },
      {
        "source": "ae12b2f7-1234-30c7-836b-73ed1172ebdd",
        "relation": "member of",
        "target": "0f11c417-4fb1-38e9-9b84-1111fc65c9c0",
        "directed": true,
        "metadata": {}
      }
    ],
    "metadata": {}
  }
}

How to Find an Element ID and Delete It Via the API

You can automate element removal from CloudWisdom using two Element endpoints: /elasticsearchElementQueryUsingPOST and /elements/{id}. This is useful for keeping a clean inventory and it helps avoid false-positive alerts when routinely shutting down instances that are using the Metricly agent.

  1. Build a query using CURL that searches your inventory for an element matching elementNames you provide. This query returns information on the element, such as the elementId. In this example we are searching for element-name-abc1. Since we’re only really interested in obtaining the elementId, let’s exclude metrics and attributes using sourceFilter:

    curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{  "sort": { \
     "field": "name", \
     "order": "asc", \
     "missing": "_last" \
    }, \
    "page": 0, \
    "pageSize": 35, \
    "startDate": "2020-01-26T11:29:56-05:00", \
    "endDate": "2020-01-26T12:29:56-05:00", \
    "elementNames": { \
     "and": false, \
     "items": [ \
       { \
         "literal": true, \
         "contains": true, \
         "item": "element-name-abc1" \
       } \
     ] \
    }, \
    "sourceFilter": { \
     "excludes": [ \
       "metrics", \
       "attributes" \
     ] \
    } \
    }' 'https://app.metricly.com/elements/elasticsearch/elementQuery'
  2. Review the request body and obtain the elementId.

    {
    "page": {
    "content": [
      {
        "sourceTags": {
          "Name": "element-name-abc1",
          "n.collectors": "EBS"
        },
        "state": {
          "netuitive.metrics.collected.percent": null
        },
        "eventCount": {
          "total": 0,
          "topCategory": null
        },
        "fqn": "501119301106:EBS:us-east-1:vol-08ab171bfa2c63111",
        "name": "element-name-abc1",
        "location": "us-east-1c",
        "id": "115a11a0-2b5c-3eb9-b11b-48f81de11038",
        "type": "EBS"
      }
    ],
    "last": true,
    "totalElements": 1,
    "totalPages": 1,
    "sort": null,
    "first": true,
    "numberOfElements": 1,
    "size": 35,
    "number": 0
    }
  3. Submit a Delete request to /elements/{id}.

    curl -X DELETE --header 'Accept: */*' --header 'User-Agent: none' 'https://app.metricly.com/elements/115a11a0-2b5c-3eb9-b11b-48f81de11038'
    
    

The element is now removed from your inventory, along with its historical data. If you wish to keep the historical data, consider putting the element in maintenance mode instead. This disables alerts during known outages without discarding historical data.

You can fetch metric samples for a single element using the /elements/{elementId}/metrics/{metricId}/samples endpoint. First you must obtain some element details from the /elements/elasticsearch/elementQuery endpoint.

  1. Build a POST query using CURL that searches your inventory for an element matching elementNames you provide. In this example we are searching for element-name-abc1. Since we’re only really interested in obtaining the elementId and metricNames, let’s exclude attributes using sourceFilter:

    curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{  "sort": { \
     "field": "name", \
     "order": "asc", \
     "missing": "_last" \
    }, \
    "page": 0, \
    "pageSize": 35, \
    "startDate": "2020-01-26T11:29:56-05:00", \
    "endDate": "2020-01-26T12:29:56-05:00", \
    "elementNames": { \
     "and": false, \
     "items": [ \
       { \
         "literal": true, \
         "contains": true, \
         "item": " bamboo - us-east-1" \
       } \
     ] \
    }, \
    "sourceFilter": { \
     "excludes": [ \
       "attributes" \
     ] \
    } \
    }' 'https://app.metricly.com/elements/elasticsearch/elementQuery'
  2. Review the response body and obtain the elementId. Also select the metricId corresponding to the metric you want to fetch. For this example, we’ll take the ID for RequestCount: 4a902433-1111-371c-9a14-d9112c465aa9.

    {
    "page": {
    "content": [
      {
        "netuitiveTags": {
          "TstMetriclyTag": "Yes",
          "n.analysis.status": null
        },
        "sourceTags": {
          "n.collectors": "ALB"
        },
        "state": {
          "netuitive.metrics.collected.percent": 100
        },
        "eventCount": {
          "total": 0,
          "topCategory": null
        },
        "lastProcessed": "2020-01-26T21:35:00Z",
        "metrics": [
          {
            "netuitiveTags": {
              "n.statistic": "AVG"
            },
            "sourceTags": {
              "awsDimensions": "{\"LoadBalancer\":\"app/bamboo/5f973fddb1e0c111\"}",
              "awsNamespace": "AWS/ApplicationELB"
            },
            "processingFlags": {
              "RAW_AGG": true
            },
            "unit": "Count",
            "fqn": "aws.applicationelb.requestcount",
            "dataSourceId": 31845,
            "name": "RequestCount",
            "id": "4a902433-1111-371c-9a14-d9112c465aa9"
          }
        ],
        "fqn": "501119301106:ALB:us-east-1:app/bamboo/5f113fddb1e0c653",
        "name": "element-name-abc",
        "location": "us-east-1",
        "id": "6bdf4fd1-1111-2222-9c36-17eb5f628e46",
        "type": "ALB"
      }
    ],
    "last": true,
    "totalElements": 1,
    "totalPages": 1,
    "sort": null,
    "first": true,
    "numberOfElements": 1,
    "size": 35,
    "number": 0
    }
    }
  3. Build a GET CURL command for the /elements/{elementId}/metrics/{metricId}/samples. Include the elementId and metricId found in the response body. This example adds startTime and endTime parameters to limit the response body and defines the rollup value as ZERO.

    curl -X GET --header 'Accept: application/json' 'https://app.metricly.com/elements/6bdf4fd1-1111-2222-9c36-17eb5f628e46/metrics/4a902433-1111-371c-9a14-d9112c465aa9/samples?startTime=2020-01-26T11%3A29%3A56-05%3A00&endTime=2020-01-26T11%3A30%3A56-05%3A00&rollup=ZERO'
  4. Review the response body for this 1 minute window. This is one metric sample using raw data.

      "samples": [
        {
          "metricId": "4a902433-1111-371c-9a14-d9112c465aa9",
          "timestamp": "2020-01-26T16:30:00Z",
          "rollup": "ZERO",
          "data": {
            "min": 0,
            "avg": 0.15,
            "max": 1,
            "cnt": 20,
            "sum": 3
          }
        }
      ]
    }
  5. Compare with the response body of a 10 minute window where the rollup value is PT5M. This is two metric samples that provide baseline bands.

    {
      "samples": [
        {
          "metricId": "4a902433-1111-371c-9a14-d9112c465aa9",
          "timestamp": "2020-01-26T16:25:00Z",
          "rollup": "PT5M",
          "data": {
            "actual": 0.1,
            "avg": 0.1,
            "min": 0,
            "max": 1,
            "baselineMean": 0.1714443172258489,
            "cnt": 20,
            "sum": 2,
            "baselineStddev": 0.8864747374758107,
            "baselineUpper": 3.717343267129092,
            "baselineLower": 0
          }
        },
        {
          "metricId": "4a902433-1111-371c-9a14-d9112c465aa9",
          "timestamp": "2020-01-26T16:30:00Z",
          "rollup": "PT5M",
          "data": {
            "actual": 0.19047619047619047,
            "avg": 0.19047619047619047,
            "min": 0,
            "max": 1,
            "baselineMean": 0.17387482703660617,
            "cnt": 21,
            "sum": 4,
            "baselineStddev": 0.9182086113131865,
            "baselineUpper": 3.8467092722893526,
            "baselineLower": 0
          }
        }
      ]
    }
    

Now you can fetch metric data using two Element endpoints.