AVEVA CONNECT

Observability

Synopsis

Creates an AVEVA CONNECT target that writes metrics to streams in AVEVA CONNECT data services, formerly AVEVA Data Hub. It sends them as OMF (OSIsoft Message Format) messages, and each series goes to the stream whose ID a template gives.

note

The target follows AVEVA's OMF documentation.

Schema

- name: <string>
  description: <string>
  type: avevaconnect
  pipelines: <pipeline[]>
  status: <boolean>
  properties:
    url: <string>
    tenant_id: <string>
    namespace_id: <string>
    client_id: <string>
    client_secret: <string>
    token_url: <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:

Field	Required	Default	Description
`name`	Y		Target name
`description`	N	-	Optional description
`type`	Y		Must be `avevaconnect`
`pipelines`	N	-	Optional post-processor pipelines
`status`	N	`true`	Enable/disable the target

Connection

Field	Required	Default	Description
`url`	Y	-	The https address of AVEVA CONNECT data services in your region, such as `https://uswe.datahub.connect.aveva.com`. It must have a host. It takes no user, query or fragment, but it can have a path. In the console: URL
`tenant_id`	Y	-	The ID of the tenant that the data goes to. In the console: Tenant ID
`namespace_id`	Y	-	The ID of the namespace in that tenant. The target sends its messages to `<url>/api/v1/tenants/<tenant_id>/namespaces/<namespace_id>/omf`. In the console: Namespace ID

Authentication

Field	Required	Default	Description
`client_id`	Y	-	The ID of a client-credentials client of the tenant. In the console: Client ID
`client_secret`	Y	-	The secret of that client. In the console: Client secret
`token_url`	N	`<url>/identity/connect/token`	The address of the token service. It must be an https URL. In the console: Token URL

client_id and client_secret can each be plain text, an environment variable or a secret.

Data

Field	Required	Default	Description
`container_id`	N	`{device}.{metric}`	The template of the stream ID. See The Stream ID. In the console: Stream ID template
`omf_version`	N	`1.2`	The OMF version of the messages: `1.0`, `1.1` or `1.2`. In the console: OMF version
`compression`	N	`true`	The target compresses each message with gzip. Set it to `false` to send messages uncompressed. In the console: Compression

Performance

Field	Required	Default	Description
`timeout`	N	`30`	As on the OTLP page
`batch_size`	N	`1000`	As on the OTLP page
`max_retries`	N	`3`	As on the OTLP page
`retry_delay`	N	`1`	As on the OTLP page
`disable_retries`	N	`false`	As 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 CONNECT settings, has four sections:

Connection settings: URL, then Tenant ID and Namespace ID side by side.
Authentication: Client ID and Client secret side by side, then Token URL (Optional).
Data settings: Stream ID template (Optional, its placeholder shows {device}.{metric}), OMF version (a dropdown, 1.2) and Compression (a switch, on).
Performance.

The form has no TLS step, because AVEVA CONNECT uses public certificates.

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 stream 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 AVEVA CONNECT

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, which AVEVA CONNECT keeps as a stream in the namespace.
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 AVEVA CONNECT answers 404.

The target signs in with OAuth 2.0 client credentials:

It asks the token service for a token with client_id and client_secret, and sends the token with each message.
It keeps the token until a minute before it expires, and then asks for a new one. All the workers of the target share one token.
When AVEVA CONNECT answers 401 to a message, the target drops the token, and Director delivers the batch again later with a new token.
When the token service refuses the client (400 or 401), Director delivers the batch again later. The warning gives the status, and the OAuth error code when the answer has one. It never shows the client secret.

The Stream ID

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 IDs such as router1.cpu.load. The template {attr.site}.{device}.{metric} gives plant1.router1.cpu.load.
An ID 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 Stream

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 ID, the target sends the first one and drops the values of the other, with a warning, because they would mix in one stream. Add {attr.service.instance.id} to the template to give each instance its own stream.
The target keeps up to 100,000 IDs. A series that sends nothing for an hour gives up its ID. When 100,000 series hold an ID and none of them is stale, the target sends the values of a new ID without this check, so that no value is lost. Two series can then mix their values in that stream.
Each Director keeps its own list, so two Directors can write to one stream without a warning.

What Is Dropped Before Sending

