Skip to content

MonitoredItem

Canonical path: o6.subscription.MonitoredItem

Root shortcut: o6.MonitoredItem

MonitoredItem

A client subscription item or a server-local monitored item.

Created by Client.monitor(...), or by Server.createDataChangeMonitoredItem(...) and its event counterparts for a server-local item, rather than directly. An item is falsy once deleted, and operations requiring a live item raise RuntimeError; repeated deletion logs a warning.

Local items expose creation state and support deletion. The local backend has no public modification, mode-change, or triggering API, so modify, setMonitoringMode, and setTriggering raise NotImplementedError immediately. Delete and recreate a local item to change its configuration. A local handle constructed directly from an ID has no creation metadata: itemToMonitor, params, requestedParams, and mode raise RuntimeError.

Awaiting the item resolves it, which is what lets await client.monitor(...) return an item whose id the server has already assigned.

See Managing monitored items.

Attributes

DataChangeCallback class-attribute instance-attribute 

DataChangeCallback = (
    Callable[[Any], MaybeAwaitable[None]]
    | Callable[["MonitoredItem", Any], MaybeAwaitable[None]]
)

EventCallback class-attribute instance-attribute 

EventCallback = (
    Callable[[dict[str, Any]], MaybeAwaitable[None]]
    | Callable[
        ["MonitoredItem", dict[str, Any]],
        MaybeAwaitable[None],
    ]
)

CreatedCallback class-attribute instance-attribute 

CreatedCallback = Callable[
    ["MonitoredItem", MonitoredItemCreateResult],
    MaybeAwaitable[None],
]

DeletedCallback class-attribute instance-attribute 

DeletedCallback = Callable[
    ["MonitoredItem", int, int], MaybeAwaitable[None]
]

client property 

client

The client that owns the subscription this item belongs to.

subscription property 

subscription

The subscription this item belongs to.

itemToMonitor property 

itemToMonitor

What is being monitored: node, attribute, index range, and encoding.

Returns an independent snapshot, including nested values.

Raises:

Type Description
RuntimeError

Local creation metadata is unavailable for this handle.

params property 

params

The sampling parameters in force, as revised by the server.

Returns an independent snapshot. For local events, the sampling interval is backend metadata, not an event polling period; clientHandle does not route callbacks. Queue size and discard policy govern local buffering.

Raises:

Type Description
RuntimeError

Local creation metadata is unavailable for this handle.

requestedParams property 

requestedParams

An independent snapshot of the parameters submitted at creation.

These retain the original sampling interval and queue size, before backend revisions. Later modifications do not change this snapshot.

Raises:

Type Description
RuntimeError

Creation has not started, or the handle was constructed directly without creation metadata.

mode property 

mode

The accepted monitoring mode.

Raises:

Type Description
RuntimeError

Local creation metadata is unavailable for this handle.

id property 

id

Server-assigned item id; None before creation and after deletion.

Functions

__init__ 

__init__(
    subscription=None, *, server=None, monitoredItemId=None
)

Create an item handle. Use Client.monitor or the server's createDataChangeMonitoredItem family instead.

Parameters:

Name Type Description Default
subscription Subscription | None

The client subscription this item belongs to.

 None
server Server | None

The server that owns the item, for a server-side item.

 None
monitoredItemId int | None

An existing server-assigned item id to wrap.

 None

__await__ 

__await__()

Wait for the server to create this item, then return it.

delete 

delete()

Delete this monitored item on the server.

Deleting an item that is already gone logs a warning instead of raising, so cleanup paths can run unconditionally.

Raises:

Type Description
RuntimeError

The owning client or server has been garbage-collected.
StatusCodeError

The DeleteMonitoredItems service call failed.

modify 

modify(
    samplingInterval=None,
    queueSize=None,
    discardOldest=None,
    filter=None,
)

Change this item's sampling parameters on the server.

Omitted arguments keep their current value. The server may revise the sampling interval and queue size, and the revised values are stored back, so params reports what was actually granted.

Parameters:

Name Type Description Default
samplingInterval float | None

Requested sampling interval in milliseconds.

 None
queueSize int | None

Requested notification queue depth.

 None
discardOldest bool | None

Drop the oldest queued notification when the queue is full, rather than the newest.

 None
filter DataChangeFilter | EventFilter | str | None

A DataChangeFilter for a data-change item, an EventFilter for an event item, or a filter query string, which is only valid for event items.

 None

Raises:

Type Description
NotImplementedError

Local items cannot be modified through the backend's public API. Delete and recreate the item instead.
TypeError

The filter kind does not match the item kind, or a string filter was passed for a data-change item.
RuntimeError

The item has been deleted.
StatusCodeError

The ModifyMonitoredItems service call failed.

setMonitoringMode 

setMonitoringMode(mode)

Set whether this item samples and reports.

Parameters:

Name Type Description Default
mode MonitoringMode

DISABLED stops sampling, SAMPLING samples without reporting, and REPORTING samples and reports.

 required

Raises:

Type Description
NotImplementedError

The local backend has no public mode-change API.
RuntimeError

The item has been deleted.
StatusCodeError

The SetMonitoringMode service call failed.

setTriggering 

setTriggering(linksToAdd=None, linksToRemove=None)

Link other items so they report whenever this item reports.

A triggering link lets a rarely-changing item pull others along: the linked items report together with this one even while they are only SAMPLING.

Parameters:

Name Type Description Default
linksToAdd list[MonitoredItem] | None

Items to start reporting alongside this one.

 None
linksToRemove list[MonitoredItem] | None

Items to unlink.

 None

Raises:

Type Description
NotImplementedError

Triggering links require a client subscription; the local backend has no public triggering API.
TypeError

A link is not a MonitoredItem.
ValueError

A link belongs to another subscription or is server-local.
RuntimeError

This item or a linked item is uninitialized or deleted.
StatusCodeError

The SetTriggering service call failed, or the server rejected one of the links.