Skip to main content

Persistent Point Value Cache

Mango 4.0 and later includes significant improvements to the startup performance of data sources and their associated data points. One of the most impactful features is the Persistent Point Value Cache, which stores the latest cached values for data points on disk in a fast key-value store, separate from the main time-series database.

Why It Matters​

When Mango starts, each data point needs to know its most recent value so that event detectors, meta data points, and the UI can display current state immediately. Without the persistent cache, Mango must query the time-series database (NoSQL or SQL) for the latest value of every data point during startup. On systems with thousands of data points, this can take several minutes.

With the persistent cache enabled, these latest values are stored in a compact on-disk map that can be read much faster than querying the full time-series store. This can reduce startup times from minutes to seconds on large systems.

Supported Implementations​

MapDB Module​

The original persistent cache implementation uses MapDB, a pure Java embedded database engine. This module stores the cache in a file called pointValueCache.db in the databases directory.

Configuration in mango.properties:

# Enable the MapDB point value cache
mapdb.enabled=false

# Directory for the cache database file
db.pointValueCache.location=databases

# How often to flush changes to disk
mapdb.commitFrequencyPeriods=30
mapdb.commitFrequencyPeriodType=SECONDS

Chronicle Map Module​

Chronicle Map is the recommended implementation for production systems. It uses memory-mapped files for higher performance than MapDB and supports persistence, recovery, and custom tuning.

Basic configuration in mango.properties:

# Enable Chronicle Map cache (replaces MapDB when present)
chroniclePointValueCache.enabled=true

# Path to the Chronicle database file
chroniclePointValueCache.databaseFile=databases/pointValueCache.chronicle

# Automatically recover the cache from disk on startup
chroniclePointValueCache.recover=true

# Only recover if the Chronicle library version matches (prevents compatibility errors)
chroniclePointValueCache.sameLibraryVersion=true

# Number of entries to hold — set to your number of data points or higher
chroniclePointValueCache.entries=1048576

# How much memory can expand beyond the initial estimate (1 = no expansion)
chroniclePointValueCache.maxBloatFactor=1

Migration from MapDB:

If you are switching from MapDB to Chronicle Map, add these properties once to migrate existing data:

chroniclePointValueCache.migrateFromMapdb=true
chroniclePointValueCache.migrateDelete=true   # delete old MapDB files after migration
warning

Back up your system before enabling migration. After the first successful start, set both properties back to false.

JVM options required for Mango 5:

When running Chronicle Map on Mango 5, add these options to your Mango start script (ma-start.sh):

MA_JAVA_OPTS="$MA_JAVA_OPTS --add-exports=java.base/jdk.internal.ref=ALL-UNNAMED"
MA_JAVA_OPTS="$MA_JAVA_OPTS --add-exports=java.base/sun.nio.ch=ALL-UNNAMED"
MA_JAVA_OPTS="$MA_JAVA_OPTS --add-opens=java.base/java.lang.reflect=ALL-UNNAMED"

Advanced tuning (optional):

PropertyDescription
chroniclePointValueCache.averageValueSizeExpected size in bytes of each point value. Helps Chronicle allocate memory efficiently.
chroniclePointValueCache.actualChunkSizeInternal chunk size for memory management.
chroniclePointValueCache.actualSegmentsNumber of map segments for concurrency.
chroniclePointValueCache.entriesPerSegmentHow many entries are stored in each segment.
chroniclePointValueCache.actualChunksPerSegmentTierControls chunk tier size per segment.

Leave these unset unless directed by Radix IoT support or doing performance profiling.

How It Works​

  1. During normal operation, whenever a new point value is stored in the time-series database, the persistent cache is also updated with the latest value for that point.
  2. The cache periodically flushes to disk based on the configured commit frequency.
  3. On startup, Mango reads the cached values from disk rather than querying the time-series store, dramatically improving initialization speed.
  4. If the cache file does not exist (first run or after deletion), Mango will rebuild it by pulling the latest values from the time-series store. This initial rebuild takes the same amount of time as a startup without the cache, but subsequent startups will be fast.

Sizing and Performance Considerations​

The cache stores one entry per data point, containing only the most recent value and its timestamp. The disk footprint is modest even for large systems -- typically a few megabytes for systems with tens of thousands of points.

The commit frequency setting controls the trade-off between data safety and write performance:

  • Shorter intervals (e.g., 10 seconds) ensure that fewer values are lost if Mango crashes, but increase disk I/O.
  • Longer intervals (e.g., 60 seconds) reduce disk I/O but risk losing more cached values on an unclean shutdown.
  • The default of 30 seconds is appropriate for most installations.

Troubleshooting​

Cache File Corruption​

If Mango fails to start with errors referencing the cache file, you can safely delete pointValueCache.db from the databases directory. Mango will rebuild the cache from the time-series store on the next startup.

Disk Space Issues​

If the system runs out of disk space while the MapDB cache is in use, the JVM may crash. See Linux Diagnostic Information for details on diagnosing crashes caused by disk space exhaustion. Ensure your monitoring includes disk space alerts.