4.21   Reports

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

The Fields: Reports, 8.4.22 Fields: Report Samples, and 8.4.17 Fields: Report Datapoints reference sections contain the type and description of all fields in the Report, Sample, and Datapoint objects. They also contain 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 --

In this section:

4.21.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 https://localhost:8080/mws/rest/reports?api-version=3[&query={"field":"value"}&sort={"field":<1|-1>}]
GET https://localhost:8080/mws/rest/reports/<id>?api-version=3
GET https://localhost:8080/mws/rest/reports/<name>?api-version=3

4.21.1.A  Get All Reports (No Data)

URLs and Parameters

GET https://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 3.3  Global URL Parameters for available URL parameters.

Sample Response

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

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

Samples

GET https://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"
    }
  ]
}

4.21.1.B  Get Single Report (With Data)

URLs and Parameters

GET https://localhost:8080/mws/rest/reports/<id>?api-version=3
GET https://localhost:8080/mws/rest/reports/<name>?api-version=3
Parameter Required Type Value 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 3.3  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": "2024-12-02 17:28:22 UTC",
      "startDate": "2024-12-02 17:28:22 UTC",
      "firstSampleDate": null,
      "lastSampleDate": null,
      "data": null
    },
        {
      "endDate": "2024-12-02 17:28:23 UTC",
      "startDate": "2024-12-02 17:28:37 UTC",
      "firstSampleDate": "2024-12-02 17:28:23 UTC",
      "lastSampleDate": "2024-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
}

4.21.1.C  Get Datapoints for Single Report

URLs and Parameters

GET https://localhost:8080/mws/rest/reports/<id>/datapoints?api-version=3[&query={"field":"value"}&sort={"field":<1|-1>}]
GET https://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 3.3  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": "2024-12-02 17:28:22 UTC",
      "startDate": "2024-12-02 17:28:22 UTC",
      "firstSampleDate": null,
      "lastSampleDate": null,
      "data": null
    },
        {
      "endDate": "2024-12-02 17:28:37 UTC",
      "startDate": "2024-12-02 17:28:37 UTC",
      "firstSampleDate": "2024-12-02 17:28:23 UTC",
      "lastSampleDate": "2024-12-02 17:28:23 UTC",
      "data":       {
        "utilization": 99.89,
        "time": 27.433333333333337
      }
    }
  ]
}

4.21.2 Getting Samples for Reports

The HTTP GET method is used to retrieve Sample information.

Quick Reference

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

4.21.2.A  Get Samples for Report

URLs and Parameters

GET https://localhost:8080/mws/rest/reports/<id>/samples?api-version=3[&query={"field":"value"}&sort={"field":<1|-1>}]
GET https://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 3.3  Global URL Parameters for available URL parameters.

Sample Response

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

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

4.21.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 https://localhost:8080/mws/rest/reports?api-version=3

4.21.3.A  Create Report

URLs and Parameters

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

See 3.3  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":"2024-12-01 19:16:57 UTC",
			"endDate":"2024-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 https://localhost:8080/mws/rest/reports?api-version=3 (Minimal report without datapoints)
------------------------------------

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

4.21.4 Creating Samples

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

Quick Reference

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

4.21.4.A  Create Samples for Report

URLs and Parameters

POST https://localhost:8080/mws/rest/reports/<id>/samples?api-version=3
POST https://localhost:8080/mws/rest/reports/<name>/samples?api-version=3
Parameter Required Type Value 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 3.3  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":"2024-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"]}

4.21.5 Deleting Reports

The HTTP DELETE method is used to delete Reports.

Quick Reference

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

4.21.5.A  Delete Report

URLs and Parameters

DELETE https://localhost:8080/mws/rest/reports/<id>?api-version=3
DELETE https://localhost:8080/mws/rest/reports/<name>?api-version=3
Parameter Required Type Value 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 3.3  Global URL Parameters for available URL parameters.

Sample Response

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

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

Related Topics