(Click to open topic with navigation)

5.250 Reports

This section describes behavior of the reporting framework in Moab Web Services. It contains the URLs, request bodies, and responses delivered to and from MWS.

The Fields: Reports, Fields: Report Samples, and Fields: Report Datapoints reference sections contain the type and description of all fields in the Report, Sample, and Datapoint objects. They also contains details regarding which fields are valid during PUT and POST actions.

Supported methods

Resource GET PUT POST DELETE
/rest/reports Get All Reports (No Data) -- Create Report Delete Report
/rest/reports/<name> Get Single Report (With Data) -- -- --
/rest/reports/<id> Get Single Report (With Data) -- -- --
/rest/reports/<name>/datapoints Get Datapoints for Single Report -- -- --
/rest/reports/<id>/datapoints Get Datapoints for Single Report -- -- --
/rest/reports/<name>/samples Get Samples for Report -- Create Samples for Report --
/rest/reports/<id>/samples Get Samples for Report -- Create Samples for Report --

This topic contains these sections:

5.250.1 Getting Reports

The HTTP GET method is used to retrieve Report information. Queries for all reports with no attached data and a single report with associated data are available.

Quick reference

GET http://localhost:8080/mws/rest/reports?api-version=3[&query={"field":"value"}&sort={"field":<1|-1>}]
GET http://localhost:8080/mws/rest/reports/<id>?api-version=3
GET http://localhost:8080/mws/rest/reports/<name>?api-version=3

5.250.1.A Get All Reports (No Data)

URLs and parameters

GET http://localhost:8080/mws/rest/reports?api-version=3[&query={"field":"value"}&sort={"field":<1|-1>}]
Parameter Required Type Description Example
query No JSON

Queries for specific results.

It is possible to query reports by one or more fields based on MongoDB query syntax.

 query={"reportSize":4}
sort No JSON Sort the results. Use 1 for ascending and -1 for descending. sort={"name":-1}

See Global URL Parameters for available URL parameters.

Sample response

JSON response
------------------------------------

{
  "totalCount": 1,
  "resultCount": 1,
  "results": [  {
    "id": "3efe5c670be86ba8560397ff",
    "name": "cpu-util"
	…
  }]
}

Samples

GET http://localhost:8080/mws/rest/reports?api-version=3&fields=id,name
------------------------------------

{
  "totalCount": 3,
  "resultCount": 3,
  "results":   [
        {
      "id": "3efe5c670be86ba8560397ff",
      "name": "cpu-util"
    },
        {
      "id": "3efe5c670be86ba856039800",
      "name": "cpu-temp"
    },
        {
      "id": "3efe5c670be86ba856039801",
      "name": "cpu-load"
    }
  ]
}

5.250.1.B Get Single Report (With Data)

URLs and parameters

GET http://localhost:8080/mws/rest/reports/<id>?api-version=3
GET http://localhost:8080/mws/rest/reports/<name>?api-version=3
Parameter Required Type Valid values Description
id Yes String -- The unique identifier of the report.
name Yes String -- The name of the report.

Only one of id or name are required.

See Global URL Parameters for available URL parameters.

Sample response

In the example below, the first datapoint has a null data element, which means that the minimumSampleSize configured for the report was not met when consolidating the datapoint. The second datapoint contains actual data.

JSON response
------------------------------------

{
  "consolidationFunction": "average",
  "datapointDuration": 15,
  "datapoints":   [
        {
      "endDate": "2011-12-02 17:28:22 UTC",
      "startDate": "2011-12-02 17:28:22 UTC",
      "firstSampleDate": null,
      "lastSampleDate": null,
      "data": null
    },
        {
      "endDate": "2011-12-02 17:28:23 UTC",
      "startDate": "2011-12-02 17:28:37 UTC",
      "firstSampleDate": "2011-12-02 17:28:23 UTC",
      "lastSampleDate": "2011-12-02 17:28:30 UTC",
      "data":       {
        "utilization": 99.89,
        "time": 27.433333333333337
      }
    }
  ],
  "description": "Example of CPU utilization reporting",
  "id": "3efe5c670be86ba8560397ff",
  "keepSamples": false,
  "minimumSampleSize": 1,
  "name": "cpu-util",
  "reportSize": 2
}

5.250.1.C Get Datapoints for Single Report

URLs and parameters

GET http://localhost:8080/mws/rest/reports/<id>/datapoints?api-version=3[&query={"field":"value"}&sort={"field":<1|-1>}]
GET http://localhost:8080/mws/rest/reports/<name>/datapoints?api-version=3[&query={"field":"value"}&sort={"field":<1|-1>}]
Parameter Required Type Description Example
id Yes String The unique identifier of the report. --
name Yes String The name of the report. --
query No JSON Queries for specific results. query={"reportSize":4}
sort No JSON Sort the results. Use 1 for ascending and -1 for descending. sort={"name":-1}

Only one of id or name are required.

It is possible to query reports by one or more fields based on MongoDB query syntax.

See Global URL Parameters for available URL parameters.

Sample response

This function is exactly the same as Get Single Report (With Data). No report metadata (i.e. description, minimumSampleSize, etc.) is returned.

JSON response
------------------------------------

