Configure access to metrics

The metrics API captures information about the components of ArcGIS Enterprise and the machines where those components are running. To make use of the information exposed by the metrics API, you will need to create a key or token to authorize access to the metrics, configure Prometheus to scrape the metrics, and optionally configure Grafana to visualize the metrics.

Metrics are enabled by default, but you can disable metrics if necessary.

Configure access permissions

Before scraping metrics, ensure that you enable the correct access permissions.

The account that runs each software component must be part of the Performance Monitor Group to collect machine metrics.

For ArcGIS Enterprise deployments, including any federated servers, authenticate requests with an API key. For a stand-alone ArcGIS Server sites, authenticate requests using an administrative token.

Note:

Successful authentication to obtain metrics for any ArcGIS Enterprise component requires the Portal for ArcGIS service to be accessible. Authentication for ArcGIS Data Store metrics additionally requires that the hosting server is accessible.

Obtain an API key using ArcGIS Enterprise

To use ArcGIS Enterprise to obtain an API key appropriate for accessing the metrics API, complete the following steps:

Sign in to your organization as an administrator.
From the My content tab of the content page, click New item and click Developer credentials.
Select API key credentials, then click Next.
Select Private application with selected privileges and access, then click Next.
Select No item access, then click Next.
Select the Observability privilege, then click Next.
Select an expiration date and optionally any referrer URLs, then click Next.
Add a title for the API key item and optionally tags and a summary, then click Next.
Review the API key configuration for accuracy, then click Next.
Ensure the option to Generate the API key now is selected, then click Next.
Copy the API key.

Obtain an administrative token using ArcGIS Server

For stand-alone ArcGIS Server sites, you can obtain an administrative token using ArcGIS Server. For federated ArcGIS Server sites, obtain an API key instead.

Sign in to the ArcGIS Server Administrator Directory as a user with administrative privileges.
Click generateToken.
Provide the following information:
- Username—The username of a user with administrator privileges
- Password—The password for the specified username
- Client—HTTP referrer
- HTTP referrer—A URL that matches the referer specified in your Prometheus configuration. The example Prometheus configuration uses ARCGIS.COM as the referer.
Optionally set an expiration time in minutes.

Note:

The default expiration time is 60 minutes. The default maximum expiration time is 1440 minutes (24 hours). To generate a longer-lived token, an administrator must update the token configuration to increase the longTimeout property before generating a token. Exercise caution when increasing the longTimeout value to ensure the updated value meets your security requirements.
Click Generate.
Copy the token.

Configure Prometheus Server

To add the metrics API as a scrape target, you will need to update your Prometheus configuration. For instructions to deploy Prometheus, see the deployment guide.

Configure a separate scrape job for each component of ArcGIS Enterprise that you want to obtain metrics from. The following information is required for each scrape configuration:

job_name—A unique name for the job.
http_sd_configs—The configuration for the service discovery endpoint. The following information is required:
- url—The URL of the service discovery endpoint. This will be in the format <scheme>://<machine fqdn>/<context>/monitoring/discovery.
  
  For Portal for ArcGIS and ArcGIS Server, it is recommended to use the URL of the ArcGIS Web Adaptor or reverse proxy. For example, an organization might use https://portal.example.com/portal/monitoring/discovery for service discovery for portal metrics or https://gisserver.example.com/server/monitoring/discovery for service discovery for an ArcGIS Server site.
  
  For ArcGIS Data Store, you must specify the machine where the relational store is installed and the port number. For example https://relational.example.com:2443/arcgis/monitoring/discovery
- bearer_token or bearer_token_file—The ArcGIS Enterprise API key or ArcGIS Server administrative token you created.
  
  The token is provided as part of http_sd_configs to authenticate to the service discovery endpoint.
bearer_token or bearer_token_file—The ArcGIS Enterprise API key or ArcGIS Server administrative token you created.

The token is provided again as part of the scrape configuration to authenticate to the metrics collection endpoints.
metrics_path—The value must be /arcgis/monitoring/metrics

Scraping machine metrics requires making requests to each individual machine directly. These requests do not go through any ArcGIS Web Adaptor or reverse proxy you have configured. Make sure that Prometheus Server can access each ArcGIS Server machine over port 6443 and each Portal for ArcGIS machine over port 7443.
scheme—Either http or https depending on whether the URL specified in https_sd_configs is configured to be accessible over http or https.

See the example Prometheus configuration for a YAML template file for scraping ArcGIS Enterprise metrics. You can use the example dashboard template for configuring Grafana to visualize the metrics after collecting them with Prometheus.

Configure the metrics cleaning interval

The default interval for clearing metrics from the system is 1 hour, which is appropriate for most organizations. See Clearing metrics for considerations to take into account when changing the clearing interval.

If you need to change the clearing interval, the steps to do so depend on the ArcGIS Enterprise component.

Configure the metrics clearing interval for ArcGIS Server

Sign in to the ArcGIS Server Administrator Directory as a user with administrative privileges.
Navigate to System > Properties > Update.
In the Properties text box, add a value for the metricsClearingIntervalInHours key as JSON.

For example, to set an interval of two hours, use the following JSON:
```
{
   "isMetricsEnabled": true,
   "metricsClearingIntervalInHours": 2
}
```
Click Update.
Restart the ArcGIS Server service.

Configure the metrics clearing interval for Portal for ArcGIS

Sign in to the Portal Administrator Directory as an administrator of your organization.
Navigate to System > Properties > Update Properties.
In the Properties text box, add a value for the metricsClearingIntervalInHours key as JSON.

For example, to set an interval of two hours, use the following JSON:
```
{
   "isMetricsEnabled": true,
   "metricsClearingIntervalInHours": 2
}
```
Click Update Properties.

This operation will automatically restart the Portal for ArcGIS service.

Configure the metrics clearing interval for ArcGIS Data Store

Run the datastoremetrics utility on the machine where the relational store is installed and specify the interval parameter. For example, to set an interval of two hours, use the following command:

./datastoremetrics --enabled true --interval 2

datastoremetrics --enabled true --interval 2

To change the metrics clearing interval for both a primary and a standby relational store, you must run the utility on both.

Disable metrics

The steps to disable metrics depend on the ArcGIS Enterprise component.

Disable metrics for an ArcGIS Server site

Sign in to the ArcGIS Server Administrator Directory as a user with administrative privileges.
Navigate to System > Properties > Update.
In the Properties text box, set the isMetricsEnabled key to false:
```
{"isMetricsEnabled": false}
```
Click Update.
Restart the ArcGIS Server service.

Disable metrics for Portal for ArcGIS

Sign in to the Portal Administrator Directory as an administrator of your organization.
Navigate to System > Properties > Update Properties.
In the Properties text box, set the isMetricsEnabled key to false:
```
{"isMetricsEnabled": false}
```
Click Update Properties.

This operation will automatically restart the Portal for ArcGIS Service.

Disable metrics for ArcGIS Data Store

To disable metrics for ArcGIS Data Store, run the datastoremetrics utility on the machine where the relational store is installed using the following command:

./datastoremetrics --enabled false

datastoremetrics --enabled false

To disable metrics for both a primary and a standby relational store, you must run the utility on both.