Retrieving Cluster and Node Information

These resources give you information about your cluster and its nodes. For example, you can get a map of node information including the current OS load, the data held in storage, or the status of streaming or compaction operations underway.

Cluster and Node Retrieval Methods URL

Retrieve cluster data size

Retrieve cluster configuration information.

Retrieve information about a cluster property.

Retrieve information about nodes in the cluster.

Retrieve information about a specific node.

Retrieve information about the property of a node.

Retrieve information about a property for all nodes.

Retrieve cluster-wide storage capacity information.

Download a diagnostic tarball of cluster data.

Cluster Properties

The following commands retrieve information about the cluster.

GET /{cluster_id}/datasize/keyspaces

Retrieve data size of the cluster. Can be broken down by keyspaces and datacenter.

Path arguments:

  • cluster_id: The ID of a cluster returned from GET /cluster-configs.

  • keyspaces: List of keyspaces of which to get the size. If blank, size of all keyspaces are returned.

  • datacenters: List of datacenters of which to get the size. If blank, size all datacenters are returned.

Returns size of the data in bytes.

Example:

 curl http://127.0.0.1:8888/Test_Cluster/datasize/keyspaces

Output:

  106286829.0

GET /{cluster_id}/cluster

Retrieve information about the cluster.

Path arguments: cluster_id: The ID of a cluster returned from GET /cluster-configs.

Returns a Cluster object.

Responses: Cluster

 {
    "endpoint_snitch": Full class name of snitch,
    "name": Name of the cluster,
    "partitioner": Full class name of partitioner,
    "status": Status if the cluster is being restarted
 }

Example:

 curl http://127.0.0.1:8888/Test_Cluster/cluster

Output:

 {
    "endpoint_snitch": "org.apache.cassandra.locator.SimpleSnitch",
    "name": "Test Cluster",
    "partitioner": "org.apache.cassandra.dht.RandomPartitioner",
    "status": "Restarting"
 }

GET /{cluster_id}/cluster/{property}

Retrieve a single cluster property.

Path arguments:

  • cluster_id: The ID of a cluster returned from GET /cluster-configs.

  • * property**: A property of cluster.

Returns a string.

Example:

curl http://127.0.0.1:8888/Test_Cluster/cluster/partitioner

Output:

  "org.apache.cassandra.dht.RandomPartitioner"

Node Properties

GET /{cluster_id}/nodes

Retrieve a list of all nodes and node properties in the cluster.

Path arguments: cluster_id: The ID of a cluster returned from GET /cluster-configs.

Returns a list of node objects.

Response: Node

A property is null if it is not applicable to the node or if there is no data to report.

{
  "node_ip": <value>,
  "node_name": <value>,
  "token": <value>,
  "node_version": <name:value>,
  "load": <value>,
  "data_held": <value>,
  "mode": <value>,
  "streaming": <name:value, name:value, . . .>,
  "task_progress": <name:value, name:value, . . .>,
  "last_seen": <value>,
  "num_procs": <value>,
  "rpc_ip": <value>,
  "dc": <value>,
  "rack": <value>,
  "network_interfaces": <value array>,
  "partitions": {
    "data": <value list>,
    "commitlog": <value>,
    "saved_caches": <value>,
    "other": <value list>
  },
  "devices": {
    "data": <value list>,
    "commitlog": <value>,
    "saved_caches": <value>,
    "other": <value list>
  },
  "os": <value>,
  "has_jna": <value>,
  "ec2": {
    "instance-id": <value>,
    "instance-type": <value>,
    "ami-id": <value>,
    "placement": <value>
  }
}

This table describes the property values of a Node:

Property

Description of Values

node_ip

IP address

node_name

Hostname

token

Token assignment (string). If the node has multiple tokens (part of vnode support in Cassandra 1.2 and later), this will be a single randomly selected token from the node’s set of tokens.

node_version

Dictionary of component versions: - cassandra: Cassandra version - dse: DSE version - jobtracker: Job Tracker version - tasktracker: Task Tracker version - search: Solr version

load

OS load, which corresponds to the command, 1min avg from uptime

data_held

Amount of Cassandra data on the node (in bytes)

mode

Examples are "normal", "decommissioned", "leaving". Controlled by Cassandra.

streaming

Dictionary of active outbound streams in the form \{<destination_node_ip>: <progress>}, where <progress> is a float between 0.0 and 1.0.

For example, 0.8 means the stream is 80% complete.

task_progress

Dictionary of active tasks in the form \{<task-name-string>: <progress>}.

Example task names include "major-compaction" and "minor-compaction". <progress> is the same format as it is for streaming.

last_seen

0 if the node is up, a UNIX timestamp indicating when the node went down if it is currently down, or null if the node state is unknown

num_procs

Number of processor cores

rpc_ip

The rpc_address set in cassandra.yaml, which is usually the same as the node_ip property

dc

Name of node’s data center

rack

Name of node’s rack

network_interfaces

