Skip to main content

AVEVA PI System

Observability

Synopsis​

Creates an AVEVA PI System target that writes metrics to PI points through PI Web API. It sends them as OMF (OSIsoft Message Format) messages, and each series goes to the PI point that a template names.

note

The target follows AVEVA's OMF documentation.

Schema​

- name: <string>
  description: <string>
  type: avevapi
  pipelines: <pipeline[]>
  status: <boolean>
  properties:
    url: <string>
    username: <string>
    password: <string>
    container_id: <string>
    omf_version: <string>
    compression: <boolean>
    timeout: <numeric>
    batch_size: <numeric>
    max_retries: <numeric>
    retry_delay: <numeric>
    disable_retries: <boolean>
    debug:
      status: <boolean>
      dont_send_logs: <boolean>

Configuration​

The following fields are used to define the target:

FieldRequiredDefaultDescription
nameYTarget name
descriptionN-Optional description
typeYMust be avevapi
pipelinesN-Optional post-processor pipelines
statusNtrueEnable/disable the target

Connection​

FieldRequiredDefaultDescription
urlY-The https address of PI Web API, such as https://pi.example.com/piwebapi. The target sends its messages to <url>/omf, or to the URL as it is when it already ends in /omf. It must have a host. It takes no user, query or fragment, but it can have a path. In the console: URL

Authentication​

FieldRequiredDefaultDescription
usernameY-The PI Web API user that the target signs in as, with Basic authentication. In the console: Username
passwordY-The password of that user. In the console: Password

username and password can each be plain text, an environment variable or a secret.

Data​

FieldRequiredDefaultDescription
container_idN{device}.{metric}The template of the PI point name. See The PI Point Name. In the console: PI point name template
omf_versionN1.2The OMF version of the messages: 1.0, 1.1 or 1.2. An older PI Web API may need 1.0 or 1.1. In the console: OMF version
compressionNfalseWhen it is on, the target compresses each message with gzip. In the console: Compression

Performance​

FieldRequiredDefaultDescription
timeoutN30As on the OTLP page
batch_sizeN1000As on the OTLP page
max_retriesN3As on the OTLP page
retry_delayN1As on the OTLP page
disable_retriesNfalseAs on the OTLP page

Other Settings​

  • headers works as on the OTLP page. It cannot change the headers that OMF and the sign-in need.
  • The tls settings work as on the OTLP page.
  • cumulative_to_delta has no effect on this target.

Scheduling​

See Scheduling and Pool Behavior for interval and cron fields shared by all targets.

Debug Options​

The debug options work as on the OTLP page.

The Console Form​

The settings step, AVEVA PI System settings, has four sections:

  • Connection settings: URL.
  • Authentication: Username and Password, side by side.
  • Data settings: PI point name template (Optional, its placeholder shows {device}.{metric}), OMF version (a dropdown, 1.2) and Compression (a switch, off).
  • Performance.

The TLS step of the OTLP form follows, because a PI Web API server in a company network often has a certificate from the company's own certificate authority.

Details​

What the Target Sends​

Only metrics:

  • the readings of metric devices;
  • the metrics that the OpenTelemetry device receives.

The number points of gauges and sums are sent. Histograms and summaries are not, because each PI point holds single numbers.

A record that is not a metric, such as a log line, is counted as dropped, with a warning at most once a minute. So route only metrics to this target.

How the Data Reaches PI​

OMF describes data with a type, containers and values:

  • The target uses one type for every series: a timestamp and a 64-bit floating point value. So every value is written as a double.
  • Each series has a container of its own. PI Web API keeps each container as a PI point, in its default Data Archive.
  • The target sends the type once, then each container once, and then the values. It sends the type and the containers again after Director restarts the target, and when PI Web API answers 404.

The PI Point Name​

container_id is a template:

  • {device} is the name of the device, {metric} the name of the metric, and {attr.<key>} the value of an attribute of the reading, or else of its resource, such as service.instance.id or host.name.
  • The default {device}.{metric} gives names such as router1.cpu.load. The template {attr.site}.{device}.{metric} gives plant1.router1.cpu.load.
  • A name holds only letters, digits, ., _ and -. The target replaces any other character with _, so Boiler Room 1.temp (C) becomes Boiler_Room_1.temp__C_.
  • A template with an unknown placeholder, an empty {attr.} or a brace without its partner stops the target from starting. The error names the character where the problem is.

One Series to One PI Point​

A series is one metric of one instance of a device or service, from one instrumentation scope, with one set of point attributes.

  • Instances are told apart by service.name, service.namespace, service.instance.id and host.name.
  • When two series give the same name, the target sends the first one and drops the values of the other, with a warning, because they would mix in one PI point. Add {attr.service.instance.id} to the template to give each instance its own PI point.
  • The target keeps up to 100,000 names. A series that sends nothing for an hour gives up its name. When 100,000 series hold a name and none of them is stale, the target sends the values of a new name without this check, so that no value is lost. Two series can then mix their values in that PI point.
  • Each Director keeps its own list, so two Directors can write to one PI point without a warning.

What Is Dropped Before Sending​

