Just a second...

Topic persistence

Consider if you want to enable topic persistence for fast recovery of topic state when Diffusion™ servers restart.

Topic persistence

Topic persistence enables a server to store the state of topics (and the topic tree) to the local file system as a special persistence log file. When the server restarts, topics are automatically restored to the state they were in when the server was stopped.

The persistence log only stores the most recent state of each topic.

Persistence avoids the need for the server to rebuild the topic tree from scratch when it starts. Persistence is useful to speed up development, as well as for backing up and restoring the state of topics at a particular point in time.

Persistence can be enabled or disabled for the whole server. As of Diffusion 6.1, when persistence is enabled for the server, it can still be disabled for individual topics using the PERSISTENT topic property.


Consider the following factors when using topic persistence:
  • Persistence is disabled by default.
  • Each server has an append-only log file of topic events. By default, this is stored in a directory named persistence under the Diffusion server home directory.
  • The log file is written until it reaches 200MiB in size. It is then switched out of service and automatically compacted to save storage space. Compaction removes redundant information (for example, if a topic has been removed, the history of values for that topic is removed during compaction, and only the last value is retained).
  • Enabling persistence consumes a significant amount of storage space. You will need to allow 200MiB for the active log file, plus space for the compacted file. The size of the compacted file depends on the details of your application. The more topics you have, the bigger the file will be.
  • As a rough indication of the size of the compacted file, it contains two records for each topic: a topic record and a value record. The size of each topic record will be approximately the length of the topic name plus 20 bytes. The size of each value record will be approximately the length of the value or delta plus 13 bytes. In practice, you should allow extra space and make sure to monitor the free space available on the server.
  • You can configure the directory where the persistence files are stored. See Configuring topic persistence for details.
  • You should only back up or restore a persistence log while the Diffusion server is not running.
  • Enabling persistence increases memory usage. The compaction service uses about as much memory as it takes to store the topics themselves.
  • If servers close unexpectedly (for example, due to a crash), the persistence feature may not log the most recent topic updates, resulting in some data loss when the server restarts.
  • Current information is always prioritised. During recovery from the file system, if a newer state of a topic is available (for example, from an application update or by replication from another server), that state will be used instead.
  • If you do not want topics to be restored when you next start the server, simply delete all the log files.

Persistence and topic replication

In a cluster with topic replication enabled, topic values from other servers in the cluster take precedence over values recovered from persistence.

If only one server in the cluster receives a topic update, the updated value will not be recovered from the persistence file if another server in the cluster has a value for that topic.

When you restart a cluster, it is best to start with the server that was shut down last.

Alternatively, you can do a rolling restart and make sure that the cluster recovers between each server start.