Performance metrics

Performance metrics are designed to give insight into what PI Web API is doing. For example, they show PI Web API usage, system load, and also aggregate request performance. Performance metrics are passively collected by the PI Web API service and provide a snapshot of a point in time. If you are a PI Web API administrator, you can view them through the metrics controller.

Configuration settings

Performance metrics are enabled by default. If you want to disable metrics, set the PerformanceMetricsEnabled configuration option to false. This resets the service's collected metrics. If you decide to re-enable performance metrics later, counts will start from zero. Counts are the number of processed requests. For more information on how to change the configuration settings, see Configuration at runtime.

Note: Performance metrics are calculated per PI Web API instance. The client application interacting with PI Web API is random. If you want to see performance metrics for a particular instance, you must enable server affinity or sticky sessions to pick a specific instance URL instead of the load balancer.

Metrics types

The following three performance metrics types are available:

• Request metrics

  PI Web API metrics are organized by HTTP method and route pattern, which are used to match incoming request URIs with the associated controller and action. URL parameters are ignored during this mapping step, hence, they do not appear in performance metrics. For example, the request URI /help/controllers/metrics appears as /help/controllers/{name}.

  Request time is measured in milliseconds. It is 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 PI Web API do not include external factors, such as the time needed to transmit the response across the network. The following metrics are core metrics:

  • Time-bucketed counts

    Time-bucketed counts 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 in each bucket. The label of each bucket is the inclusive lower bound of the range and the next label is the exclusive upper bound of the range.

    Example: The following metrics snippet indicates that five requests completed in > = 10 but < 50 milliseconds. Three requests needed >= 120,000 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

    The request counts by user indicates how many requests were processed by a certain user.

  • Request counts by status code

    The request counts by status code indicates how many requests with a certain status code were processed.

  • Total request count

    The total request count indicates how many requests were processed altogether.

  • Last observed time

    The last observed time is the last time a request was observed against this route.

  • Exponentially weighted average request time

    The exponentially weighted average request time determines the approximate response time of a given route. Recent requests are more heavily weighted in the average calculation because of the exponential weighting.

All metrics are expressed at running counts, except for last observed time and average request time. To understand the service's performance over a time interval, you can compare a before and after snapshot.

• Plugin metrics

  PI Web API's independent functionality groups, also known as plugins, all collect their own metrics. Plugin examples are OMF Services and Core Services. Those plugins may expose zero or more metric counts and zero or more subgroups of metrics. The subgroups recursively reuse the same metric count and subgroup structure.

  Specific performance metrics are currently supported for the OMF Services plugin only and they include the following:

  • Operation metrics

    Operation metrics return OMF version-specific metrics. The set of metrics are grouped by their associated OMF version and may differ based on the OMF version.

    OMF v1.0

    PI Web API aliases OMF v1.0 messages to OMF v1.1. Messages that use OMF v1.0 are displayed under the OMF v1.1 metric group.

    OMF v1.1

    Returns counts of Type messages, Container messages, Static data messages, Dynamic data messages, and Link data messages.

    OMF v1.2

    Returns counts of Type messages, Container messages, Static data messages, Dynamic data messages, and Link data messages.

    PI Data Archive throughput

    Returns counts of the following for each Data Archive server:

    • Points created

    • Points updated

    • Points deleted

    • Values inserted

    • Values updated

    • Values removed

    • Digital sets created

    • Digital sets deleted

      Asset framework throughput

      Returns counts of the following for each Asset Framework database:

    • Element templates created

    • Element templates deleted

    • Elements created

    • Elements updated

    • Elements deleted

    • Elements moved

    • Enumeration sets created

    • Enumeration sets deleted

    • Point reference attributes created

    • Point reference attributes deleted

  • Environment metrics

    Environment metrics describe the PI Web API host machine. The following environment metrics are available:

    • Processor

      The Processor metric is periodically sampled and reported as the percentage of CPU in use PI Web API, hence, it is not a request-time snapshot.

    • Memory

      The Memory metric is the current snapshot of private bytes, virtual bytes, and working set bytes in use by PI Web API.