Cassandra monitoring integration

Our Cassandra integration sends performance metrics and inventory data from your Cassandra database to the New Relic platform. You can view pre-built dashboards of your Cassandra metric data, create alert policies, and create your own custom queries and charts.

Read on to install the integration, and to see what data we collect.

Compatibility and requirements

Our integration is compatible with Apache Cassandra version 3.x or higher.

Before installing the integration, make sure that you meet the following requirements:

Java Runtime Environment 7 or higher.
If Cassandra is not running on Kubernetes or Amazon ECS, you must install the infrastructure agent on a Linux host that's running Cassandra. Otherwise:
- If running on Kubernetes, see these requirements.
- If running on ECS, see these requirements.

Quick start: Use our guided install

Instrument your Cassandra database quickly and send your telemetry data with guided install. Our guided install creates a customized CLI command for your environment that downloads and installs the New Relic CLI and the infrastructure agent.

Ready to get started? Click one of these button to try it out.

Guided install

EU Guided install

Our guided install uses the infrastructure agent to set up the Cassandra integration. Not only that, it discovers other applications and log sources running in your environment and then recommends which ones you should instrument.

The guided install works with most setups. But if it doesn't suit your needs, you can find other methods below to get started monitoring your Cassandra database.

Install and activate

To install the Cassandra integration, follow the instructions for your environment:

Additional notes:

Advanced: Integrations are also available in tarball format to allow for install outside of a package manager.
On-host integrations do not automatically update. For best results, regularly update the integration package and the infrastructure agent.

To install the Cassandra integration on Linux:

Follow the instructions for installing an integration, using the file name nri-cassandra.
Change the directory to the integration folder:
```
cd /etc/newrelic-infra/integrations.d
```

Copy the sample configuration file:

sudo cp cassandra-config.yml.sample cassandra-config.yml

Edit the cassandra-config.yml file as described in the configuration settings.
Restart the infrastructure agent.
To enable automatic Cassandra error log parsing and forwarding, copy (or rename) the cassandra-log.yml.example file to cassandra-log.yml. No need to restart the agent.
Example:
```
sudo cp /etc/newrelic-infra/logging.d/casssandra-log.yml.example /etc/newrelic-infra/logging.d/cassandra-log.yml
```

Configuration

Configure the integration

There are several ways to configure the integration, depending on how it was installed:

If enabled via Kubernetes: see Monitor services running on Kubernetes.
If enabled via Amazon ECS: see Monitor services running on ECS.
If installed on-host: edit the config in the integration's YAML config file, cassandra-config.yml.

An integration's YAML-format configuration is where you can place required login credentials and configure how data is collected. Which options you change depend on your setup and preference.

The configuration file has common settings applicable to all integrations, such as interval, timeout, inventory_source. To read all about these common settings, refer to our Configuration Format document.

Important

If you are still using our legacy configuration/definition files, please refer to this document for help.

Specific settings related to Cassandra are defined using the env section of the configuration file. These settings control the connection to your Cassandra instance as well as other security settings and features. The list of valid settings is described in the next section of this document.

Cassandra Instance Settings

The Cassandra integration collects both metrics(M) and inventory(I) information. In the table, use the Applies To column for the settings available to each collection:

Setting	Description	Default	Applies to
HOSTNAME	Hostname or IP where Cassandra is running.	localhost	M/I
PORT	Port on which Cassandra is listening.	7199	M
USERNAME	Username for accessing JMX.	N/A	M
PASSWORD	Password for the given user.	N/A	M
CONFIG_PATH	Path to the Cassandra configuration file.	/etc/cassandra/ cassandra.yaml	I
COLUMN_FAMILIES_LIMIT	Limit on number of Cassandra Column Families.	20	M
TIMEOUT	Request timeout in milliseconds.	2000	M
KEY_STORE	The filepath of the keystore containing the JMX client's SSL certificate.	N/A	M
KEY_STORE_PASSWORD	The password for the JMX SSL key store.	N/A	M
TRUST_STORE	The filepath of the trust store containing the JMX client's SSL certificate.	N/A	M
TRUST_STORE_PASSWORD	The password for the JMX SSL trust store.	N/A	M
REMOTE_MONITORING	Enable multi-tenancy monitoring.	false	M/I
METRICS	Set to `true` to enable metrics-only collection.	false
INVENTORY	Set to `true` to enable inventory-only collection.	false

