
[[newts-reference]]
= Configuration Reference
:description: Configuration properties for OpenNMS Newts, a time-series data store based on Apache Cassandra, for horizontal scaling.

Use the following properties, found in `$\{OPENNMS_HOME}/etc/opennms.properties`, to configure Newts.

[[ga-opennms-operation-newts-properties-general]]
== General

[caption=]
.Overview of Newts configuration properties
[cols="2,2,1"]
|===
| Name  | Description   | Default Value

| org.opennms.newts.config.keyspace
| Name of the keyspace to use.
| newts

| org.opennms.newts.config.hostname
| IP address or hostnames of the Cassandra nodes.
If including multiple node references, separate each with a single comma.
| localhost

| org.opennms.newts.config.port
| CQL port used to connect to the Cassandra nodes.
| 9042

| org.opennms.newts.config.username
| Username to use when connecting to Cassandra via CQL.
| cassandra

| org.opennms.newts.config.password
| Password to use when connecting to Cassandra via CQL.
| cassandra

| org.opennms.newts.config.datacenter
| Set this to the value of your local datacenter for the best performance.
| datacenter1

| org.opennms.newts.config.ssl
| Enable or disable SSL when connecting to Cassandra.
| false

| org.opennms.newts.config.connections-per-host
| Number of connections per host.
| _Driver default_

| org.opennms.newts.config.max-requests-per-connection
| Maximum number of requests that can be in flight on a single connection at the same time.
| _Driver default_

| org.opennms.newts.config.read_consistency
| Consistency level for read operations.
See http://docs.datastax.com/en/cassandra/2.1/cassandra/dml/dml_config_consistency_c.html[Configuring Data Consistency] in the Cassandra documentation for a list of available options.
| ONE

| org.opennms.newts.config.write_consistency
| Consistency level for write operations.
See http://docs.datastax.com/en/cassandra/2.1/cassandra/dml/dml_config_consistency_c.html[Configuring Data Consistency] in the official Cassandra documentation for a list of available options.
| ANY

| org.opennms.newts.config.driver_settings_file
| Cassandra driver settings file.
The configuration settings defined in this file overwrite all other driver-related settings.
See https://docs.datastax.com/en/developer/java-driver/4.14/manual/core/configuration/reference/[Reference Configuration] in the official DataStax documentation for details.
| _None_

| org.opennms.newts.config.max_batch_size
| Maximum number of records to insert in a single transaction.
Limited by the size of the Cassandra cluster's `batch_size_fail_threshold_in_kb` property.
| 16

| org.opennms.newts.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.newts.config.writer_threads
| Number of threads used to pull samples from the ring buffer and inserted into Newts.
| 16

| org.opennms.newts.config.ttl
| Number of seconds after which samples will automatically be deleted.
Defaults to one year, in seconds.
| 31540000

| org.opennms.newts.config.resource_shard
| Time (in seconds) that samples are stored at the same key.
Defaults to 7 days, in seconds.
| 604800

| org.opennms.newts.query.minimum_step
| Minimum step size, in milliseconds.
Used to prevent large queries.
| 300000

| org.opennms.newts.query.interval_divider
| If the query does not specify an interval, the step will be divided into this number of intervals when aggregating values.
| 2

| org.opennms.newts.query.heartbeat
| Duration, in milliseconds.
Used when no heartbeat is specified.
Should generally be 1.5 times your largest collection interval.
| 450000

| org.opennms.newts.query.parallelism
| Maximum number of threads that can be used to compute aggregates.
Defaults to the number of available cores.
| _Number of cores_

| org.opennms.newts.config.cache.strategy
| Canonical name of the class used for resource-level caching.
See the table below for all of the available options.
| _See below_

| org.opennms.newts.config.cache.max_entries
| Maximum number of records to keep in the cache when using an in-memory caching strategy.
| 8192

| org.opennms.newts.nan_on_counter_wrap
| Disables the processing of counter wraps, replacing them with NANs instead.
| false

| org.opennms.newts.config.cache.priming.disable
| Disables the cache primer, which preemptively loads the cache with indexed resources on startup.
| false

| org.opennms.newts.config.cache.priming.block_ms
| Block startup for this many milliseconds while waiting for the cache to be primed.
Set this value to `-1` to disable blocking.
Set this value to `0` to block indefinitely waiting for all of the records to be read.
| 120000
|===

[caption=]
.Available caching strategies
[options="autowidth"]
|===
| Name  | Class | Default

| In-memory cache
| org.opennms.netmgt.newts.support.GuavaSearchableResourceMetadataCache
| Y

| Redis-based cache
| org.opennms.netmgt.newts.support.RedisResourceMetadataCache
| N
|===

[[ga-opennms-operation-newts-properties-redis-cache]]
=== Redis Cache

When enabled, the following options can be used to configure the Redis-based cache:

[options="autowidth"]
|===
| Name  | Description   | Default

| org.opennms.newts.config.cache.redis_hostname
| IP address the Redis server's hostname.
| localhost

| org.opennms.newts.config.cache.redis_port
| TCP port used to connect to the Redis server.
| 6379
|===

== Recommendations

You will likely want to change the values of `cache.max_entries` and `ring_buffer_size` to suit your installation.

{page-component-title} caches metadata related to resources to avoid writing redundant records in Cassandra.
If you are collecting data from a large number of resources, you should increase `cache.max_entries` to reflect the number of resources you are collecting from, along with a suitable buffer.

The samples the collectors gather are temporarily stored in a ring buffer before they are persisted to Cassandra using Newts.
You should increase the value of `ring_buffer_size` if you expect large peaks of collectors returning at once or latency in persisting these to Cassandra.
Note, however, that the memory the ring buffer uses is reserved, and larger values may require an increased heap size.

Newts uses cache priming to help reduce the number of records that need to be indexed after restarting {page-component-title}.
This works by rebuilding the cache using the index data that has already been persisted in Cassandra.
If you continue to see large spikes of index-related inserts after rebooting, consider increasing the amount of time spent priming the cache.
