- URL: https://<usageReports-url>/add(POST only)
- Required Capability:Default administrator role
- Version Introduced:10.3
Description
The add operation creates a new usage report. A usage report is created by submitting a JSON representation of it to this operation.
Caution:
For deployments using a version of ArcGIS Enterprise 11.0 and lower, if you include the ServiceRunningInstancesMax metric in a report you cannot include any other metric value in the same report. To view usage statistics for the these other metrics, you'll need to create a separate usage report. Deployments using a version of ArcGIS Enterprise 11.1 and higher can combine all metrics, including ServiceRunningInstancesMax, in a single usage report.
Request parameters
| Parameter | Details |
|---|---|
| reportname | The unique name of the report. Example |
| since | The time duration for the report. CUSTOM represents a time range that is specified using the from and to parameters. Values: LAST_DAY (previous 24 hours) | LAST_WEEK (previous 7 days) | LAST_MONTH (previous 30 days) | CUSTOM |
| from (Optional, used if since is set to CUSTOM) | The time stamp (milliseconds since UNIX epoch, namely January 1, 1970, 00:00:00 GMT) for the beginning period of the report. Example |
| to (Optional, used if since is set to CUSTOM) | The time stamp (milliseconds since UNIX epoch, namely January 1, 1970, 00:00:00 GMT) for the ending period of the report. Example |
| aggregationInterval (Optional) | The time interval in minutes. Server metrics are summarized and returned for time slices using the specified interval. The time range for the report, specified using the since parameter (and the from and to parameters when since is CUSTOM) is split into multiple slices, each covering a time interval. Server metrics are then summarized for each time slice and returned as data points in the report data. When the aggregationInterval value is not specified, the following defaults are used:
Note:If the samplingInterval value specified in Usage Reports Settings is more than the aggregationInterval value, the samplingInterval value is used instead. |
| queries | A list of queries used to generate the report. Specify the list as an array of JSON objects representing the queries. Each query specifies the list of metrics to be queries for a given set of resourceURIs values. For more information about query properties, see the table below. Example |
| metadata | A JSON object. This is typically used for storing presentation tier data for the usage report, such as report title, colors, line styles, and so on. It's also used to denote visibility in ArcGIS Server Manager for reports created with the Administrator Directory. To make a report created in the Administrator Directory visible to ArcGIS Server Manager, include "managerReport":true in the metadata JSON object. When this value is not set (default), reports are not visible in ArcGIS Server Manager. This behavior can be extended to any client that wants to interact with the Administrator Directory. Any user-created value must be processed by the client. Example |
| f | The response format. The default value is html. Values: html | json | pjson |
Query parameters
| Property | Description |
|---|---|
| resourceURIs | A comma-separated list of resource URIs used to report metrics. This specifies services or folders that are used to gather metrics. The resourceURI is formatted as below:
Example |
| metrics | A comma-separated list of metrics to be reported. The following are supported metrics:
Note:The RequestsTimedOut and ServiceRunningInstancesMax metrics are not applicable to hosted feature services. Example |
Example usage
Request JSON syntax
{
"reportname": [unique name or id of the report],
"since": ["LAST_DAY | LAST_WEEK | LAST_MONTH | CUSTOM"], //Optional, specified when "since" is CUSTOM"
"from" : [timestamp], to": [timestamp], //Optional, specified when "since" is CUSTOM
"aggregationInterval": [minutes], //Optional, aggregation interval in minutes
"queries": [
{
"resourceURIs": ["services/Map_bv_999.MapServer"], //Comma separated list of services and/or folders
"metrics": ["RequestCount"] // Comma-separated list of metrics
}
],
"metadata": "This could be any String or JSON Object."
}Single query example
A sample POST request for the add operation that demonstrates a single query is shown below. This example is formatted for readability:
POST /webadaptor/admin/usagereports/add HTTP/1.1
Host: machine.domain.com
Content-Type: application/x-www-form-urlencoded
Content-Length: []
usagereport={
"reportname": 1394219221008,
"since": "LAST_MONTH",
"queries": [
{
"resourceURIs": [
"services/Map_bv_999.MapServer"
],
"metrics": [
"RequestCount"
]
}
],
"metadata": "This could be any String or JSON Object typically used for storing report metadata."
}&f=jsonMultiple queries example
A sample POST request for the add operation that demonstrates multiple queries is shown below. This example is formatted for readability:
POST /webadaptor/admin/usagereports/add HTTP/1.1
Host: machine.domain.com
Content-Type: application/x-www-form-urlencoded
Content-Length: []
usagereport={
"reportname": "Server Statistics",
"since": "LAST_WEEK",
"aggregationInterval": 5,
"queries": [
{
"resourceURIs": [
"services/SampleWorldCities.MapServer",
"services/System"
],
"metrics": [
"RequestCount",
"RequestsFailed"
]
},
{
"resourceURIs": [
"services/System/CachingTools.GPServer"
],
"metrics": [
"RequestAvgResponseTime",
"RequestsTimedOut"
]
}
],
"metadata": "This is a random test String that could contain report metadata in any format."
}&f=jsonJSON Response example
{"status": "success"}