The values for these settings can be defined in several ways:

Adding the value directly in the config file. This is the most common way.
Replacing the values from environment variables using the {{}} notation. This requires infrastructure agent v1.14.0+. Read more here or see the example below.
Using secrets management. Use this to protect sensitive information, such as passwords that would be exposed in plain text on the configuration file. For more information, see Secrets management.

Labels/Custom attributes

You can further decorate your metrics using labels. Labels allow you to add key/value pair attributes to your metrics, which you can then use to query, filter, or group your metrics on.
Our default sample config file includes examples of labels; however, as they are not mandatory, you can remove, modify, or add new ones of your choice.

labels:
   env: production
   role: load_balancer

Example configurations

This is the basic configuration used to collect metrics and inventory from your localhost:

integrations:
  - name: nri-cassandra
    env:
      HOSTNAME: localhost
      PORT: 7199
      USERNAME: cassandra_user
      PASSWORD: cassandra_password
      CONFIG_PATH: /etc/cassandra/cassandra.yml
    interval: 30s
    labels:
      environment: production
    inventory_source: config/cassandra

This configuration collects metrics every 30 seconds and inventory every 60 seconds:

integrations:
  - name: nri-cassandra
    env:
      METRICS: true
      HOSTNAME: localhost
      PORT: 7199
      USERNAME: cassandra_user
      PASSWORD: cassandra_password
      REMOTE_MONITORING: true
    interval: 30s
    labels:
      environment: production

  - name: nri-cassandra
    env:
      INVENTORY: true
      HOSTNAME: localhost
      PORT: 7199
      USERNAME: cassandra_user
      PASSWORD: cassandra_password
      CONFIG_PATH: /etc/cassandra/cassandra.yml
    interval: 60s
    labels:
      environment: production
    inventory_source: config/cassandra

In this configuration we are using the environment variable CASSANDRA_HOST to populate the HOSTNAME setting of the integration:

integrations:
  - name: nri-cassandra
    env:
      METRICS: "true"
      HOSTNAME: {{CASSANDRA_HOST}}
      PORT: 7199
      USERNAME: cassandra_user
      PASSWORD: cassandra_password
    interval: 15s
    labels:
      env: production
      role: load_balancer

In this configuration we are monitoring multiple Cassandra servers from the same integration. For the first instance (HOSTNAME: 1st_cassandra_host) we are collecting metrics and inventory while for the second instance (HOSTNAME: 2nd_cassandra_host) we will only collect metrics.

integrations:
  - name: nri-cassandra
    env:
      METRICS: "true"
      HOSTNAME: 1st_cassandra_host
      PORT: 7199
      USERNAME: cassandra_user
      PASSWORD: cassandra_password
    interval: 30s
    labels:
      env: production
      role: load_balancer
  - name: nri-cassandra
    env:
      INVENTORY: "true"
      HOSTNAME: 1st_cassandra_host
      PORT: 7199
      USERNAME: cassandra_user
      PASSWORD: cassandra_password
    interval: 60s
    labels:
      env: production
      role: load_balancer
    inventory_source: config/cassandra

  - name: nri-cassandra
    env:
      METRICS: "true"
      HOSTNAME: 2nd_cassandra_host
      PORT: 7199
      USERNAME: cassandra_user
      PASSWORD: cassandra_password
    interval: 30s
    labels:
      env: production
      role: load_balancer

Find and use data

Data from this service is reported to an integration dashboard.

Cassandra data is attached to the CassandraSample and CassandraColumnFamilySample event types. You can query this data for troubleshooting purposes or to create charts and dashboards.

For more on how to find and use your data, see Understand integration data.

Metric data

The Cassandra integration collects the following metrics.

Node metrics

Cassandra node metrics are attached to the CassandraSample event type. The Cassandra integration collects these node metrics:

