Create Usage Report—ArcGIS REST APIs

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 the usage report to this operation.

Caution:

If you include the ServiceRunningInstancesMax metric in a report, you cannot include other instances in the same report. If you want to view usage statistics for the ServiceRunningInstancesMax metric as well as other metrics, create a separate usage report.

Request parameters


Parameter	Details
reportname	The unique name of the report. Example `"reportname": "Server Statistics"`
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 timestamp (milliseconds since UNIX epoch, namely January 1, 1970, 00:00:00 GMT) for the beginning period of the report. Example `"from": "1568230820504"`
to (Optional, used if since is set to CUSTOM)	The timestamp (milliseconds since UNIX epoch, namely January 1, 1970, 00:00:00 GMT) for the ending period of the report. Example `"to": "1568185200000"`
aggregationInterval (Optional)	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 from and to 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 is not specified, the following defaults are used: LAST_DAY: 30 minutes LAST_WEEK: 4 hours LAST_MONTH: 24 hours CUSTOM: 30 minutes up to 1 day, 4 hours up to 1 week, 1 day up to 30 days, and 1 week for longer periods. Note: If the samplingInterval specified in Usage Reports Settings is more than the aggregationInterval, the samplingInterval is used instead.
queries	A list of queries for which to generate the report. You need to 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. For more information on query properties, see the table below. Example `"queries": [ { "resourceURIs": ["services/Map_bv_999.MapServer"], "metrics": ["RequestCount"] } ]`
metadata	Can be any JSON Object. Typically used for storing presentation tier data for the usage report, such as report title, colors, line-styles, etc. Also used to denote visibility in ArcGIS Server Manager for reports created with the Administrator Directory. To make any report created in the Administrator Directory visible to Manager, include "managerReport":true in the metadata JSON object. When this value is not set (default), reports are not visible in Manager. This behavior can be extended to any client that wants to interact with the Administrator Directory. Any user-created value will need to be processed by the client. Example `"metadata": "This could be any String or JSON Object."`
f	The response format. The default value is html. Values: html \| json \| pjson

Query parameters


Property	Description
resourceURIs	Comma separated list of resource URIs for which to report metrics. Specifies services or folders for which to gather metrics. The resourceURI is formatted as below: services/—Entire Site services/Folder/—Folder within a Site. Reports metrics aggregated across all services within that Folder and Sub-Folders. services/Folder/ServiceName.ServiceType—Service in a specified folder, for example: services/Map_bv_999.MapServer. services/ServiceName.ServiceType—Service in the root folder, for example: Map_bv_999.MapServer Example `"resourceURIs": ["services/SampleWorldCities.MapServer","services/System"]`
metrics	A comma-separated list of metrics to be reported. Supported metrics are: RequestCount—the number of requests received RequestsFailed—the number of requests that failed RequestsTimedOut—the number of requests that timed out RequestMaxResponseTime—the maximum response time RequestAvgResponseTime—the average response time ServiceRunningInstancesMax—the maximum number of active (running) service instances, sampled at one-minute intervals for a specified service. If you include this metric, it must be the only metric included in the report. Note: The RequestsTimedOut and ServiceRunningInstancesMax metrics are not applicable to hosted feature services. Example `"metrics": ["RequestCount","RequestsFailed"]`

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

Below is a sample POST request for add that demonstrates a single query. 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=json

Multiple queries example

Below is a sample POST request for add that demonstrates multiple queries. 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=json

JSON Response example

{"status": "success"}

ArcGIS REST APIs