Skip to content

Metrics REST interface

Get metrics metadata for nodes

Get metadata for all known metrics in the managed nodes. The metrics are grouped hierarchically according to three main groups (wombat_metrics, folsom_metrics, and exometer_metrics) and the categories under which they are displayed in the web dashboard.

Definition

1
GET /api/metric/metric-info/node/NODE_ID?tags=LISTOFTAGS

Example request

1
curl -X GET "http://127.0.0.1:8080/api/metric/metric-info/node/3fa56f92-3195-401b-93a8-7bc43e54d66f?tags=dev,op"

Example response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
{
  "groups": [
    {
      "name": "wombat_metrics",
      "display": "WombatOAM metrics",
      "categories": [
        {
          "display": "Memory",
          "metrics": [
            {
              "name": "total_memory",
              "type": "gauge",
              "display": "Total memory",
              "unit": "byte"
            },
            {
              "name": "atom_memory",
              "type": "gauge",
              "display": "Atom memory",
              "unit": "byte"
            },
            {...},
            {...},
            {...}
          ]
        },
        {
          "display": "Runtime",
          "metrics": [
            {
              "name": "cpu_avg1",
              "type": "gauge",
              "display": "CPU load for 1 avg",
              "unit": "numeric"
            },
            {...},
            {...},
            {...}
          ]
        },
        {...},
        {...},
        {...}
      ]
    },
    {
      "name": "folsom_metrics",
      "display": "Folsom metrics",
      "categories": [
        {
          "display": "Folsom metrics",
          "metrics": [
            {
              "name": "cpu",
              "type": "gauge",
              "display": "cpu",
              "unit": "numeric"
            },
            {...},
            {...},
            {...}
          ]
        }
      ]
    },
    {
      "name": "exometer_metrics",
      "display": "Exometer metrics",
      "categories": [
        {
          "display": "Exometer metrics",
          "metrics": [
            {
              "name": "[cpu,counter]",
              "type": "counter",
              "display": "cpu_counter",
              "unit": "numeric"
            },
            {...},
            {...},
            {...}
          ]
        }
      ]
    }
  ]
}

Arguments

Argument Description
node ID Required. The identifier of the node for which to retrieve metrics metadata.
tags Optional. A comma separated list of tags that overrides the tags set for the user.

Returns

An array of metric groups, categories, and information about individual metrics that are tagged with any of the active tags. The "display" property is the text that is displayed in the web dashboard.

For each individual metric:

Property Description
name The internal name of the metric. This name should be used in calls to retrieve data for specific individual metrics.
type The type of metric, determining the call that should be used when retrieving data for that metric.
display The text displayed in the web dashboard.
unit The metric's unit of measurement.

Get metric metadata for node families

Get metadata for all known metrics in node families.

Definition

1
GET /api/metric/metric-info/node-family/NODE_FAMILY_ID?tags=LISTOFTAGS

Example request

1
curl -X GET "http://127.0.0.1:8080/api/metric/metric-info/node-family/93be4f01-dae6-49b0-9608-4552f841a720"

Example response

See "Get metrics metadata for nodes", above.

Arguments

Argument Description
node family ID Required. Description
tags Optional. A comma separated list of tags that overrides the tags set for the user.

Returns

An array of metric groups, categories, and information about individual metrics that are tagged with any of the active tags.. The "display" property is the text that is displayed in the web dashboard.

For each individual metric:

Property Description
name The internal name of the metric. This name should be used in calls to retrieve data for specific individual metrics.
type The type of metric, determining the call that should be used when retrieving data for that metric.
display The text displayed in the web dashboard.
unit The metric's unit of measurement.

Get metric historical data for a node

Retrieve the historical data for a specified node and a specified metric. The request needs to specify the series from which to query (see "Arguments", below), as well as the time interval.

Definition

1
GET /api/metric/history/node/NODE_ID/METRIC/SERIES?from=FROM&to=TO

Example request

1
curl -X GET "http://127.0.0.1:8080/api/metric/history/node/3fa56f92-3195-401b-93a8-7bc43e54d66f/total_memory/3?from=2014-07-31T00:00:00.000Z&to=2014-07-31T23:59:59.999Z"

