Monitoring Module

Monitoring Plugin

The Controller provides quantum network monitoring capabilities through a monitoring plugin interface, which defines handlers for monitoring messages. A monitoring plugin must implement the abstract method handle_resource_update() to manage monitoring events received from a msgserver that listens to a chosen topic.

The built-in monitoring plugin handles monitoring events received by the controller. It subscribes to the monitor topic for MonitorEvent messages. Upon receiving a message, the plugin:

  1. Validates the message format against the monitoring message schema.

  2. Dispatches on eventType:

    • agentHeartbeat — updates the node’s last-seen timestamp in the database (not persisted to the Monitor DB).

    • agentState, agentTaskResult, experimentResult, and all other event types — persisted to the Monitor database.

Protocol

The Message Bus defines a built-in monitoring message format in JSON, which includes the following fields:

  • rid: str — Resource ID (e.g. agent identifier)

  • ts: float — UTC Unix timestamp

  • eventType: str — Type of event (see EventType below)

  • value: str | int | float | object — Value of the monitored resource

Event Types

All valid event types are defined in the EventType enum exported by qn-mq (see Message Bus):

Event Type

Description

agentState

Agent state transition (e.g. Not Ready / Ready). Persisted to the Monitor DB.

experimentResult

Result of a completed experiment run. Persisted to the Monitor DB.

agentHeartbeat

Periodic liveness ping from an agent. Updates the node’s last-seen timestamp; not stored in the Monitor DB.

agentTaskSchedulerPhase

Phase update from the agent task scheduler. Persisted to the Monitor DB.

agentTaskSchedulerTask

Individual task status from the agent task scheduler. Persisted to the Monitor DB.

agentTaskResult

Result of a completed agent local task, including the experiment ID and result payload. Persisted to the Monitor DB and queryable via getTasks.

Agent Heartbeat Tracking

The monitor plugin uses incoming agentHeartbeat events to maintain a last-seen timestamp for each node in the database. This timestamp is used by the controller to exclude stale agents when matching nodes to an experiment path (see Scheduling).

A node is considered stale if no heartbeat has been received within 60 seconds.

getTasks RPC

The monitor plugin exposes a getTasks RPC command that allows clients to query recorded agent task results from the Monitor database. The request accepts an optional agent filter to narrow results to a specific node.

Each entry in the response includes the task and experiment identifiers, the result payload, status, timestamps, and the name of the originating task.