Performance Metrics (Core Services)

Performance Metrics allows system administrators to view PI Web API usage, system load, and aggregate request performance. These metrics are passively collected by the service and are exposed to PI Web API Administrators through the Metrics controller. Retrieving metrics provides a snapshot of service metrics at the time of the request.

Configuration Settings

Performance Metrics are enabled by default. To disable access to the performance metrics endpoint, set the 'PerformanceMetricsEnabled' configuration option to false. This will reset the service's collected metrics. For more information on how to change configuration settings, refer to the Configuration controller or to Configuration at runtime on AVEVA Documentation.

Metrics Collected

Request Metrics

PI Web API Core metrics are organized by HTTP method and route pattern. The PI Web API uses the route pattern to match incoming request URIs to the associated controller and action. URL parameters are ignored during this mapping step, and so they do not appear in Performance Metrics. For example, the request URI /help/controllers/metrics would appear as /help/controllers/{name}. Request times are measured in milliseconds. The request time is defined as the time elapsed between when the request is received and when the first byte of the response is returned. This means that the request times measured by the PI Web API do not include external factors, such as the time needed to transmit the response across the network. Core metrics include:

• Time-bucketed counts - This set of metrics is designed to act like a histogram. Requests are grouped into buckets based on how long the request took to process. The returned values indicate how many requests were present in each bucket. The label of each bucket is the inclusive lower bound of the range and the next label is its exclusive upper bound. For example, the metrics snippet below indicates that 5 requests completed in 10 or more milliseconds but less than 50 milliseconds, while 3 requests required 120000 or more milliseconds to complete.

  "Counts": {
    "0": 0,
    "10": 5,
    "50": 0,
    "100": 0,
    "250": 0,
    "500": 0,
    "750": 0,
    "1000": 0,
    "5000": 0,
    "30000": 0,
    "60000": 0,
    "120000": 3
  }

• Request counts by user

• Request counts by status code
• Total request count
• Last observed time - The last time a request was observed against this route.
• Exponentially weighted moving average request time - This is included as a convenience for users who would like to determine the approximate response time of a given route at a glance. Because it is exponentially weighted, recent requests are more heavily weighted in the average calculation.

Except for the last observed time and average request time, all metrics are expressed as running counts. Thus, to understand the service's performance over a time interval, one may compare a before and after snapshot. Note that Performance Metrics are collected and exposed per PI Web API instance. This means that installations with multiple PI Web API instances behind a load balancer require server affinity to calculate accurate deltas.

Plugin Metrics

The PI Web API consists of several independent groups of functionality, such as Core Services, and OMF Services. These groups are internally referred to as "plugins". Each plugin may collect its own metrics. Plugins may expose zero or more metric counts, as well as zero or more sub-groups of metrics. These sub-groups recursively reuse the same metric count and sub-group structure.

For information regarding the metrics collected by specific plugins, see the below topics. These topics are only available if the corresponding plugin is installed.

• OMF Services Performance Metrics

Environment Metrics

Environment metrics describe the PI Web API host machine.

• Processor - Unlike other metrics, the 'Processor' metric is not a request-time snapshot. This metric is periodically sampled and reported as the percentage of CPU in use by PI Web API.
• Memory - The current snapshot of private bytes, virtual bytes, and working set bytes in use by PI Web API.