Name	Description
`db.allMemtablesOffHeapSizeBytes`	Total amount of bytes stored in the memtables (2i and pending flush memtables included) that resides on-heap.
`db.allMemtablesOnHeapSizeBytes`	Total amount of bytes stored in the memtables (2i and pending flush memtables included) that resides off-heap.
`db.commitLogCompletedTasksPerSecond`	The number of commit log messages written per second.
`db.commitLogPendindTasks`	Number of commit log messages written but yet to be fsync’ed.
`db.commitLogTotalSizeBytes`	Current size, in bytes, used by all the commit log segments.
`db.droppedRequestTypeMessagesPerSecond`	Dropped messages per second for this type of request. `RequestType` can be any of the following: BatchRemove, BatchStore, CounterMutation, Hint, Mutation, PagedRange, RangeSlice, Read, ReadRepair, RequestResponse, or Trace.
`db.keyCacheCapacityBytes`	Key cache capacity in bytes.
`db.keyCacheHitRate`	One-minute key cache hit rate.
`db.keyCacheHitsPerSecond`	Number of key cache hits per second.
`db.keyCacheRequestsPerSecond`	Number of requests to the key cache per second.
`db.keyCacheSizeBytes`	Size of occupied cache in bytes.
`db.liveSSTableCount`	Number of SSTables on disk for this column family.
`db.loadBytes`	Size, in bytes, of the on disk data size this node manages.
`db.rowCacheCapacityBytes`	Row cache capacity in bytes.
`db.rowCacheHitRate`	One-minute row cache hit rate.
`db.rowCacheHitsPerSecond`	Number of row cache hits per second.
`db.rowCacheRequestsPerSecond`	Number of requests to the row cache per second.
`db.rowCacheSizeBytes`	Total size of occupied row cache, in bytes.
`db.threadpool.poolActiveTasks`	Number of tasks being actively worked on by this pool. `pool` can be one of the following: internalAntiEntropyStage internalCacheCleanupExecutor internalCompactionExecutor internalGossipStage internalHintsDispatcher internalInternalResponseStage internalMemtableFlushWriter internalMemtablePostFlush internalMemtableReclaimMemory internalMigrationStage internalMiscStage internalPendingRangeCalculator internalSampler internalSecondaryIndexManagement internalValidationExecutor requestCounterMutationStage requestMutationStage requestReadRepairStage requestReadStage requestRequestResponse requestViewMutationStage
`db.threadpool.pool.PendingTasks`	Number of tasks being actively worked on by this pool. `pool` can be any of the items in the list provided in the description of `db.threadpool.poolActiveTasks`.
`db.totalHintsInProgress`	Number of hints currently attempting to be sent.
`db.totalHintsPerSecond`	Number of hint messages per second written to this node. Includes one entry for each host to be hinted per hint.
`query.CASReadRequestsPerSecond`	Transaction read latency in requests per second.
`query.CASWriteRequestsPerSecond`	Transaction write latency in requests per second.
`query.rangeSliceRequestsPerSecond`	Number of range slice requests per second.
`query.rangeSliceTimeoutsPerSecond`	Number of timeouts encountered per second when processing token range read requests.
`query.rangeSliceUnavailablesPerSecond`	Number of unavailable exceptions encountered per second when processing token range read requests.
`query.readLatency50thPercentileMilliseconds`	Read latency in milliseconds, 50th percentile.
`query.readLatency75thPercentileMilliseconds`	Read latency in milliseconds, 75th percentile.
`query.readLatency95thPercentileMilliseconds`	Read latency in milliseconds, 95th percentile.
`query.readLatency98thPercentileMilliseconds`	Read latency in milliseconds, 98th percentile.
`query.readLatency999thPercentileMilliseconds`	Read latency in milliseconds, 999th percentile.
`query.readLatency99thPercentileMilliseconds`	Read latency in milliseconds, 99th percentile.
`query.readRequestsPerSecond`	Number of read requests per second.
`query.readTimeoutsPerSecond`	Number of timeouts encountered per second when processing standard read requests.
`query.readUnavailablesPerSecond`	Number of unavailable exceptions encountered per second when processing standard read requests.
`query.viewWriteRequestsPerSecond`	Number of view write requests per second.
`query.writeLatency50thPercentileMilliseconds`	Write latency in milliseconds, 50th percentile.
`query.writeLatency75thPercentileMilliseconds`	Write latency in milliseconds, 75th percentile.
`query.writeLatency95thPercentileMilliseconds`	Write latency in milliseconds, 95th percentile.
`query.writeLatency98thPercentileMilliseconds`	Write latency in milliseconds, 98th percentile.
`query.writeLatency999thPercentileMilliseconds`	Write latency in milliseconds, 999th percentile.
`query.writeLatency99thPercentileMilliseconds`	Write latency in milliseconds, 99th percentile.
`query.writeRequestsPerSecond`	Number of write requests per second.
`query.writeTimeoutsPerSecond`	Number of timeouts encountered per second when processing regular write requests.
`query.writeUnavailablesPerSecond`	Number of unavailable exceptions encountered per second when processing regular write requests.

