State Manager

Opsview State Manager is a fast, distributed, persistent key-value store used to retain session and other persistent data. It complements the Cache Manager, which handles short-term ephemeral data.

Since the State Manager stores data in persistent storage, restarting the Manager does not result in data loss, and components using it do not need to re-populate previously stored data. Additionally, the data is shared across all nodes within the same Collector Cluster, allowing a check run on one node to access data stored by another.

Each item of data stored in the State Manager can have an associated time-to-live (TTL), defined when the data is saved. The State Manager provides an API for client components, accessible via both HTTP and HTTPS endpoints.

The State Manager is a sub-component of the Opsview Cache Manager, which handles short-term ephemeral data.

Package dependencies Copied

Service Dependencies Copied

Installation Copied

The State Manager is deployed on Collectors by Opsview Deploy. The specific playbook is cache-manager-install.yaml.

Configuration Copied

Configuration options for the State Manager must be set in /opt/opsview/cachemanager/etc/cachemanager.yaml. Opsview Deploy automatically configures Cache Manager peers within the cluster.

Warning

While certain settings can be modified manually, it is strongly recommended to manage them via Opsview Deploy to ensure cluster-wide synchronization. Failure to do so may result in the State Manager not functioning correctly.

These settings are specific to the State Manager, but many settings in the Cache Manager settings, are also applicable to the State Manager.

Setting Description
max_persistent_data_item_size Defines the maximum size of an individual data item that can be stored in the State Manager. The default value is 16 KB.
max_persistent_data_items Specifies the maximum number of data items that can exist in the store at any one time. The default is 1024 items.

Management Copied

See Cache Manager Managemant

Logging Copied

The Opsview State Manager logs events to syslog, consistent with other Opsview components.

Example of logging:

Oct 16 08:33:28 dk-pc-m opsview.cachemanager.datastore <10822> : [NOTICE] State Manager initialised
Oct 16 08:33:28 dk-pc-m opsview.cachemanager.cachemanagerworker <10822> : [NOTICE] Worker started (PID=10822).

Using the State Manager Copied

How the State Manager works Copied

By default, Opsview Deploy installs one Cache Manager per Collector, each of which includes an instance of the State Manager. Each Cache Manager is connected to the Executor and Scheduler via the Load Balancer.

When plugins are executed, they interact with their local State Manager, which can then store and retrieve data from the cluster’s shared datastore. This ensures that data is consistent and accessible across all nodes in the Collector Cluster.

Using the State Manager

API methods Copied

The State Manager provides two primary API methods: store_data and fetch_data.

Method Description
store_data Save a piece of data in the State Manager using a key, namespace and TTL, with an optional timestamp.
fetch_data Retrieve data from the State Manager using a key and namespace

The State Manager assigns data to a unique combination of key and namespace.

The namespace ensures naming collisions are avoided and potentially sensitive data cannot be read by other unauthorized plugins.

The key is the identifier for the data in the namespace specified.

Data will be valid for the time specified by the TTL, after which it will be removed from the persistent storage.

The optional timestamp can be useful when there is a degree of latency between the source of the data and the call to store the data.

Building plugins that use State Manager Copied

State Manager is fully integrated with plugnpy. You can import plugnpy into your Python monitoring script and make full use of all the State Manager’s features.

plugnpy comes with an HTTP client which is able to connect to the opsview-cachemanager component. This allows the plugins to use the State Manager to store data into memory which can be consumed by later service checks which require the same data.

The module consists of a class, StateManagerUtils, which provides easy to use interfaces to communicate with the State Manager (which is a subset of opsview-cachemanager). The class handles the details of the connection to the State Manager, and automatically uses the correct namespace from the executor.

StateManagerUtils Copied

A simple client to store to or fetch data from the State Manager.

from plugnpy.statemanager import StateManagerUtils

client = StateManagerUtils()

Once a State Manager client has been created, the store_data and fetch_data methods can be used to save and retrieve data respectively.

client.store_data(key, data, ttl=3600)

The fetch_data method can be called with the key parameter to retrieve data stored under the specified key.

data = client.fetch_data(key)

Debugging Copied

To see what is going on inside the State Manager as you are making calls, you must start the Cache Manger in debug mode.

Set the Cache Manager logging to DEBUG:

Edit /opt/opsview/cachemanager/etc/cachemanager.yaml

cachemanager:
...
  logging:
    loggers:
      opsview:
        level: DEBUG

Then restart the Cache Manager:

sudo /opt/opsview/watchdog/bin/opsview-monit restart opsview-cachemanager

Alternatively run the Cache Manager directly in DEBUG mode:

# Stop the Cache Manager
sudo /opt/opsview/watchdog/bin/opsview-monit stop opsview-cachemanager

# Start the Cache Manager in debug mode using -d flag
sudo -iu opsview /opt/opsview/cachemanager/venv3/bin/cachemanagerlauncher -d

2025-10-16 10:25:16,370 NOTICE [opsview <25035>] Launching Opsview Cache-Manager daemon (debug mode).
2025-10-16 10:25:16,371 INFO [opsview.common.process.workerpool <25035>] Process launcher greenlet 0 launched.
2025-10-16 10:25:16,458 INFO [opsview.cachemanager.helpers.lockingcache <25076>] Creating local cache (max_total_bytes=1073741824, max_item_bytes=0).
2025-10-16 10:25:16,458 NOTICE [opsview.cachemanager.datastore <25076>] State Manager initialised

When finished, restart the Cache Manager

sudo /opt/opsview/watchdog/bin/opsview-monit start opsview-cachemanager

Caveats Copied

The State Manager will make a best effort to ensure concurrent store requests for the same namespace and key are processed in the correct order. The timestamp parameter helps to police this.

In some cases when two store data requests are made at the same time a document conflict error will be returned for one of the store requests, while the other succeeds. In this case the failed request can be retried. There is a small possibility that if two requests are made at the same time on different collectors within the same cluster then they might both succeed and the order cannot be guaranteed.

It is the caller’s responsibility to encrypt any sensitive data.

["Opsview On-Premises"] ["User Guide"]

Was this topic helpful?