wiki:GENIMonitoring/API

Version 13 (modified by Caylin Hickey, 3 years ago) (diff)

Added example queries from Tom's attachment

Note: this is a draft page documenting the development of the GENI Collector API access.

GENI Collector API

This page details the developmental progress and description of the GENI Collector API access system.

The API is accessed in similar fashion to accessing metric data from a GENI Monitoring Datastore. (ie: /API/data/?q={json})

Metric Data

Request

Request Format

  {
    eventType: [
      "opsmonitoring:_____",
      ...
    ],
    ts: {
      gte*: #####,        // milliseconds or microseconds
      lt*: #####          // milliseconds or microseconds
    },
    obj: {
      type*: _______,     // string of pollable object time (aggregate, node, interface, etc.)
      id: [
        _______,         // string of either urn or id of a requested target
        ...
      ]
    },
    output: _______      // string of output format type (xml or json). if not supplied, defaults to xml
  }

Note: items denoted with a (*) are required

Valid Metric Request Object Types

  • aggregate
  • node
  • interface
  • vlan
  • check | experiment

Valid Metric eventTypes per Object Type

  • aggregate
    • is_available
    • routable_ip_available
    • raw_pc_available
    • nodelogin
  • node
    • cpu_util
    • mem_used_kb
    • swap_free
    • disk_used_max_part
    • num_vms_allocated
    • is_available
  • interface | vlan
    • rx_bps
    • tx_bps
    • rx_pps
    • tx_pps
    • rx_eps
    • tx_eps
    • rx_dps
    • tx_dps
  • interface only
    • tx_power
    • tx_freqency
    • wmx_noc
  • experiment | check
    • ping_rtt_ms
    • is_stitch_path_available

Example Request URL

https://genimon.uky.edu/API/data/?q={"obj":{"id":["pks2.sdn.uky.edu_node_pc1"],"type":"node"},"output":"json","ts":{"gte":1456260153962,"lt":1456263753962}}

Response

Response Format (XML) [Default]

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <request>
    <url>_____</url>                                                    // the url from which this response was generated
  </request>
  <objects>
    <object urn="_____" id="_____" schema="_____" objectType="_____">   // descriptors of this object   
      <events eventType="_____" units="_____">                          // descriptors of this eventType list
        <event>
          <ts>#####</ts>                                                // timestamp of this event (in milliseconds)
          <v>_____</v>                                                  // value for this eventType at this timestamp
        </event>
        ...
      </events>
    </object>
    ...
  </objects>
</response>

Response Format (JSON)

  [
    {
      "$schema": "http://www.gpolab.bbn.com/monitoring/schema/20151105/data#",
      "description": "ops_monitoring:_____ for _____ of type _____",             // eventType, id, objectType
      "eventType": "ops_monitoring:_____",                                       // eventType
      "id": "_____:_____",                                                       // eventType, id
      "subject": {
        "href": "_____#"                                                         // schema of objectType
      },
      "tsdata": [
        "ts": #####,                                                             // (in milliseconds)
        "v": _____                                                               // depends on the eventType
      ],
      "units": _____                                                             // describes the units fo the eventType
    },
    ...
  ]

Object Information

Request

Request Format

  {
    infoType: _____,     // the type of info requested (simple or detailed)
    ts: {
      ts: #####,         // milliseconds or microseconds, defaults to now() if omitted
    },
    obj: {
      type*: _______,    // string of object type  (aggregate, node, interface, etc.)
      id: [
        _______,         // string of either urn or id of a requested target, returns all if omitted
        ...
      ]
    },
    output: _______      // string of output format type. currently only json for info requests
  }

Note on infoType:

  • simple - Returns a list with the object details
  • detailed - Returns a list with the object details as well as any child objects associated to said object

Valid Info Request Object Types

  • opsconfig | configstore
  • aggregate
  • sliver
  • node
  • link
  • interface
  • vlan
  • authority
  • slice
  • checkstore | externalcheckstore
  • check | experiment

Example Request URL

https://genimon.uky.edu/API/info/?q={"obj":{"id":["pks2.sdn.uky.edu_node_pc1"],"type":"node"},"output":"xml"}

Response

Response Format (XML) [Default]

  <?xml version="1.0" encoding="UTF-8"?>
  <response>
    <request>
      <url>
        _____
      </url>
    </request>
    <objects>
      <______>
        <______>______</_____>
        ...
      </_____>
      ...
    </objects>
  </response>

Response Format (JSON)

  [
    {
      _____: _____,          // These will be fields specific to the type of object requested
      ...
    },
    ...
  ]

Example Queries

  • Get a list of aggregates in JSON format (SImple meaning just the aggregate itself, not its children)
http://genimon.uky.edu/API/info/?q={"obj":{"type":"aggregate"},"output":"json","infoType":"simple"}
  • Get a list of aggregates in XML format
http://genimon.uky.edu/API/info/?q={"obj":{"type":"aggregate"},"output":"xml","infoType":"simple"}
  • Get information about a single aggregate by short name in JSON format
http://genimon.uky.edu/API/info/?q={"obj":{"id":["max-ig"],"type":"aggregate"},"output":"json","infoType":"simple"}
  • Get information about a single aggregate by short name in XML format
http://genimon.uky.edu/API/info/?q={"obj":{"id":["max-ig"],"type":"aggregate"},"output":"xml","infoType":"simple"}
  • Get information about a single aggregate by URN in JSON format
http://genimon.uky.edu/API/info/?q={"obj":{"id":["urn:publicid:IDN+instageni.maxgigapop.net+authority+cm"],"type":"aggregate"},"output":"json","infoType":"simple"}
  • Get information about a single aggregate by URN in XML format
http://genimon.uky.edu/API/info/?q={"obj":{"id":["urn:publicid:IDN+instageni.maxgigapop.net+authority+cm"],"type":"aggregate"},"output":"xml","infoType":"simple"}
  • Get event information about an aggregate
http://genimon.uky.edu/API/data/?q={"obj":{"id":["max-ig"],"type":"aggregate"},"output":"xml","ts":{"gte":1456260153962,"lt":1456263753962}}
  • Just is_available for an aggregate in XML format
http://genimon.uky.edu/API/data/?q={"eventType":["is_available"],"obj":{"id":["max-ig"],"type":"aggregate"},"output":"xml","ts":{"gte":1456345005000,"lt":1456348605000}}
  • Just is_available for an aggregate in JSON format
http://genimon.uky.edu/API/data/?q={"eventType":["is_available"],"obj":{"id":["max-ig"],"type":"aggregate"},"output":"json","ts":{"gte":1456345005000,"lt":1456348605000}}
  • List all slivers in XML
http://genimon.uky.edu/API/info/?q={"obj":{"type":"sliver"},"output":"xml","infoType":"simple"}
  • Info about a single sliver in json
http://genimon.uky.edu/API/info/?q={"obj":{"id":["lan.sdn.uky.edu_sliver_38337"],"type":"sliver"},"output":"json","infoType":"detailed"}

Attachments (1)

Download all attachments as: .zip