--- title: Monitor services description: The following sections describe how to set up and maintain monitoring in your deployment to ensure appropriate performance and service availability. component: web-agents version: 2025.11 page_id: web-agents:maintenance-guide:monitoring canonical_url: https://docs.pingidentity.com/web-agents/2025.11/maintenance-guide/monitoring.html section_ids: monitor-prometheus: Monitor with Prometheus access-prometheus-endpoint: Access the Prometheus endpoint monitor-types: Monitoring types prometheus-metrics: Metrics at the Prometheus endpoint notification-metrics: Notification metrics policy-decision-metrics: Policy decision metrics cache-metrics: Cache metrics connections-metrics: Connection metrics request-metrics: Request metrics monitor-endpoint: Monitor with the monitoring endpoint (deprecated) access-monitoring-endpoint: Access the monitoring endpoint monitor-metrics: Metrics at the monitoring endpoint (deprecated) --- # Monitor services The following sections describe how to set up and maintain monitoring in your deployment to ensure appropriate performance and service availability. ## Monitor with Prometheus Web Agent automatically exposes a monitoring endpoint where Prometheus can scrape metrics in a standard Prometheus format (version 0.0.4). You can find information about installing and running Prometheus in the [Prometheus documentation](https://prometheus.io/docs/introduction/overview/). The Prometheus endpoint is protected by HTTP Basic Authentication. To access it, provide the agent URL, and the agent profile name and password. Always use HTTPS for secure connections to client applications. The metrics returned are described in [Metrics at the Prometheus endpoint](#prometheus-metrics). | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Tools such as Grafana are available to create customized charts and graphs based on the information collected by Prometheus. Learn more on the [Grafana website](https://grafana.com). | ### Access the Prometheus endpoint 1. Install a Web Agent as described in the [Installation](../installation-guide/preface.html), and use the agent to protect a web application. For example, set up the example in [Policy enforcement](../user-guide/pep.html). 2. Access the Prometheus endpoint as follows, where `https://agent.example.com:443` is the agent URL, `web-agent` is the agent profile name and `password` is the agent profile password: ```none $ curl https://agent.example.com:443/agent/metrics --user web-agent:password ``` The metrics are displayed: ```none # TYPE policy_change counter # HELP policy_change_total number of policy updates policy_change_total{topic="notification"} 0 # TYPE config_change counter # HELP config_change_total number of configuration changes config_change_total{topic="notification"} 0 # TYPE not_enforced counter # HELP not_enforced_total number of requests that were not enforced not_enforced_total{topic="enforcement"} 0 ... ``` ## Monitoring types This section describes the data types used in monitoring: * Counter Cumulative metric for a numerical value that only increases. * Gauge Metric for a numerical value that can increase or decrease. The value for a gauge is calculated when requested and represents the state of the metric at that specific time. * Histogram Metric that samples observations, counts them in buckets, and provides a sum of all observed values. ## Metrics at the Prometheus endpoint ### Notification metrics Web Agent exposes the following notification-related monitoring metrics: | Metric | [Type](#monitor-types) | Description | | --------------------- | ---------------------- | ----------------------------------------------------------------------------------------------- | | policy\_change\_total | Counter | Number of policy change notifications received from Advanced Identity Cloud or AM. | | config\_change\_total | Counter | Number of agent configuration change notifications received from Advanced Identity Cloud or AM. | ### Policy decision metrics Web Agent exposes the following policy decision monitoring metrics: | Metric | [Type](#monitor-types) | Description | | ---------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | not\_enforced\_total | Counter | Number of requests that weren't enforced by the agent because of the not-enforced URL lists. | | not\_authorised\_total | Counter | Number of requests denied by policy. | | not\_authenticated\_total | Counter | Number of requests requiring authentication. Compare this metric to the authenticated\_return\_total metric. When authenticated\_return\_total is very low, it can indicate a Denial of Service (DoS) attack, where repeated requests are made with no authentication attempts. | | authenticated\_return\_total | Counter | Number of requests returning after authentication. | | local\_decision\_total | Counter | Number of policy decisions the agent makes locally. | | remote\_decision\_total | Counter | Number of policy decisions the agent requests from Advanced Identity Cloud or AM. | | cache\_decision\_total | Counter | Number of policy decisions the agent takes from the cache when the [AM\_POLICY\_CACHE\_MODE](../user-guide/configure-envvars.html#envvar-AM_POLICY_CACHE_MODE) environment variable is set to `on`. | | url\_cache\_decision\_total | Counter | Number of policy decisions the agent takes from the URL cache when the [AM\_POLICY\_CACHE\_MODE](../user-guide/configure-envvars.html#envvar-AM_POLICY_CACHE_MODE) environment variable is set to `off`. | ### Cache metrics Web Agent exposes the following cache-related monitoring metrics: | Metric | [Type](#monitor-types) | Description | | -------------------- | ---------------------- | --------------------------------------------- | | cache\_write\_total | Counter | Number of session cache writes. | | cache\_update\_total | Counter | Number of session cache updates. | | cache\_read\_total | Counter | Number of session cache reads. | | cache\_miss\_total | Counter | Number of sessions not found in cache. | | cache\_delete\_total | Counter | Number of sessions deleted from cache. | | cache\_expiry\_total | Counter | Number of sessions expired from cache. | | cache\_fault\_total | Counter | Number of sessions that couldn't be cached. | | cache\_occupancy | Gauge | Proportion of session cache that is occupied. | ### Connection metrics Web Agent exposes the following connection-related monitoring metrics: | Metric | [Type](#monitor-types) | Description | | ------------------------ | ---------------------- | ------------------------------------ | | connection\_total | Counter | Number of connections created. | | connection\_reuse\_total | Counter | Number of cached connections reused. | ### Request metrics Web Agent exposes the following request monitoring metrics: | Metric | [Type](#monitor-types) | Description | | ------------------------- | ---------------------- | ------------------------------------------------------- | | policy\_request\_seconds | Histogram | Histogram of policy request times in seconds. | | session\_request\_seconds | Histogram | Histogram of session request times in seconds. | | config\_request\_seconds | Histogram | Histogram of configuration request times in seconds. | | agent\_time\_seconds | Histogram | Histogram of agent time in request pipeline in seconds. | ## Monitor with the monitoring endpoint (deprecated) | | | | - | -------------------------------------------------------------------------------------------------------------------------- | | | The monitoring endpoint described in this section is deprecated. Use it only for diagnostics, in conjunction with Support. | A monitoring endpoint provides access to metrics for operations within the agent and between the agent an AM. The monitoring endpoint is protected by HTTP Basic Authentication. To access it, provide the agent URL, and the agent profile name and password. Always use HTTPS for secure connections to client applications. Metrics are displayed as a JSON response, with the fields described in [Metrics at the monitoring endpoint (deprecated)](#monitor-metrics). ### Access the monitoring endpoint 1. Install a Web Agent as described in the [Installation](../installation-guide/preface.html), and use the agent to protect a web application. For example, set up the example in [Policy enforcement](../user-guide/pep.html). 2. Access the agent monitoring endpoint as follows, where `https://agent.example.com:443` is the agent URL, and `web-agent` is the agent profile name. ```none $ curl https://agent.example.com:443/agent/monitor --user web-agent Enter host password for user 'web-agent': ``` 3. Enter the agent profile password to display the metrics: ```json { "cache-invalidation": { "policy": 0, "profile": 1 }, "policy-decisions": { "neu": 0, "local": 0, "remote": 2, "cache": 0 }, "gc": { "runs": 1, "released": 0, "release-deferred": 0, "fill": 0.000000 }, "cache-operations": { "writes": 0, "rewrites": 2, "reads": 2, "misses": 0, "deletes": 0, "write-faults": 0, "expired": 0, "occupancy": 0 }, "connections": { "added": 2, "reused": 3 } } ``` ### Metrics at the monitoring endpoint (deprecated) | Metric | Submetric | Count of | | -------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `cache-invalidation` | `policy` | Number of policy change notifications received from AM. | | | `profile` | Number of agent configuration change notifications received from AM. | | `policy-decisions` | `neu` | Number of requests that were not enforced by the agent because of the not-enforced URL lists. | | | `local` | Number of policy decisions the agent makes locally. | | | `remote` | Number of policy decisions the agent requests from AM. | | | `cache` | Number of policy decisions the agent takes from the cache. | | `gc` | `runs` | Number of garbage collection runs. | | | `released` | Number of cache entries released during garbage collection runs. | | | `release-defered` | Number of entries with release deferred until the next garbage collection run. | | | `fill` | Floating point value between 0 and 1, representing the proportion of cache that is free after the most the recent garbage collection. | | `cache-operations` | `writes` | Number of writes to cache. | | | `rewrites` | Number of updates to cache. | | | `reads` | Number of reads from cache. | | | `misses` | Number of failed searches of the cache. | | | `deletes` | Number of deletes from cache. | | | `write-faults` | Number of cache writes that fail because the cache is full. | | | `expired` | Number of expired cache entries. | | | `occupancy` | Proportion of cache that is occupied. | | `connections` | `added` | Number of new connections made. | | | `reused` | Number of times existing connections were reused. |