We use proprietary and third party's cookies to improve your experience and our services, identifying your Internet Browsing preferences on our website; develop analytic activities and display advertising based on your preferences. If you keep browsing, you accept its use. You can get more information on our Cookie Policy
Cookies Policy
Monitoring Open RESTful API Specification - FIWARE Forge Wiki

Monitoring Open RESTful API Specification

From FIWARE Forge Wiki

Jump to: navigation, search

Contents

Introduction to the Monitoring API

Please check the FI-WARE Open Specifications Legal Notice to understand the rights to use FI-WARE Open Specifications.

In a Cloud, there is a set of heterogeneous components will have to be monitored, including infrastructure elements, products and applications, possible spread across different regions. This API is proposed to retrieve data from a multi-region, federated common framework for storing, aggregating and publishing the monitored data gathered from existing monitoring infrastructures. Data aggregation leverages on big data analysis techniques.

Monitoring API Core

The Monitoring API is a RESTful, resource-oriented API accessed via HTTP/HTTPS that uses JSON-based representation for information interchange. This API, as described here, will be used basically to get information about monitored metrics, including elaborated data leveraging on big data analysis techniques.

Intended Audience

This specification is intended for both software developers and implementers of this API. For the former, this document provides a full specification of how to interoperate with Cloud Platforms that implements Monitoring API. For the latter, this specification indicates the interface to be provided to clients to interoperate with the Monitoring GE within the Cloud Platform to provide the described functionalities. To use this information, the reader should first have a general understanding of the Monitoring GE and also be familiar with:

  • RESTful web services
  • JSON data serialization format.


API Change History

This version of the Monitoring API Guide replaces and obsoletes all previous versions. The most recent changes are described in the table below:

Revision Date Changes Summary
09/11/2012

First version of the Monitoring API based on TCloud specification

11/02/2014

New version of a the Monitoring API with multi-region, federation support


How to Read This Document

In the whole document the assumption is taken that the reader is familiarized with REST architecture style. Along the document, some special notations are applied to differentiate some special words or concepts. The following list summarizes these special notations.

  • A bold, mono-spaced font is used to represent code or logical entities, e.g., HTTP method (GET, PUT, POST, DELETE).
  • An italic font is used to represent document titles or some other kind of special text, e.g., URI.
  • The variables are represented between brackets, e.g. {id} and in italic font. When the reader find it, can change it by any value.

For a description of some terms used along this document, see [1].


Additional Resources

You can download the most current version of this document from the FI-WARE API specification selecting PDF Version from the Toolbox menu (left side), which will generate the file to download it. For more details about the Monitoring that this API is based upon, please refer to Cloud Hosting. Related documents, including an Architectural Description, are available at the same site.


General Monitoring API Information

Resources Summary

A diagram in which the different Uniform Resource Names (URNs) that can be used in the API is shown here. The URL http://{serverRoot}:{serverPort}/monitoring/ is the root of the resource hierarchy.


Monitoring Open RESTful API resource summary

Authentication

No defined yet.

Representation Format

The Monitoring API resources are represented by hypertext that allows each resource to reference other related resources. More concisely, JSON is used for resource representation and URLs are used for referencing other resources by default. The request format is specified using the Content-Type header and is required for operations that have a request body. The response format can be specified in requests using either the Accept header with values application/json. The following lines show the examples about it.


GET /monitoring/regions/myregionid/hosts/myhostid HTTP/1.1
Host: api.monitoring.org
Content-Type: application/json
Accept: application/json
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb


Representation Transport

Resource representation is transmitted between client and server by using HTTP 1.1 protocol, as defined by IETF RFC-2616. Each time an HTTP request contains payload, a Content-Type header shall be used to specify the MIME type of wrapped representation. In addition, both client and server may use as many HTTP headers as they consider necessary.

Resource Identification

