
[[newts-configure]]
= Configure {page-component-title} to Use Newts
:description: How to set up OpenNMS Newts, a time-series data store based on Apache Cassandra, for horizontal scaling.

This section describes how to configure your {page-component-title} instance to use Newts.

== Setup

Follow these steps to set up Newts on your {page-component-title} instance:

.Create a configuration file with the time series storage settings
[source, console]
----
sudo vi etc/opennms.properties.d/timeseries.properties
----

.Configure Newts as the time series strategy
[source, properties]
----
# Configure storage strategy
org.opennms.rrd.storeByForeignSource=true<1>
org.opennms.timeseries.strategy=newts<2>

# One year in seconds
org.opennms.newts.config.ttl=31540000<3>

# Seven days in seconds
org.opennms.newts.config.resource_shard=604800<4>

# Configure Newts time series storage connection
org.opennms.newts.config.driver_settings_file=/opt/opennms/etc/cassandra-driver.conf<5>
----

<1> Associate time series data by the foreign ID instead of the database-generated Node-ID.
<2> Set time series strategy to use `newts`.
<3> Retention rate for the time series data.
<4> Shard metrics every 7 days.
<5> The path to your driver configuration file

.Create a configuration file with the time series storage settings
[source, console]
----
sudo vi etc/cassandra-driver.conf
----

. Configure the Cassandra driver settings
[source, properties]
----
datastax-java-driver {
  basic.contact-points = [ "example-node1:9042", "example-node2:9042" ]<1>
  session-keyspace = "newts"<2>
  basic.load-balancing-policy {
    local-datacenter = datacenter1<3>
  }
  basic.request {
    page-size = 0<4>
  }
  advanced.auth-provider {
    class = PlainTextAuthProvider<5>
    username = cassandra
    password = cassandra
  }
}
----

<1> `Hostname:port` or `IP address:port` of one or more Cassandra cluster nodes.
<2> Name of the keyspace which is initialized and used.
<3> The local datacenter as defined by your Cassandra configuration
<4> Setting the page-size to 0 is recommended to disable query paging, avoiding unexpected gaps in graph data.
<5> The authentication provider to use with the supplied credentials

.(Optional) If your {page-component-title} data collection or polling intervals have been modified, set the query minimum and heartbeat rates:
+
[source, properties]
----
org.opennms.newts.query.minimum_step=30000 <1>
org.opennms.newts.query.heartbeat=450000 <2>
----
<1> The shortest collection interval configured for any collectable or pollable service, in milliseconds (in this case, 30 seconds).
<2> The communication interval for the Newts service, in milliseconds.
Should be set to 1.5 times the `maximum` value of the collection interval configured for any collectable or pollable service, in milliseconds (in this case, 450 seconds).

.Initialize the Newts schema in Cassandra:
+
[source, console]
bin/newts init

.Connect to Cassandra using the CQL shell:
+
[source, console]
----
cd ${CASSANDRA_HOME}/bin
./cqlsh
----

== Verify setup

After you have set the time series database to Newts and configured its settings, you must verify your setup and restart {page-component-title}:

.Verify keyspace initialization:
+
[source, console]
----
use newts;
describe table terms;
describe table samples;
----

.Restart {page-component-title} to apply your changes and verify your configuration:
+
[source, console]
systemctl restart opennms

After it restarts, {page-component-title} will begin to persist metrics using the Newts engine.
You can go to the Node Detail page for any SNMP-managed device to verify your setup; you should see response time graphs for the node's ICMP and node-level performance data.

NOTE: Only metrics stored in Newts are displayed in graphs.
If you have data stored in RRD files, it will not be displayed unless it is xref:time-series-storage/newts/newts-repository-converter.adoc[migrated to Newts].