Array of network interface names

partitions

Dictionary of partitions on the node grouped by category:

  • data: List of partitions where Cassandra data is stored

  • commitlog: Partition where the commitlog resides

  • saved_caches: Partition where caches are saved

  • other: List of other partitions on the node that are not used by Cassandra

devices

Dictionary of devices on the node grouped by category:

  • data: List of devices where Cassandra data is stored

  • commitlog: Device where the commitlog resides

  • saved_caches: Device where caches are saved

  • other: List of other devices on the node that are not used by Cassandra

os

Name of the operating system that will contain "linux", "mac", or "windows"

has_jna

True if the node has JNA enabled, false otherwise

ec2

Dictionary of ec2 information:

  • instance_id: the EC2 instance ID

  • instance-type: the size and type of the node’s EC2 instance

  • ami-id: what AMI was used for the instance

  • placement: what AWS region and availability zone where the node is located

Example:

 curl http://127.0.0.1:8888/Test_Cluster/nodes

Output:

{
  "192.168.1.28": {
    "data_held": 53067368.0,
    "dc": "Cassandra",
    "devices": {
      "commitlog": "disk0",
      "data": [
        "disk0"
      ],
      "other": [],
      "saved_caches": "disk0"
    },
    "ec2": {
      "ami-id": "ami-82fa58eb",
      "instance-id": "i-1c264a66",
      "instance-type": "m1.large",
      "placement": "us-east-1d"
    },
    "has_jna": true,
    "last_seen": 0,
    "load": 0.20000000000000001,
    "mode": "normal",
    "network_interfaces": [
          "lo0",
      "en0",
      "en1"
    ],
    "node_ip": "192.168.1.28",
    "node_name": "cassandra08",
    "node_version": {
      "cassandra": "1.0.8",
      "dse": "2.0-1",
      "jobtracker": null,
      "search": null,
      "tasktracker": null
    },
    "num_procs": 8,
    "os": "mac os x",
    "partitions": {
      "commitlog": "/dev/disk0s2",
      "data": [
        "/dev/disk0s2"
      ],
      "other": [],
      "saved_caches": "/dev/disk0s2"
    },
    "rack": "rack1",
    "rpc_ip": "192.168.1.28",
    "streaming": {
      "192.168.1.27": 0.23,
      "192.168.1.29": 0.97,
    },
    "task_progress": {
      "minor-compaction": 0.447
    },
    "token": "34478773810192488084662817292306645152"
  },
  "192.168.1.29": {
    ...
  }
  ...
}

GET /{cluster_id}/nodes/{node_ip}

Retrieve data for a specific node.

Path arguments:

  • cluster_id: The ID of a cluster returned from GET /cluster-configs.

  • node_ip : IP address matching the node_ip for the :`node`.

Returns a node object.

GET /{cluster_id}/nodes/{node_ip}/{property}

Retrieve a single property for a node or all nodes.

Path arguments:

  • cluster_id: The ID of a cluster returned from GET /cluster-configs.

  • node_ip : IP address matching the node_ip for the :`node`.

  • property : A property name, such as token, for a node object.

Returns a single property from a :http:response:`node` object.

Example:

curl http://127.0.0.1:8888/Test_Cluster/nodes/1.2.3.4/token

Output:

 "34478773810192488084662817292306645152"

GET /{cluster_id}/nodes/all/{property}

Retrieve a single property for all nodes.

Path arguments:

  • cluster_id: The ID of a cluster returned from GET /cluster-configs.

  • property : A property name, such as token, for a node object.

Returns a dictionary of \{<node_ip>: <property value>} for all nodes in the cluster.

Example:

 curl http://127.0.0.1:8888/Test_Cluster/nodes/all/token

Output:

{
  "1.2.3.3": "0",
  "1.2.3.4": "34478773810192488084662817292306645152",
  "1.2.3.5": "14981209899913204811852010238019834127"
}

Storage Capacity

GET /{cluster_id}/storage-capacity

Retrieve cluster-wide storage capacity information.

Path arguments: cluster_id: The ID of a cluster returned from GET /cluster-configs.

Returns:

{
  "free_gb": Total free space in the cluster in GB,
  "used_gb": Total c* used space in the cluster in GB,
  "reporting_nodes": How many nodes are included in the first two numbers
}

Example:

 curl http://127.0.0.1:8888/Test_Cluster/storage-capacity

Output:

{
  "free_gb": 627,
  "reporting_nodes": 1,
  "used_gb": 70
}

Diagnostic Tarball

GET /{cluster_id}/diagnostics.tar.gz

Download a diagnostic tarball of cluster data.

Collecting the cluster data and logs can take a few minutes to complete before the download begins.

Path arguments: cluster_id: The ID of a cluster returned from GET /cluster-configs.

Returns: Binary download of the diagnostic tarball.

Example:

 curl http://127.0.0.1:8888/Test_Cluster/diagnostics.tar.gz > Test_Cluster.tar.gz