The target drops a value that AVEVA CONNECT 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 the stream would keep a second value;
a reading that lacks an attribute that the template names;
a value whose stream ID 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 streams into messages of at most 160 KiB. OMF takes messages of up to 192 KB.
AVEVA CONNECT answers 202 when it has accepted a message, and checks the message afterwards. The target counts a 202 as delivered. It does not read the result of that later check, so it does not notice a message that AVEVA CONNECT accepts and later refuses.
A 400, or another 4xx answer that is not named here, means that AVEVA CONNECT 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 the namespace has, such as a stream that exists with another type. The target drops the message and logs a warning.
A 404 means that AVEVA CONNECT does not know the type or a stream. The target sends the type and the streams again, and then the values, once. When AVEVA CONNECT 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.

Workers

The target keeps no running totals, so it can run several workers in parallel. The workers share one list of IDs, one record of what the namespace has and one token. Only one of them at a time sends the type and the streams.

Examples

The Default Token Service

The default token service and stream IDs, with the client secret from a secret store...

targets:
  - name: aveva_connect
    type: avevaconnect
    properties:
      url: "https://uswe.datahub.connect.aveva.com"
      tenant_id: "00000000-0000-0000-0000-000000000000"
      namespace_id: "plant-metrics"
      client_id: "${CONNECT_CLIENT_ID}"
      client_secret: "$secret{store=corp-vault,ref=aveva/connect-client-secret}"

A Stream per Site and Instance

A stream for each site and instance...

targets:
  - name: aveva_connect_plant
    type: avevaconnect
    properties:
      url: "https://uswe.datahub.connect.aveva.com"
      tenant_id: "00000000-0000-0000-0000-000000000000"
      namespace_id: "plant-metrics"
      client_id: "${CONNECT_CLIENT_ID}"
      client_secret: "$secret{store=corp-vault,ref=aveva/connect-client-secret}"
      container_id: "{attr.site}.{device}.{attr.service.instance.id}.{metric}"

Troubleshooting

Configuration Errors

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

url is required for AVEVA CONNECT, for example https://uswe.datahub.connect.aveva.com
url for AVEVA CONNECT must be an https URL with a host and no user, query or fragment, such as https://uswe.datahub.connect.aveva.com
tenant_id is required for AVEVA CONNECT, and the same message for namespace_id and client_id
client_secret is required for AVEVA CONNECT
token_url for AVEVA CONNECT must be an https URL with a host and no user, query or fragment, such as https://uswe.datahub.connect.aveva.com/identity/connect/token
omf_version for AVEVA CONNECT 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 client_secret of the AVEVA CONNECT 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 client ID.
failed to resolve the client_secret of the AVEVA CONNECT 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 CONNECT takes only metrics: the route sends log records or spans to this target.
[OTLP] dropped N values in the last minute: AVEVA CONNECT <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, <ID>: two series give the same stream ID. Add an attribute to the template that tells them apart.
- refused the values: status <status>, <message>: AVEVA CONNECT refused the values for good. A 409 can mean that a stream with that ID exists with another type.
- refused the type: ... or refused the containers: ...: AVEVA CONNECT refused the type or the streams, so their values are dropped.
- refused the values as too large, even in messages of 8 KiB

Errors While It Runs

the identity service refused the sign-in with status 401, so check client_id and client_secret, or status 400, sometimes with an OAuth error code such as invalid_client: the client ID or the client secret is wrong. The batches are delivered again once this is fixed.
the identity service at <url> answered status N: the token service failed in another way. Check token_url, or leave it empty to use the default.
the identity service at <url> answered something other than a token: token_url points at something that is not a token service.
AVEVA CONNECT refused the data message with status 403, or type or container in place of data: the client lacks the rights to write to the namespace.
AVEVA CONNECT does not know the type or a container, even after they were created again: AVEVA CONNECT answered 404 twice. Check the tenant ID and the namespace ID. The batch is delivered again later.
failed to send after N of M attempts: ...: AVEVA CONNECT kept answering 408, 429 or 5xx, or the connection kept failing, until the retries ran out. The batch is delivered again later.

Synopsis​

Schema​

Configuration​

Connection​

Authentication​

Data​

Performance​

Other Settings​

Scheduling​

Debug Options​

The Console Form​

Details​

What the Target Sends​

How the Data Reaches AVEVA CONNECT​

Sign-in​

The Stream ID​

One Series to One Stream​

What Is Dropped Before Sending​

Requests and Answers​

Workers​

Examples​

The Default Token Service​

A Stream per Site and Instance​

Troubleshooting​

Configuration Errors​

Warnings While It Runs​

Errors While It Runs​