---
title: "State Manager"
description: ""
url: "https://docs.itrsgroup.com/docs/opsview/6.11.7/administration/distributing-functionality/state-manager/index.html"
---
Opsview State Manager is a fast, distributed, persistent key-value store used to retain session and other persistent data. It complements the [Cache Manager](https://docs.itrsgroup.com/docs/opsview/6.11.7/administration/distributing-functionality/cache-manager/index.html), 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](https://docs.itrsgroup.com/docs/opsview/6.11.7/administration/distributing-functionality/cache-manager/index.html), which handles short-term ephemeral data.

## Package dependencies

- `opsview-python3`

## Service Dependencies

- `opsview-registry`

## Installation

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

## Configuration

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](https://docs.itrsgroup.com/docs/opsview/6.11.7/administration/distributing-functionality/cache-manager/index.html#configuration), 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

See [Cache Manager Managemant](https://docs.itrsgroup.com/docs/opsview/6.11.7/administration/distributing-functionality/cache-manager/index.html#management)

## Logging

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

### How the State Manager works

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](/opsview//images/admin-distri-functionality-state-manager.png)

### API methods

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

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

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.

 - The `store_data` method can be called with the key and data parameters, this will store the specified data, under the given key.
 - The `ttl` parameter is used to specify the number of seconds for which the data is valid.
 - The optional `timestamp` can be used to mark the time the data was obtained.
   This can be useful when there is a degree of latency between the source of the data and the call to the `store_data` method.
   If `timestamp` is in the future, then the current time will be used instead.

```
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

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

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.

