Enable Time Series Integration Layer

Set the following property in ${OPENNMS_HOME}/etc/opennms.properties.d/timeseries.properties to configure Horizon to use the Time Series Integration Layer:

org.opennms.timeseries.strategy=integration

If you are using a container, you can set this as an environment variable in your container’s configuration settings instead of creating or modifying a property file:

OPENNMS_TIMESERIES_STRATEGY=integration

We also highly recommend that you reference resources stored in the Time Series Integration Layer by their foreign source and foreign ID, as opposed to their database ID. To this end, set the following property in the same file:

org.opennms.rrd.storeByForeignSource=true

After you activate the Time Series Integration Layer, you must configure the plugin. For specific instructions, check your plugin’s documentation.

Enabling and configuring the Time Series Integration Layer requires a restart of the Horizon service.

Additional configuration options

Use the following properties, found in ${OPENNMS_HOME}/etc/opennms.properties, to configure the Time Series Integration Layer:

Name Description Default

org.opennms.timeseries.config.ring_buffer_size (Deprecated)

Maximum number of records that can be held in the ring buffer. Must be a power of two. This is overridden by org.opennms.timeseries.config.buffer_size, unless it is -1.

8192

org.opennms.timeseries.config.buffer_size

Maximum number of records that can be held in the memory buffer. Must be a power of two.

-1 (override by org.opennms.timeseries.config.ring_buffer_size)

org.opennms.timeseries.config.writer_threads

Number of threads used to pull samples from the buffer and insert them into the time series database.

16

org.opennms.timeseries.config.buffer_type

Type of buffer (RINGBUFFER or OFFHEAP).
RINGBUFFER is a high-performance queue. It keeps data only in memory. If the queue overflows, it will drop data.
OFFHEAP is a queue that will store data in memory. When the queue overflows, it will persist extra data onto the disk.

RINGBUFFER

org.opennms.timeseries.config.offheap.batch_size

Data block size for off-heap queue.

8192

org.opennms.timeseries.config.offheap.path

Location for storing off-heap data. This location should be a high-performance disk that will accommodate a high-load system.

/tmp

org.opennms.timeseries.config.offheap.max_file_size

Maximum file size of off-heap storage.

-1 (-1: unlimited)

org.opennms.timeseries.query.minimum_step

Minimum step size, in milliseconds. Used to prevent large queries.

300000

org.opennms.timeseries.query.interval_divider

If the query does not specify an interval, the step will be divided into this many intervals when aggregating values.

2

org.opennms.timeseries.query.heartbeat

Duration, in milliseconds. Used when no heartbeat is specified. Should generally be 1.5x your largest collection interval.

450000

org.opennms.timeseries.query.heartbeat.multiplier

Multiplier: use when heartbeat is smaller than step size. It will set heartbeat by step size times multiplier. Should generally be 1.5 times step size.

1.5

org.opennms.timeseries.query.parallelism

Maximum number of threads that can be used to compute aggregates. Defaults to the number of available cores.

Number of cores

cache.timeseriesPersisterMetaTagCache.expireAfterRead

Expiry time for MetaTagCache, in seconds.

300

cache.timeseriesPersisterMetaTagCache.maximumSize

Maximum size for MetaTagCache.

8192

cache.timeseriesPersisterMetaTagCache.recordStats

Expose cache statistics for MetaTagCache via JMX.

true

cache.timeseriesSearcherCache.expireAfterRead

Expiry time for TimeseriesSearcherCache, in seconds.

300

cache.timeseriesSearcherCache.maximumSize

Maximum number of entries for TimeseriesSearcherCache.

8192

cache.timeseriesSearcherCache.recordStats

Expose cache statistics for TimeseriesSearcherCache via JMX.

true

cache.timeseriesMetaDataCache.expireAfterRead

Expiry time for TimeseriesMetaDataCache, in seconds.

300

cache.timeseriesMetaDataCache.maximumSize

Maximum number of entries for TimeseriesMetaDataCache.

8192

cache.timeseriesMetaDataCache.recordStats

Expose cache statistics for TimeseriesMetaDataCache via JMX.

true

Recommendations

The Time Series Integration Layer includes several caches to improve performance. You can configure the cache settings using the parameters above.

Time series cache collectors
Name Description

TimeseriesMetaDataCache

Caches metadata that Horizon uses internally.

TimeseriesSearcherCache

Caches metrics by tag to improve the resource lookup.

TimeseriesPersisterMetaTagCache

Caches all additional configured and resolved meta tag values by resource.

The samples that the collectors gather are temporarily stored in a buffer before they are persisted to the Time Series Integration Layer. You should increase the value of the buffer_size if you expect large peaks of collectors returning at once, or if you experience latency in persisting them. Note, however, that the memory used by the buffer is reserved, and assigning larger values may require an increased heap size.

Expose additional meta tags

Metrics that are stored via the time series plugin contain the minimal set of tags for Horizon to work. This might not be sufficient if you also use the data outside of Horizon. Configure additional meta tags using a .properties file in the ${OPENNMS_HOME}/etc/opennms.properties.d/ directory.

The configuration of the tags has the following form: prefix.tagKey=${query expression}.

  • The prefix is org.opennms.timeseries.tin.metatags.tag.

  • The tagKey can be an arbitrary string, as long as it does not break the Java properties file syntax.

  • The query expression lets you query the value. It supports the Metadata DSL within the node, asset, and requisition contexts.

The following examples demonstrate proper tag definition syntax:

  • org.opennms.timeseries.tin.metatags.tag.nodelabel=${node:label}

  • org.opennms.timeseries.tin.metatags.tag.sysObjectID=${node:sys-object-id}

Expose categories as meta tags

You can expose node categories as meta tags by setting org.opennms.timeseries.tin.metatags.exposeCategories to true. This results in the following tags:

  • Tag("cat_myFirstCategory", "myFirstCategory")

  • Tag("cat_mySecondCategory", "mySecondCategory")