Cassandra column family metrics and metadata

The Cassandra integration retrieves column family metrics. Cassandra column family data is attached to the CassandraColumnFamilySample event type. It skips system keyspaces (system, system_auth, system_distributed, system_schema, system_traces and OpsCenter). To limit the performance impact, the integration will only capture metrics for a maximum of 20 column families.

The following metadata indicates the keyspace and column family associated with the sample metrics:

Name	Description
`db.columnFamily`	The Cassandra column family these metrics refer to.
`db.keyspace`	The Cassandra keyspace that contains this column family.
`db.keyspaceAndColumnFamily`	The keyspace and column family in a single metadata attribute in the following format: `keyspace`.`columnFamily`.

The list of metrics below refer to the specific keyspace and column family specified in the metadata above:

Name	Description
`db.allMemtablesOffHeapSizeBytes`	Total number of bytes stored in the memtables (2i and pending flush memtables included) that resides off-heap.
`db.allMemtablesOnHeapSizeBytes`	Total number of bytes stored in the memtables (2i and pending flush memtables included) that resides on-heap.
`db.liveDiskSpaceUsedBytes`	Disk space in bytes used by SSTables belonging to this column family (in bytes).
`db.liveSSTableCount`	Number of SSTables on disk for this column family.
`db.pendingCompactions`	Estimate of number of pending compactions for this column family.
`db.SSTablesPerRead50thPercentileMilliseconds`	Number of sstable data files accessed per read, 50th percentile.
`db.SSTablesPerRead75thPercentileMilliseconds`	Number of sstable data files accessed per read, 75th percentile.
`db.SSTablesPerRead95thPercentileMilliseconds`	Number of sstable data files accessed per read, 95th percentile.
`db.SSTablesPerRead98thPercentileMilliseconds`	Number of sstable data files accessed per read, 98th percentile.
`db.SSTablesPerRead999thPercentileMilliseconds`	Number of sstable data files accessed per read, 999th percentile.
`db.SSTablesPerRead99thPercentileMilliseconds`	Number of sstable data files accessed per read, 99th percentile.
`query.readLatency50thPercentileMilliseconds`	Local read latency in milliseconds for this column family, 50th percentile.
`query.readLatency75thPercentileMilliseconds`	Local read latency in milliseconds for this column family, 75th percentile.
`query.readLatency95thPercentileMilliseconds`	Local read latency in milliseconds for this column family, 95th percentile.
`query.readLatency98thPercentileMilliseconds`	Local read latency in milliseconds for this column family, 98th percentile.
`query.readLatency999thPercentileMilliseconds`	Local read latency in milliseconds for this column family, 999th percentile.
`query.readLatency99thPercentileMilliseconds`	Local read latency in milliseconds for this column family, 99th percentile.
`query.readRequestsPerSecond`	Number of read requests per second for this column family.
`query.writeLatency50thPercentileMilliseconds`	Local write latency in milliseconds for this column family, 50th percentile.
`query.writeLatency75thPercentileMilliseconds`	Local write latency in milliseconds for this column family, 75th percentile.
`query.writeLatency95thPercentileMilliseconds`	Local write latency in milliseconds for this column family, 95th percentile.
`query.writeLatency98thPercentileMilliseconds`	Local write latency in milliseconds for this column family, 98th percentile.
`query.writeLatency999thPercentileMilliseconds`	Local write latency in milliseconds for this column family, 999th percentile.
`query.writeLatency99thPercentileMilliseconds`	Local write latency in milliseconds for this column family, 99th percentile.
`query.writeRequestsPerSecond`	Number of write requests per second for this column family.

Inventory

The integration captures configuration options defined in the Cassandra configuration and reports them as inventory data in the New Relic UI.

System metadata

The Cassandra integration also collects these attributes about the service and its configuration:

Name	Description
`software.version`	The Cassandra version.
`cluster.name`	The name of the cluster this Cassandra node belongs to.

Troubleshooting

Troubleshooting via jmxterm

JMXTerm is a command line interactive tool bundled within the integration package.

Docs for JMXTerm can be found at our nrjmx page in GitHub.

Check the source code

This integration is open source software. That means you can browse its source code and send improvements, or create your own fork and build it.