
= Enable Time Series Integration Layer
:description: How to configure OpenNMS Horizon or Meridian to use the time series integration layer to support other time series databases.

Set the following property in `$\{OPENNMS_HOME}/etc/opennms.properties.d/timeseries.properties` to configure {page-component-title} to use the Time Series Integration Layer:

[source, properties]
org.opennms.timeseries.strategy=integration

[NOTE]
====
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:

[source, properties]
OPENNMS_TIMESERIES_STRATEGY=integration
====

[TIP]
====
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:

[source, properties]
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 {page-component-title} service.

== Additional configuration options

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

[cols="3,3,1"]
|===
| 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
|===

[[ga-opennms-operation-timeseries-properties-recommendations]]
== Recommendations

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

[caption=]
.Time series cache collectors
[options="autowidth"]
|===
| Name  | Description

| TimeseriesMetaDataCache
| Caches metadata that {page-component-title} 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.

[[ga-opennms-operation-timeseries-properties-meta-tags]]
== Expose additional meta tags

Metrics that are stored via the time series plugin contain the minimal set of tags for {page-component-title} to work.
This might not be sufficient if you also use the data outside of {page-component-title}.
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 https://en.wikipedia.org/wiki/.properties[Java properties file syntax].
* The query expression lets you query the value.
It supports the xref:operation:deep-dive/meta-data.adoc#ga-meta-data-dsl[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")`

=== Expose resource label and tags for latency resource

You can expose resource label as a tag by setting

* `org.opennms.timeseries.tin.metatags.tag.resourceLabel=${resource:label}`

Latency resource seems to be missing node label and location, you can expose these by setting

* `org.opennms.timeseries.tin.metatags.tag.nodeLabel=${resource:node_label}`
* `org.opennms.timeseries.tin.metatags.tag.nodeLocation=${resource:location}`

=== Expose Interface/Service data for Latency resource

To expose additional tags derived from the interface and SNMP interface on a latency resource, enable this functionality by configuring the poller as follows:

1.Update the Poller Configuration:

Add the following service property to the poller configuration:

[source,xml]
----
<service name="ICMP" interval="300000" user-defined="false" status="on">
    <parameter key="interface-info-in-tags" value="true"/>
</service>
----

2.Add Custom tags:

Define custom tags in the system properties to extract specific metadata from the interface. Below are examples of commonly used tags:

* `org.opennms.timeseries.tin.metatags.tag.ipAddress=${interface:address}`
* `org.opennms.timeseries.tin.metatags.tag.ifIndex=${interface:if-index}`
* `org.opennms.timeseries.tin.metatags.tag.service_name=${service:name}`