{
  "resultCount":1,
  "totalCount":1,
  "results":[
        {
      "endDate": "2011-12-02 17:28:22 UTC",
      "startDate": "2011-12-02 17:28:22 UTC",
      "firstSampleDate": null,
      "lastSampleDate": null,
      "data": null
    },
        {
      "endDate": "2011-12-02 17:28:37 UTC",
      "startDate": "2011-12-02 17:28:37 UTC",
      "firstSampleDate": "2011-12-02 17:28:23 UTC",
      "lastSampleDate": "2011-12-02 17:28:23 UTC",
      "data":       {
        "utilization": 99.89,
        "time": 27.433333333333337
      }
    }
  ]
}

5.250.2 Getting Samples for Reports

The HTTP GET method is used to retrieve Sample information.

Quick reference

GET http://localhost:8080/mws/rest/reports/<id>/samples?api-version=3[&query={"field":"value"}&sort={"field":<1|-1>}]
GET http://localhost:8080/mws/rest/reports/<name>/samples?api-version=3[&query={"field":"value"}&sort={"field":<1|-1>}]

5.250.2.A Get Samples for Report

URLs and parameters

GET http://localhost:8080/mws/rest/reports/<id>/samples?api-version=3[&query={"field":"value"}&sort={"field":<1|-1>}]
GET http://localhost:8080/mws/rest/reports/<name>/samples?api-version=3[&query={"field":"value"}&sort={"field":<1|-1>}]
Parameter Required Type Description Example
id Yes String The unique identifier of the report. --
name Yes String The name of the report. --
query No JSON Queries for specific results. query={"reportSize":4}
sort No JSON Sort the results. Use 1 for ascending and -1 for descending. sort={"name":-1}

Only one of id or name are required.

It is possible to query reports by one or more fields based on MongoDB query syntax.

See Global URL Parameters for available URL parameters.

Sample response

JSON response
------------------------------------

{
  "totalCount": 1,
  "resultCount": 1,
  "results": [  {
	"timestamp": "2011-12-02 17:28:37 UTC"
	"data":{
		"cpu1":2.3,
		"cpu2":1.2,
		"cpu3":0.0,
		"cpu4":12.1
	},
	…
  }]
}

5.250.3 Creating Reports

The HTTP POST method is used to create Reports. Operations are available to create reports with or without historical datapoints.

Quick reference

POST http://localhost:8080/mws/rest/reports?api-version=3

5.250.3.A Create Report

URLs and parameters

POST http://localhost:8080/mws/rest/reports?api-version=3

See Global URL Parameters for available URL parameters.

Request body

To create a report, several fields are required as documented in Fields: Reports.

The request body below shows all the fields that are available during report creation.

JSON request body
------------------------------------

{
	"name":"cpu-util",
	"description":"An example report on cpu utilization",
	"consolidationFunction":"average",
	"datapointDuration":15,
	"minimumSampleSize":1,
	"reportSize":2,
	"keepSamples":true,
	"reportDocumentSize":1024,
	"datapoints":[
		{
			"startDate":"2011-12-01 19:16:57 UTC",
			"endDate":"2011-12-01 19:16:57 UTC",
			"data":{
				"time":30,
				"util":99.98
			}
		}
	]
}

Sample response

{
	"messages":["Report cpu-util created"],
	"id":"3efe5c670be86ba8560397ff",
	"name":"cpu-util"
}

Samples

POST http://localhost:8080/mws/rest/reports?api-version=3 (Minimal report without datapoints)
------------------------------------

{
	"name":"cpu-util",
	"datapointDuration":15,
	"reportSize":2
}

5.250.4 Creating Samples

The HTTP POST method is used to create samples for Reports.

Quick reference

POST http://localhost:8080/mws/rest/reports?api-version=3

5.250.4.A Create Samples for Report

URLs and parameters

POST http://localhost:8080/mws/rest/reports/<id>/samples?api-version=3
POST http://localhost:8080/mws/rest/reports/<name>/samples?api-version=3
Parameter Required Type Valid values Description
id Yes String -- The unique identifier of the report.
name Yes String -- The name of the report.

Only one of id or name are required.

See Global URL Parameters for available URL parameters.

Request body

To create samples for a report, simply send data and an optional timestamp to the URL above. The request body below shows all the fields that are available during sample creation. Note that the data field can contain arbitrary JSON.

JSON request body
------------------------------------

{
	"timestamp":"2011-12-01 19:16:57 UTC",
	"agent":"my agent",
	"data":{
		"cpu1":2.3,
		"cpu2":1.2,
		"cpu3":0.0,
		"cpu4":12.1
	}
}

Sample response

{"messages":["1 sample(s) created for report cpu-util"]}

5.250.5 Deleting Reports

The HTTP DELETE method is used to delete Reports.

Quick reference

DELETE http://localhost:8080/mws/rest/reports/<id>?api-version=3
DELETE http://localhost:8080/mws/rest/reports/<name>?api-version=3

5.250.5.A Delete Report

URLs and parameters

DELETE http://localhost:8080/mws/rest/reports/<id>?api-version=3
DELETE http://localhost:8080/mws/rest/reports/<name>?api-version=3
Parameter Required Type Valid values Description
id Yes String -- The unique identifier of the report.
name Yes String -- The name of the report.

Only one of id or name are required.

See Global URL Parameters for available URL parameters.

Sample response

JSON response
------------------------------------

{"messages":["Report cpu-util deleted"]}

Related Topics 

© 2016 Adaptive Computing