Example response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
  "data": [
    {
      "time": "2014-07-31 12:40:40.000",
      "jstime": "1406810440000",
      "value": 50258288.0
    },
    {
      "time": "2014-07-31 12:55:40.000",
      "jstime": "1406811340000",
      "value": 43555390.4
    }
  ]
}

Arguments

Argument Description
node ID Required. The identifier of the node for which to retrieve metrics data.
metric Required. The name of the metric (see "Get metrics metadata…", above).
series Required. The numeric identifier of the series. 1 means the base sample data, 2 is the first consolidated series, and 3 is the second consolidated series.
from Required. The start date and time of the samples. Combined date and time in ISO 8601 format. For example: 2014-07-31T00:00:00.000Z
to Required. The end date and time of the samples. Combined date and time in ISO 8601 format. For example: 2014-07-31T23:59:59.999Z

Returns

A data property that contains an array of metric samples, each with the following details:

Property Description
time The date and time of the sample.
jstime The millisecond value of the date and time.
value The value of the metric sample.

Get metric historical data for a node family

Retrieve the historical data for a specified node family and a specified metric. The request needs to specify the series from which to query (see "Arguments", below), as well as the time interval.

Definition

1
GET /api/metric/history/node-family/NODE_FAMILY_ID/METRIC/SERIES?from=FROM&to=TO

Example request

1
curl -X GET "http://127.0.0.1:8080/api/metric/history/node-family/93be4f01-dae6-49b0-9608-4552f841a720/total_memory/3?from=2014-07-31T00:00:00.000Z&to=2014-07-31T23:59:59.999Z"

Example response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
[
  {
    "nodeId": "5b16ec55-56a3-4430-b174-c996897ccd14",
    "data": [
      {
        "time": "2014-07-31 12:40:40.000",
        "jstime": "1406810440000",
        "value": 49912632.0
      },
      {
        "time": "2014-07-31 12:55:41.000",
        "jstime": "1406811341000",
        "value": 43825455
      },
      {...},
      {...},
      {...}
    ]
  },
  {
    "nodeId": "3fa56f92-3195-401b-93a8-7bc43e54d66f",
    "data": [
      {
        "time": "2014-07-31 12:40:40.000",
        "jstime": "1406810440000",
        "value": 50258288.0
      },
      {
        "time": "2014-07-31 12:55:41.000",
        "jstime": "1406811341000",
        "value": 43555233
      },
      {...},
      {...},
      {...}
    ]
  }
]

Arguments

Argument Description
node family ID Required. The identifier of the node family for which to retrieve metrics data.
metric Required. The name of the metric (see "Get metrics metadata…", above).
series Required. The numeric identifier of the series. 1 means the base sample data, 2 is the first consolidated series, and 3 is the second consolidated series.
from Required. The start date and time of the samples. Combined date and time in ISO 8601 format. For example: 2014-07-31T00:00:00.000Z
to Required. The end date and time of the samples. Combined date and time in ISO 8601 format. For example: 2014-07-31T23:59:59.999Z

Returns

For each node, a data property that contains an array of metric samples, each with the following details:

Property Description
time The date and time of the sample.
jstime The millisecond value of the date and time.
value The value of the metric sample.

Get metric histogram for a node

Use this call to retrieve metric data for metrics of the type histogram (see "Get metrics metadata for a node").

Definition

1
GET /api/metric/histogram/node/NODE_ID/METRIC?from=FROM&to=TO

Example request

1
curl -X GET "http://127.0.0.1:8080/api/metric/histogram/node/3fa56f92-3195-401b-93a8-7bc43e54d66f/%7Bcpu,histogram%7D?from=2014-07-31T00:00:00.000Z&to=2014-07-31T23:59:59.999Z"

