Change Broker best practices

We recommend the following preventative best practices when using Change Broker. Use this page to avoid common scaling, cadence, and bookmark issues before they affect production workloads.

Scale and retention behavior

Change Broker is designed for high-throughput egress and supports serving updates to multiple parallel client applications. Change data is retained for one hour for update retrieval.

A signup is retained relative to its configured inactivity period. By default, the inactivity period is 24 hours. If a signup remains idle beyond that period, it transitions to an expired state and is assigned an ExpiredDate. Expired signups are terminal and cannot be reactivated. They are automatically removed shortly after expiration. However, use cases with a high rate of signup creation and expiration may benefit from proactive manual deletion.

Performance and scaling practices

Use the practices below to tune throughput, response time, and data availability for your application.

Tune query cadence for payload size and latency

Adjust the cadence and signup composition to balance freshness and efficiency. Since write grouping is preserved, query responses return those same grouped data point units. Update retrieval is change event based, and a single Get updates response is capped at 100,000 data points per request.

Treat Get updates as cursor-based paging. When a response returns 80,000 updates or more (80% of the 100,000 cap), immediately issue another request with the returned bookmark. Continue this bounded polling cycle until one of the following occurs:

• A response returns zero updates.

• A response returns fewer than 80,000 updates.

• Your polling cycle limit or latency limit is reached.

This pattern helps your client application stay current when ingress rates are high and avoids relying on per-event aggregation logic.

If your polling interval is too long relative to ingress volume, payload size grows and retrieval latency increases. Tune cadence so egress keeps pace with ingress for each signup.

Note: There is no enforced byte limit on the response, but data points with large values or high stream counts can result in payloads that exceed gateway or HTTP layer limits. If you encounter payload size issues, reduce the number of streams per signup or increase polling frequency to keep individual responses smaller.

If your use case only needs the current state rather than the full recent history, reduce the monitored stream set per signup and increase polling frequency to minimize unnecessary payload.

Validate service setup before scaling

Confirm Change Broker is available for the target account and service instance before onboarding workloads.

• Validate account and service instance targeting before create-signup requests.

• Run a create-signup request, and then poll Get signup by ID until the response shows that the signup is Active.

• Before the first Get updates request, confirm that the Get signup by ID response payload includes bookmarkInfo.bookmark.

• Resolve account and service instance setup mismatches before running long-running ingress workflows.

Set inactivity period intentionally at signup creation

Prevent expiration surprises by treating inactivity period as an explicit design choice.

• The default signup inactivity period is 24 hours.

• Set inactivityPeriod in create-signup requests when your workflow needs a different inactivity threshold.

• Keep the query cadence aligned with the inactivity period that your client application expects.

Maximize streams and data per write operation

Design write operations to carry larger, more efficient payloads when possible. When you use Open Message Format (OMF), you control how much data is written to a stream and how many streams are included in a write operation. For PI to CONNECT Agent, this is automatically optimized and is not configured by you. Change Broker preserves write-operation grouping with minimal processing, so a stream written with 10 timestamp-value pairs in one write operation is returned as one grouped data point in update responses.

Create, modify, and remove signups iteratively when needed

Use iterative signup management when concurrency starts to increase operation duration. In internal testing and many practical scenarios, these operations complete in less than one second when performed concurrently. As stream counts and signup counts grow very large within a service instance, durations can increase. In those scenarios, performing some or all of these operations iteratively can improve practical response times.

Prefer fewer signups with more streams per signup

Favor a smaller number of signups that each contain more streams when practical. Change Broker is designed for large numbers of streams in a smaller number of signups per service instance. Internal tests showed strong performance with a few signups of up to 100,000 streams each, and also with many signups (up to 100) containing fewer streams (up to 25 each). These are benchmark observations rather than guaranteed limits.

There may be egress lag in very large signups or signups with many high-frequency streams. If responses repeatedly return at or above 80,000 updates (80% of the 100,000 maximum), your client application can fall behind ingress and may not keep up with incoming change volume.

When this happens, use one or more of these mitigations:

• In each polling cycle, continue issuing consecutive Get updates requests with the returned bookmark until a response returns fewer than 80,000 updates (including zero).

• Increase base Get updates polling frequency.

• Split the monitored streams into multiple signups, and poll Get updates for each signup.

Query each signup at least once per hour

Keep each signup in an Active state and bookmark-valid through regular queries. A bookmark is valid for one hour after being obtained from a Get signup by ID or Get updates request, with a small server-side buffer to account for clock skew. If a bookmark expires, it can no longer be used to query queued change data. You can continue using the signup while it remains Active, but once the signup reaches its configured inactivity period (24 hours by default) after a period of inactivity, it expires and can no longer be queried or modified.

Think of a bookmark as a cursor for a specific signup. Persist the latest bookmark from every successful response, and use that latest bookmark in the next Get updates request. Do not reuse older bookmark values unless previously fetched data is desired.

Query each signup more frequently than once per hour when write volume is elevated. The hourly guidance is the minimum required to avoid expiration, not a recommended steady-state cadence for high-throughput scenarios.

If you are operating near these tested scale ranges, contact AVEVA customer support for guidance specific to your environment.