OpenNMS Time Series DB

The OpenNMS Time Series DB is a cloud-hosted service that provides a scalable time series database to store and persist performance metrics that Meridian collects from monitored devices.

Requirements

You must have the following to use the Time Series DB:

  • Horizon 31+ (Meridian availability with the 2023 release).

  • A Time Series DB subscription. The subscription provides access to the OpenNMS Portal, where you can retrieve your activation key and view Time Series DB metrics. Contact sales@opennms.com to sign up.

When you sign up for the Time Series DB subscription, you receive an activation email from The OpenNMS Group with a login for the OpenNMS Portal. If you do not receive the activation email, contact your account manager.

Deployment

Follow these steps to set up the Time Series DB in your environment:

  1. Update your OpenNMS Cloud Services Connector files.

  2. Configure Cloud Services settings.

  3. Obtain an activation key for the Cloud Services Connector.

  4. Enable Cloud Services connectivity.

  5. Allow Meridian to make outgoing connections to the following gateways:

    • TCP auth.access.onms-dp-prod.production.prod.dataservice.opennms.com:443

    • TCP gateway.onms-dp-prod.production.prod.dataservice.opennms.com:443

You should ensure that your firewall allows access to the gateways above. If they are blocked, you cannot enable the Cloud Services.

Update Cloud Services Connector files

The OpenNMS Cloud Services Connector is an extension that lets your Meridian instance send time series data to the OpenNMS-hosted cloud service. The packages for this extension are installed by default in Horizon 31 and later, but they do need to be configured and activated. You can use yum or apt to make sure your opennms-cloud-plugin package is up to date.

To ensure that the feature is activated on future service restarts, add the feature to a file in featuresBoot.d:

echo "opennms-plugin-cloud-core wait-for-kar=opennms-plugin-cloud" | sudo tee ${OPENNMS_HOME}/etc/featuresBoot.d/plugin-cloud.boot

Configure Cloud Services

You must configure your Meridian instance to load the Cloud Services plugin on start, and to direct storage to the cloud service. If you are using Horizon 31 or later, copy the example timeseries.properties file to your working directory:

cp ${OPENNMS_HOME}/etc/examples/opennms.properties.d/hosted_tsdb.timeseries.properties ${OPENNMS_HOME}/etc/opennms.properties.d/timeseries.properties

You can configure custom tags in the following contexts in ${OPENNMS_HOME}/etc/opennms.properties.d/timeseries.properties:

  • Asset

  • Interface

  • Node

  • Service

  • Resource

  • Metadata

Only users who can access the data in their Time Series DB (for example, via Cortex or InfluxDB) can configure custom tags.

Below are examples of tag definitions:

org.opennms.timeseries.tin.metatags.tag.node=${node:label}
org.opennms.timeseries.tin.metatags.tag.location=${node:location}
org.opennms.timeseries.tin.metatags.tag.geohash=${node:geohash}
org.opennms.timeseries.tin.metatags.tag.ifDescr=${ipInterface:if-description}
org.opennms.timeseries.tin.metatags.tag.label=${resource:label}

After the plugin is installed and configured, restart the Meridian service:

systemctl restart opennms

Obtain an activation key

An activation key lets your Meridian instance connect to the Time Series DB cloud service. You must log in to the OpenNMS Portal to access the key, copy it, and paste it into the appropriate page in Meridian.

The activation key is valid for one hour. If you do not use it within that time, you must log in to the OpenNMS Portal again, delete the instance, create a new instance, and generate a new key.

To obtain the activation key, follow these steps:

  1. If you have not already done so, activate your OpenNMS Portal account by clicking Account Activation in your welcome email.

  2. Sign in to the OpenNMS Portal.

  3. Choose OpenNMS Core Instances in the left menu and click Add New.

  4. Type the name of your instance and click Generate Activation Key.

  5. Copy the activation key and click Save & Close.

Enable Cloud Services connectivity

To install the activation key on your Meridian instance, follow these steps:

  1. Log in to Meridian.

  2. In the top menu bar, click Plugins  Cloud Services.

  3. Turn the Cloud Services Deactivate toggle on.

  4. Paste the activation key in the Enter Activation Key box, and click Activate.

By default, collectd collects data every five minutes. You should see time series summary information in the OpenNMS Portal UI within 15 minutes. For more information on how to view this information, see View time series summary data. To change the data collection frequency, see Service configuration attributes.

Troubleshooting

To verify that your Time Series DB is set up correctly, run the health-check command in Karaf. The resulting output should be similar to the following example:

admin@opennms()> health-check
Verifying the health of the container

Verifying installed bundles                    [ Success  ]
Cloud status                                   [ Success  ] => Cloud status=SERVING
Connecting to ElasticSearch ReST API (Flows)   [ Success  ] => Not configured

=> Everything is awesome

Check the Karaf logs if the registration fails or the health check does not say SERVING. If this is the case, you will need to open a support ticket.

You can also check if the ${OPENNMS_HOME}/share/rrd files are still being updated. If they are not, this indicates that the Time Series DB is working.

View time series summary data

You can view time series summary data, including health status, capacity, and metrics per second, in the OpenNMS Portal. By default, the screen displays data for all OpenNMS instances that you have configured to use the Time Series DB. You can filter to see data for a specific instance.

  1. Sign in to the OpenNMS Portal.

  2. In the left menu, click Time Series.

  3. To see summary data for a specific instance, type an instance name in the Search Instances field.

    The screen updates to display only that instance and its associated summary data.