Example response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
{
  "data": [
    {
      "time": "2014-07-31 12:47:10.261",
      "jstime": "1406810830000",
      "value": {
        "min": 0,
        "max": 100,
        "arithmetic_mean": 51.00486381322957,
        "geometric_mean": 35.66788826103998,
        "harmonic_mean": 23.94843838939527,
        "median": 52,
        "variance": 1002.5579120554382,
        "standard_deviation": 31.663194912317966,
        "skewness": -0.053591991674156764,
        "kurtosis": -1.3019963450719712,
        "n": 1028,
        "percentiles": [
          {"percentile": 50, "value": 52},
          {"percentile": 75, "value": 79},
          {"percentile": 90, "value": 93},
          {"percentile": 95, "value": 98},
          {"percentile": 99, "value": 100},
          {"percentile": 999, "value": 100}
        ],
        "histogram": [
          {"x": 11, "num": 146},
          {"x": 22, "num": 106},
          {"x": 40, "num": 176},
          {"x": 50, "num": 74},
          {"x": 60, "num": 81},
          {"x": 70, "num": 103},
          {"x": 80, "num": 91},
          {"x": 90, "num": 107},
          {"x": 100, "num": 144},
          {"x": 110, "num": 0}
        ]
      }
    },
    {...},
    {...},
    {...}
  ]
}

Arguments

Argument Description
node ID Required. The identifier of the node for which to retrieve metrics data.
metric Required. The name of the metric (see "Get metrics metadata…", above).
from Required. The start date and time of the samples. Combined date and time in ISO 8601 format. For example: 2014-07-31T00:00:00.000Z
to Required. The end date and time of the samples. Combined date and time in ISO 8601 format. For example: 2014-07-31T23:59:59.999Z

Returns

A data property that contains an array of metric samples within the specified time interval, each with the following details:

Property Description
time The date and time of the sample.
jstime The millisecond value of the date and time.
value A data structure which provides the details of the data point.

Get metric duration for a node

Use this call to retrieve metric data for metrics of the type duration (see "Get metrics metadata for a node").

Definition

1
GET /api/metric/duration/node/NODE_ID/METRIC?from=FROM&to=TO

Example request

1
curl -X GET "http://127.0.0.1:8080/api/metric/duration/node/3fa56f92-3195-401b-93a8-7bc43e54d66f/%7Bhandle_req_duration%7D?from=2014-07-31T00:00:00.000Z&to=2014-07-31T23:59:59.999Z"

Example response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
{
  "data": [
    {
      "time": "2014-07-31 12:47:10.261",
      "jstime": "1406810830000",
      "value": {
        "count": 2567,
        "last": 34,
        "min": 0,
        "max": 100,
        "arithmetic_mean": 51.00486381322957,
        "geometric_mean": 35.66788826103998,
        "harmonic_mean": 23.94843838939527,
        "median": 52,
        "variance": 1002.5579120554382,
        "standard_deviation": 31.663194912317966,
        "skewness": -0.053591991674156764,
        "kurtosis": -1.3019963450719712,
        "n": 1028,
        "percentiles": [
          {"percentile": 50, "value": 52},
          {"percentile": 75, "value": 79},
          {"percentile": 90, "value": 93},
          {"percentile": 95, "value": 98},
          {"percentile": 99, "value": 100},
          {"percentile": 999, "value": 100}
        ],
        "histogram": [
          {"x": 11, "num": 146},
          {"x": 22, "num": 106},
          {"x": 40, "num": 176},
          {"x": 50, "num": 74},
          {"x": 60, "num": 81},
          {"x": 70, "num": 103},
          {"x": 80, "num": 91},
          {"x": 90, "num": 107},
          {"x": 100, "num": 144},
          {"x": 110, "num": 0}
        ]
      }
    },
    {...},
    {...},
    {...}
  ]
}

Arguments

Argument Description
node ID Required. The identifier of the node for which to retrieve metrics data.
metric Required. The name of the metric (see "Get metrics metadata…", above).
from Required. The start date and time of the samples.
to Required. The end date and time of the samples.

The from and to fields are combined date and time in ISO 8601 format. For example: 2014-07-31T23:59:59.999Z

Returns

A data property that contains an array of metric samples within the specified time interval, each with the following details:

Property Description
time The date and time of the sample.
jstime The millisecond value of the date and time.
value A data structure which provides the details of the data point.