The target drops a value that PI would not take:

  • a value that is NaN or an infinity;
  • a point without a timestamp, because its time would differ each time the batch is delivered, and PI would keep a second value;
  • a reading that lacks an attribute that the template names;
  • a value whose PI point name is empty or longer than 255 bytes;
  • a histogram or a summary.

A warning with the number of values and the reason is logged at most once a minute. These values are counted in the warning, not as dropped records, because one record can hold many values.

Requests and Answers​

  • The target puts the values of many PI points into messages of at most 160 KiB. OMF takes messages of up to 192 KB.
  • A 2xx answer means that PI Web API took the message. PI Web API can answer 200 and still say in its answer that the message failed. The target then drops the message and logs a warning with PI's first message.
  • A 400, or another 4xx answer that is not named here, means that PI Web API will never take the message. The target drops its values and logs a warning with the reason.
  • A 409 means that the message clashes with what PI has, such as a PI point that exists with another type. The target drops the message and logs a warning.
  • A 404 means that PI Web API does not know the type or a PI point. The target sends the type and the PI points again, and then the values, once. When PI Web API answers 404 again, Director delivers the batch again later.
  • A 413 means that the message is too large. The target sends its values again in messages of half the size, down to 8 KiB. When a message of 8 KiB is still too large, it drops the values and logs a warning.
  • A 401 or a 403, and a redirect that the target does not follow, make Director deliver the batch again later, because waiting does not fix a sign-in or an address. The target follows only a 307 or a 308 redirect, which sends the same request to the new address.
  • A 408, a 429 or a 5xx answer, and a failed connection, are retried. When the answer has a Retry-After header, the target waits that long, for at most one minute. Otherwise it waits for retry_delay. When the retries run out, Director delivers the batch again later.
  • A batch that fails part way is delivered again as a whole, so a value that was already sent can arrive twice.

Sign-in​

The target signs in with Basic authentication only, with username and password. The user needs the rights to write OMF data through PI Web API.

Workers​

The target keeps no running totals, so it can run several workers in parallel. The workers share one list of names and one record of what PI has, and only one of them at a time sends the type and the PI points.

Examples​

Basic Sign-in​

Basic sign-in, with the default PI point names...

targets:
  - name: aveva_pi
    type: avevapi
    properties:
      url: "https://pi.example.com/piwebapi"
      username: "${PI_USERNAME}"
      password: "$secret{aveva-pi-password}"

A PI Point per Site and Instance​

A PI point for each site and instance, and OMF 1.1 for an older PI Web API...

targets:
  - name: aveva_pi_plant
    type: avevapi
    properties:
      url: "https://pi.example.com/piwebapi"
      username: "pi-writer"
      password: "$secret{aveva-pi-password}"
      container_id: "{attr.site}.{device}.{attr.service.instance.id}.{metric}"
      omf_version: "1.1"

Troubleshooting​

Configuration Errors​

Director refuses a configuration it cannot use, with one of these messages:

  • url is required for AVEVA PI System, for example https://pi.example.com/piwebapi
  • url for AVEVA PI System must be an https URL with a host and no user, query or fragment, such as https://pi.example.com/piwebapi
  • username is required for AVEVA PI System, and the same message for password
  • omf_version for AVEVA PI System must be 1.0, 1.1 or 1.2
  • container_id template has an unknown placeholder {name} at character 10: use {device}, {metric} or {attr.<key>}
  • container_id template has an empty attribute name in {attr.} at character N: write the name after attr., as in {attr.site}
  • container_id template has a { at character N with no closing }: close every placeholder with }, and the messages for a } with no opening { and for a { inside a placeholder
  • the password of the AVEVA PI System target resolved to nothing: check the environment variable or the secret it names: the setting is set, but its environment variable or secret is empty. The same message names the username.
  • failed to resolve the password of the AVEVA PI System target: ...: the environment variable or the secret could not be read.

Warnings While It Runs​

These appear in the Director log, at most once a minute:

  • [OTLP] dropped N records that are not metrics in the last minute: AVEVA PI System takes only metrics: the route sends log records or spans to this target.
  • [OTLP] dropped N values in the last minute: AVEVA PI System <reason>, where the reason is one of:
    • takes no NaN or infinite value
    • takes no value without a timestamp
    • has no value for an attribute the container_id names
    • cannot take the container id, which is empty or longer than 255 bytes
    • stores no histograms or summaries
    • already writes this container id for another series, <name>: two series give the same PI point name. Add an attribute to the template that tells them apart.
    • refused the values: status <status>, <message>: PI Web API refused the values for good. A 409 can mean that a PI point with that name exists with another type.
    • refused the type: ... or refused the containers: ...: PI Web API refused the type or the PI points, so their values are dropped.
    • refused the values as too large, even in messages of 8 KiB

Errors While It Runs​

  • AVEVA PI System refused the data message with status 401, or type or container in place of data, or 403: the user name or the password is wrong, or the user lacks the rights. The batches are delivered again once this is fixed.
  • AVEVA PI System does not know the type or a container, even after they were created again: PI Web API answered 404 twice. Check that url points at PI Web API. The batch is delivered again later.
  • failed to send after N of M attempts: ...: PI Web API kept answering 408, 429 or 5xx, or the connection kept failing, until the retries ran out. The batch is delivered again later.