API consumer must indicate the resource identifier while invoking a GET, PUT, POST or DELETE operation. Monitoring API combines both identification and location by terms of URL. Each invocation provides the URL of the target resource along the verb and any required input data. That URL is used to identify unambiguously the resource. For HTTP transport, this is made using the mechanisms described by HTTP protocol specification as defined by IETF RFC-2616.

Monitoring API does not enforce any determined URL pattern to identify its resources. Anyway the Monitoring API extension follows the HATEOAS principle (Hypermedia As The Engine Of Application State). This means that resource representation contains the URLs of the related resources (e.g., book representation contains hyperlinks to its chapters; chapter representation contains hyperlinks to its pages...). API consumer obtains measure and values as its following point, which in turn provides hyperlinks that directly or indirectly take to other resources like measure resources.

Some Monitoring API entities provide an instance identifier property (instance ID). This property is used to identify unambiguously the entity but not the REST resource used to manage it, which is identified by its URL as described above. It is common that most implementations make use of instance ID to compose the URL (e.g., the book with instance ID 1492 could be represented by resource http://.../book/1492), but such an assumption should not be taken by API consumer to obtain the resource URL from its instance ID.

Links and References

Resources often lead to refer to other resources. In those cases, we have to provide an ID or an URL to a remote resource.

Paginated Collections (Optional)

n.a.

Query parameters (Optional)

In this case we can specify the parameter since in a GET method in order that the response will give us only information generated from a given timestamp in the format `YYYY-MM-DD HH:MM'.

Limits

n.a

Versions

This is the second version with multi-region, federation support.

Extensions

No apply yet.

Faults

The error code is returned in the body of the response for convenience. The message section returns a human-readable message that is appropriate for display to the end user. The details section is optional and may contain information—for example, a stack trace—to assist in tracking down an error. The detail section may or may not be appropriate for display to an end user.

Monitoring API Faults
Fault Element Associated Error Codes Description
Fault 500, 400, other codes possible Error in the operation
serviceUnavailable 503 The service is not available
unauthorized 401 You are not authorized to access to that operation. The token is not correct.
forbidden 403 It is forbidden
badRequest 400 The request has not been done correctly
badMediaType 415 The payload media is not correct
itemNotFound 404 It is not exist
badMethod 405 Method not allowed
overLimit 413 Request entity too large

API Operations

In this section we go in depth for each operation. In order to provide good comprehensive of the API operations, these operations were described in the Monitoring architecture. FI-WARE programmer's guide will also provide examples on how to use the API. The operations, which are not described here are under discussion and will be included in the following releases.

Monitoring API Root [/]

API entry point.

Retrieve Entry Point [GET]

  • Response 200 (application/hal+json)
    • Body

      {
          "_links": {
              "self": { "href": "/" },
              "regions": { "href": "/monitoring/regions", "templated": true }
              "host2hosts": { "href": "/monitoring/host2hosts", "templated": true }
          }
      }

Resource collection: regions

Region related APIs

Regions [/monitoring/regions]

Retrieve all regions.

  • Model (application/hal+json)
    • Body

      {
          "_links": {
              "self": { "href": "/monitoring/regions" }
          },
          "_embedded": {
              "regions": [
                  {
                      "_links" : {
                          "self": { "href": "/monitoring/regions/Trento" }
                      },
                      "id": "Trento"
                  }
              ]
          },
          "total_nb_users": "10",
          "total_nb_cores": "100",
          "total_nb_ram": "1000",
          "total_nb_disk": "10000",
          "total_nb_vm": "100000"
      }

List All Regions [GET]

  • Response 200 [Regions][]

Region [/monitoring/regions/{regionid}{?since}]

Retrieve a region. Parameter {since} is optional. If present, the measures after {since} are provided, otherwise metrics referred to the last monitoried interval are provided. Measures are aggregated on an hourly basis.

  • Parameters
    • regionid (string)
  • Model (application/hal+json)
    • Body

      {
          "_links": {
              "self": { "href": "/monitoring/regions/Trento" },
              "hosts": { "href": "/monitoring/regions/Trento/hosts" }
          },
          "id": "Trento",
          "name": "Trento",
          "country": "Italy",
          "latitude": "xyz",
          "longitude": "xyz",
          "nb_users": "10",
          "nb_cores": "100",
          "nb_ram": "1000",
          "nb_disk": "10000",
          "nb_vm": "100000",
          "measures": [
              {
                  "timestamp" : "2013-12-20 12.00",
                  "percCPULoad": {
                      "value": "123",
                      "description": "avarage of the percCPULoad for all the hosts"
                      },
                  "percRAMUsed": {
                      "value": "123",
                      "description": "avarage of the percCPULoad for all the hosts"
                      },
                  "percDiskUsed": {
                      "value": "123",
                      "description": "avarage of the percCPULoad for all the hosts"
                      }
                  }
              ]    
      }

Retrieve a Region [GET]

  • Parameters
    • since (optional, string) ... in the format `YYYY-MM-DD HH:MM'
  • Response 200 [Region][]

Resource collection: hosts

Host related APIs.

Hosts [/monitoring/regions/{regionid}/hosts]

Retrieve all hosts in a given region.

  • Parameters
    • regionid (string)
  • Model (application/hal+json)

    • Body

      {
          "_links": {
              "self": { "href": "/monitoring/regions/{regionid}/hosts" }
          },
          "hosts": [
              {
                  "_links" : {
                  "self": { "href": "/monitoring/regions/Trento/hosts/12345" }
                  },
                  "id": "12345"
              }
              ]
      }

List All Hosts for a given Region [GET]

  • Response 200 [Hosts][]

Host [/monitoring/regions/{regionid}/hosts/{hostid}{?since}]

Retrieve an host. Parameter {since} is optional. If present, the measures after {since} are provided, otherwise metrics referred to the last monitoried interval are provided. Measures are aggregated on an hourly basis.

  • Parameters
    • regionid (string)
    • hostid (string)
  • Model (application/hal+json)
    • Body

      {
          "_links": {
              "self": { "href": "/monitoring/regions/Trento/hosts/12345" },
              "services": { "href": "/monitoring/regions/Trento/hosts/12345/services" }
          },
          "regionid": "Trento",
          "hostid": "12345",
          "ipAddresses": [
                  {
                     "ipAddress": "1.2.3.4"
                  }
              ],
          "owd_endpoint_dest_default": "xyz",
          "bwd_endpoint_dest_default": "xyz",
          "owd_frequency": "123",
          "bwd_frequency": "123",
          "measures": [
              {
                  "timestamp" : "2013-12-20 12.00",
                  "percCPULoad": {
                      "value": "123",
                      "description": "desc"
                      },
                  "percRAMUsed": {
                      "value": "123",
                      "description": "desc"
                      },
                  "percDiskUsed": {
                      "value": "123",
                      "description": "desc"
                      },
                  "sysUptime": {
                      "value": "123",
                      "description": "desc"
                      },
                  "owd_status": {
                      "value": "123",
                      "description": "desc"
                      },
                  "bwd_status": {
                      "value": "123",
                      "description": "desc"
                      }
                  }
              ],    
          "traps": [
              {
                  "description": "desc"
              }
          ]    
      }

Retrieve an host [GET]

  • Parameters
    • since (optional, string) ... in the format `YYYY-MM-DD HH:MM'
  • Response 200 [Host][]


Resource collection: VMs

VM related APIs.

VMs [/monitoring/regions/{regionid}/vms]

Retrieve all VMs on a given region.

  • Parameters
    • regionid (string)
  • Model (application/hal+json)
    • Body

      {
          "_links": {
              "self": { "href": "/monitoring/regions/{regionid}/vms" }
          },
          "vms": [
              {
                  "_links" : {
                  "self": { "href": "/monitoring/regions/Trento/vms/54321" }
                  },
                  "id": "54321"
              }
              ]
      }

List All VMs for a given Region on a given Host [GET]

  • Response 200 [VMs][]

VM [/monitoring/regions/{regionid}/vms/{vmid}{?since}]

Retrieve a vm. Parameter {since} is optional. If present, the measures after {since} are provided, otherwise metrics referred to the last monitoried interval are provided. Measures are aggregated on an hourly basis.

  • Parameters
    • regionid (string)
    • vmid (string)
  • Model (application/hal+json)
    • Body

      {
          "_links": {
              "self": { "href": "/monitoring/regions/Trento/hosts/12345/vms/54321" },
              "services": { "href": "/monitoring/regions/Trento/vms/54321/services" }
          },
          "regionid": "Trento",
          "vmid": "54321",
          "ipAddresses": [
                  {
                     "ipAddress": "1.2.3.4"
                  }
              ],
          "measures": [
              {
                  "timestamp" : "2013-12-20 12.00",
                  "percCPULoad": {
                      "value": "123",
                      "description": "desc"
                      },
                  "percRAMUsed": {
                      "value": "123",
                      "description": "desc"
                      },
                  "percDiskUsed": {
                      "value": "123",
                      "description": "desc"
                      },
                  "sysUptime": {
                      "value": "123",
                      "description": "desc"
                      }
                  }
              ],    
          "traps": [
              {
                  "description": "desc"
              }
          ]    
      }

Retrieve a vm [GET]

  • Parameters
    • since (optional, string) ... in the format `YYYY-MM-DD HH:MM'
  • Response 200 [VM][]


Resource colletion: services

Service related APIs.

Services4Host [/monitoring/regions/{regionid}/hosts/{hostid}/services]

Retrieve all Services running on a given host.

  • Parameters
    • regionid (string)
    • hostid (string)
  • Model (application/hal+json)
    • Body

      {
          "_links": {
              "self": { "href": "/monitoring/regions/{regionid}/hosts/{hostid}/services" }
          },
          "services": [
              {
                  "_links" : {
                  "self": { "href": "/monitoring/regions/Trento/hosts/12345/services/apache2" }
                  },
                  "id": "apache2"
              }
              ]
      }

List all Services running on a given Host [GET]

  • Response 200 [Services4Host][]

Service4Host [/monitoring/regions/{regionid}/hosts/{hostid}/services/{serviceName}?since]

Retrieve a service. Parameter {since} is optional. If present, the measures after {since} are provided, otherwise measures referred to the last monitoried interval are provided. Measure status is always referred to the current status. Measure percUptime is present only if since is specified and is aggregated on an hourly basis.

  • Parameters
    • regionid (string)
    • hostid (string)
    • serviceName (string)
  • Model (application/hal+json)
    • Body

      {
          "_links": {
              "self": { "href": "/monitoring/regions/Trento/hosts/12345/service/apache2" }
          },
          "regionid": "Trento",
          "hostid": "12345",
          "serviceName": "apache2",
          "description": "this is apache2 service!",
          "measures": [
              {
                  "timestamp" : "2013-12-20 12.00",
                  "status": {
                      "value": "green/yellow/red",
                      "description": "status of the service. In case of realtime, it could be only red or green whereas in case of historical data it could be green if %upTime > 90%, 50%<=yellow<=90%, red < 50%"
                      }
                  }
              ]    
      }

Retrieve a service belonging to an host [GET]

  • Parameters
    • since (optional, string) ... in the format `YYYY-MM-DD HH:MM'
  • Response 200 [Service4Host][]

Services4VM [/monitoring/regions/{regionid}/vms/{vmid}/services]

Retrieve all Services running on a given VM.

  • Parameters
    • regionid (string)
    • vmid (string)
  • Model (application/hal+json)
    • Body

      {
          "_links": {
              "self": { "href": "/monitoring/regions/{regionid}/vms/{vmid}/services" }
          },
          "services": [
              {
                  "_links" : {
                  "self": { "href": "/monitoring/regions/Trento/vms/54321/services/apache2" }
                  },
                  "id": "apache2"
              }
              ]
      }

List all Services running on a given VM [GET]

  • Response 200 [Services4VM][]

Service4VM [/monitoring/regions/{regionid}/vms/{vmid}/services/{serviceName}?{since}]

Retrieve a service belonging to a VM. Parameter {since} is optional. If present, the measures after {since} are provided, otherwise measures referred to the last monitoried interval are provided. Measure status is always referred to the current status. Measure percUptime is present only if since is specified and is aggregated on an hourly basis.

  • Parameters
    • regionid (string)
    • vmid (string)
    • serviceName (string)
  • Model (application/hal+json)
    • Body

      {
          "_links": {
              "self": { "href": "/monitoring/regions/Trento/vms/54321/service/apache2" }
          },
          "regionid": "Trento",
          "vmid": "54321",
          "serviceName": "apache2",
          "description": "this is apache2 service!",
          "measures": [
              {
                  "timestamp" : "2013-12-20 12.00",
                  "status": {
                      "value": "green/yellow/red",
                      "description": "status of the service. In case of realtime, it could be only red or green whereas in case of historical data it could be green if %upTime > 90%, 50%<=yellow<=90%, red < 50%"
                      }
                  }
              ]    
      }

Retrieve a service belonging to an vm [GET]

  • Parameters
    • since (optional, string) ... in the format `YYYY-MM-DD HH:MM'
  • Response 200 [Service4VM][]

Services4Region [/monitoring/regions/{regionid}/services?{since}]

Retrieve the current status of the services running on a given region. If parameter {since} is specified, the the measures represents the %uptime of each service. + Parameters + regionid (string)

  • Model (application/hal+json)
    • Body

      {
          "_links": {
              "self": { "href": "/monitoring/regions/{regionid}/services" }
          },
      
           "measures": [
                  {
                  "timestamp" : "2013-12-20 12.00",
                  "novaServiceStatus": {
                      "value": "green/yellow/red",
                      "description": "status of the service. In case of realtime, it could be only red or green whereas in case of historical data it could be green if %upTime > 90%, 50%<=yellow<=90%, red < 50%"
                      },
                   "neutronServiceStatus": {
                      "value": "green/yellow/red",
                      "description": "status of the service. In case of realtime, it could be only red or green whereas in case of historical data it could be green if %upTime > 90%, 50%<=yellow<=90%, red < 50%"
                      },    
                   "cinderServiceStatus": {
                      "value": "green/yellow/red",
                      "description": "status of the service. In case of realtime, it could be only red or green whereas in case of historical data it could be green if %upTime > 90%, 50%<=yellow<=90%, red < 50%"
                      },    
                  "glanceServiceStatus": {
                      "value": "green/yellow/red",
                      "description": "status of the service. In case of realtime, it could be only red or green whereas in case of historical data it could be green if %upTime > 90%, 50%<=yellow<=90%, red < 50%"
                      },    
                  "IDMServiceStatus": {
                      "value": "green/yellow/red",
                      "description": "status of the service. In case of realtime, it could be only red or green whereas in case of historical data it could be green if %upTime > 90%, 50%<=yellow<=90%, red < 50%"
                      },       
                   "OverallStatus": {
                      "value": "green/yellow/red",
                      "description": "calculated from the previous statuses in this way: all green => green, > 50% green => yellow, <= 50% green => red"
                      } 
                  }    
              ]
      }

List all Services running on a given region [GET]

  • Parameters
    • since (optional, string) ... in the format `YYYY-MM-DD HH:MM'
  • Response 200 [Services4Region][]


Resource collection: network elements

Network Element related APIs.

NEs [/monitoring/regions/{regionid}/nes]

Retrieve all NEs monitored in a given region.

  • Parameters
    • regionid (string)
  • Model (application/hal+json)
    • Body

      {
          "_links": {
              "self": { "href": "/monitoring/regions/{regionid}/nes" }
          },
          "nes": [
              {
                  "_links" : {
                  "self": { "href": "/monitoring/regions/Trento/12345" }
                  },
                  "id": "12345"
              }
              ]
      }

List all NEs for a given Region on a given Host [GET]

  • Response 200 [NEs][]

NE [/monitoring/regions/{regionid}/nes/{neid}{?since}]

Retrieve a network element. Parameter {since} is optional. If present, the measures after {since} are provided, otherwise metrics referred to the last monitoried interval are provided. Measures are aggregated on an hourly basis.

  • Parameters
    • regionid (string)
    • neid (string)
  • Model (application/hal+json)
    • Body

      {
          "_links": {
              "self": { "href": "/monitoring/regions/Trento/nes/54321" }
          },
          "regionid": "Trento",
          "neid": "54321",
          "neType": "network element type",
          "measures": [
              {
                  "timestamp" : "2013-12-20 12.00",
                  "ifPhysAddress": {
                      "value": "123",
                      "description": "desc"
                      },
                  "ifOperStatus": {
                      "value": "123",
                      "description": "desc"
                      },
                  "ifInOctects": {
                      "value": "123",
                      "description": "desc"
                      },
                  "ifInErrors": {
                      "value": "123",
                      "description": "desc"
                      },
                  "ifInUCastPkts": {
                      "value": "123",
                      "description": "desc"
                      },
                  "ifInDiscard": {
                      "value": "123",
                      "description": "desc"
                      },
                  "ifOutOctects": {
                      "value": "123",
                      "description": "desc"
                      },
                  "ifOutErrors": {
                      "value": "123",
                      "description": "desc"
                      },
                  "ifOutUCastPkts": {
                      "value": "123",
                      "description": "desc"
                      },
                  "ifOutDiscard": {
                      "value": "123",
                      "description": "desc"
                      }   
                  }
              ],    
          "traps": [
              {
                  "description": "desc"
              }
          ]    
      }

Retrieve a network element [GET]

  • Parameters
    • since (optional, string) ... in the format `YYYY-MM-DD HH:MM'
  • Response 200 [NE][]


Resource collection: host2hosts

Host related APIs.

Host2Hosts [/monitoring/host2hosts]

Retrieve all host2hosts.

  • Model (application/hal+json)
    • Body

      {
          "_links": {
              "self": { "href": "/monitoring/host2hosts" }
          },
          "host2hosts": [
              {
                  "_links" : {
                  "self": { "href": "/monitoring/host2hosts/Trento-12345;Berlin-5678" }
                  },
                  "id": "Trento-12345;Berlin-5678"
              }
              ]
      }

List All Host2Hosts [GET]

  • Response 200 [Host2Hosts][]

Host2Host [/monitoring/host2hosts/{source};{dest}{?since}]

Retrieve a host2host object representing a connection between two hosts identified by the parameters {source} and {dest}, each one in the form regionid-hostid. Parameter {since} is optional. If present, the measures after {since} are provided, otherwise metrics referred to the last monitoried interval are provided. Measures are aggregated on an hourly basis.

  • Parameters
    • source (string)
    • dest (string)
  • Model (application/hal+json)
    • Body

      {
          "_links": {
              "self": { "href": "/monitoring/host2hosts/Trento-12345;Berlin-5678" }
          },
          "source": "Trento-12345",
          "dest": "Berlin-5678",
      
          "measures": [
              {
                  "timestamp" : "2013-12-20 12.00",
                  "owd_min": {
                      "value": "123",
                      "description": "desc"
                      },
      
                  "owd_max": {
                      "value": "123",
                      "description": "desc"
                      },   
                  "owd_avg": {
                      "value": "123",
                      "description": "desc"
                      },       
                  "jitter": {
                      "value": "123",
                      "description": "desc"
                      },  
                  "packet_loss": {
                      "value": "123",
                      "description": "desc"
                      }, 
                  "bandwidth_avg": {
                      "value": "123",
                      "description": "desc"
                      }    
                  }
              ]    
      }

Retrieve an host2host [GET]

  • Parameters
    • since (optional, string) ... in the format `YYYY-MM-DD HH:MM'
  • Response 200 [Host2Host][]
Personal tools
Create a book