Get metric meter for a node

Use this call of retrieving metric data for metrics of the type meter (see "Get metrics metadata for a node").

Definition

1
GET /api/metric/meter/node/NODE_ID/METRIC?from=FROM&to=TO

Example request

1
curl -X GET "http://127.0.0.1:8080/api/metric/meter/node/3fa56f92-3195-401b-93a8-7bc43e54d66f/%7Bcpu,meter%7D?from=2014-07-31T00:00:00.000Z&to=2014-07-31T23:59:59.999Z

Example response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
  "data": [
    {
      "time": "2014-07-31 12:47:10.261",
      "jstime": "1406810830000",
      "value": {
        "one": "2.068",
        "five": "3.085",
        "fifteen": "2.993",
        "day": "2.226"
      }
    },
    {
      "time": "2014-07-31 12:47:59.213",
      "jstime": "1406810879000",
      "value": {
        "one": "4693.918",
        "five": "1164.305",
        "fifteen": "403.433",
        "day": "6.443"
      }
    },
    {...},
    {...},
    {...}
  ]
}

Arguments

Argument Description
node ID Required. The identifier of the node for which to retrieve metrics data.
metric Required. The name of the metric (see "Get metrics metadata…", above).
from Required. The start date and time of the samples. Combined date and time in ISO 8601 format. For example: 2014-07-31T00:00:00.000Z
to Required. The end date and time of the samples. Combined date and time in ISO 8601 format. For example: 2014-07-31T23:59:59.999Z

Returns

A data property that contains an array of metric samples within the specified time interval, each with the following details:

Property Description
time The date and time of the sample.
jstime The millisecond value of the date and time.
value The data points at the given time.

Get spiral metric for a node

Use this call of retrieving metric data for metrics of the type spiral (see "Get metrics metadata for a node").

Definition

1
GET /api/metric/spiral/node/NODE_ID/METRIC/SERIES?from=FROM&to=TO

Example request

1
curl -X GET "http://127.0.0.1:8080/api/metric/spiral/node/3fa56f92-3195-401b-93a8-7bc43e54d66f/%5Bcpu,duration%5D/2?from=2014-07-31T00:00:00.000Z&to=2014-07-31T23:59:59.999Z"

Example response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "data": [
    {
      "time": "2014-07-31 12:47:13.754",
      "jstime": "1406810833000",
      "value": {
        "count": 305076,
        "one": 38554
      }
    },
    {
      "time": "2014-07-31 12:48:01.240",
      "jstime": "1406810881000",
      "value": {
        "count": 737557,
        "one": 461738
      }
    },
    {...},
    {...},
    {...}
  ]
}

Arguments

Argument Description
node ID Required. The identifier of the node for which to retrieve metrics data.
metric Required. The name of the metric (see "Get metrics metadata…", above).
Series Optional. The numeric identifier of the series. 1 means the base sample data, 2 is the first consolidated series, and 3 is the second consolidated series. The default value is 1.
from Required. The start date and time of the samples. Combined date and time in ISO 8601 format. For example: 2014-07-31T00:00:00.000Z
to Required. The end date and time of the samples. Combined date and time in ISO 8601 format. For example: 2014-07-31T23:59:59.999Z

Returns

A data property that contains an array of metric samples within the specified time interval, each with the following details:

Property Description
time The date and time of the sample.
jstime The millisecond value of the date and time.
value The data points at the given time.

Get gauge info for a node

Retrieve the current configuration of gauges shown on the web dashboard.

Definition

1
GET /api/metric/gauge-info/node/NODE_ID

Example request

1
curl -X GET "http://127.0.0.1:8080/api/metric/gauge-info/node/3fa56f92-3195-401b-93a8-7bc43e54d66f"

Example response

1
2
3
4
5
6
7
8
9
{
  "gauges": [
    {
      "name": "total_memory",
      "min_value": 10000000,
      "max_value": 30000000
    }
  ]
}

Arguments

Argument Description
node ID Required. The identifier of the node for which to retrieve gauge details.

Returns

An array containing each gauge's name, minimum value, and maximum value.