Enable Time Series Integration Layer

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

org.opennms.timeseries.strategy=integration

After activating the Time Series Integration Layer, you need to start an actual implementation. Do this via Karaf. Here is an example of how to activate the in memory time series plugin:

clone & build:
> git clone git@github.com:opennms-forge/timeseries-integration-inmemory.git
> mvn install

in Karaf shell:
> bundle:install -s mvn:org.opennms.plugins.timeseries.inmemory/timeseries-inmemory-plugin/1.0.0-SNAPSHOT

For specific instructions, check your plugin description.

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

With these set, upon restart, Horizon begins persisting metrics using the Time Series Integration Layer.

Additional configuration options

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

Name Description Default

org.opennms.timeseries.config.ring_buffer_size

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

8192

org.opennms.timeseries.config.writer_threads

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

16

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.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 in seconds for MetaTagCache

300

cache.timeseriesPersisterMetaTagCache.maximumSize

Maximum size for MetaTagCache

8192

cache.timeseriesPersisterMetaTagCache.recordStats

Should cache statistics be exposed via JMX for MetaTagCache?

true

cache.timeseriesSearcherCache.expireAfterRead

Expiry time in seconds for TimeseriesSearcherCache

300

cache.timeseriesSearcherCache.maximumSize

Maximum size for TimeseriesSearcherCache

8192

cache.timeseriesSearcherCache.recordStats

Should cache statistics be exposed via JMX for TimeseriesSearcherCache?

true

cache.timeseriesMetaDataCache.expireAfterRead

Expiry time in seconds for TimeseriesMetaDataCache

300

cache.timeseriesMetaDataCache.maximumSize

Maximum size for TimeseriesMetaDataCache

8192

cache.timeseriesMetaDataCache.recordStats

Should cache statistics be exposed via JMX for TimeseriesMetaDataCache?

true

Recommendations

The Time Series Integration Layer includes several caches to improve performance. You can tune the cache settings to suit your needs, using the parameters above.

Name Description

TimeseriesMetaDataCache

Caches metadata that uses Horizon internally.

TimeseriesSearcherCache

Caches metrics by tag to improve the resource lookup.

TimeseriesPersisterMetaTagCache

Caches all additionally configured and resolved meta-tag values by resource.

The samples the collectors gather are temporarily stored in a ring buffer before they are persisted to the Time Series Integration Layer. Increase the value of the ring_buffer_size if you expect large peaks of collectors returning at once or latency in persisting these. However, note that the memory the ring buffer uses is reserved, and 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 via 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. Supports use of the Metadata DSL.

Examples:

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

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

Expose categories by setting org.opennms.timeseries.tin.metatags.exposeCategories to true.

  • org.opennms.timeseries.tin.metatags.exposeCategories=true

Will lead to:

  • Tag("cat_myFirstCategory", "myFirstCategory")

  • Tag("cat_mySecondCategory", "mySecondCategory")