ping

java -Xmx64m -Xms64m \
-jar KVHOME/lib/kvstore.jar ping [-verbose] [-json] [-shard <shardId>]
-host <hostname> -port <port> or
-helper-hosts  <host:port>[,host:port]*>
-username <user>
-security <security-file-path>

Attempts to contact a store to get status of running services. This utility provides both a concise summary of the health of a store, as well as detailed information about the topology of the store. It can signal a red/yellow/green status, to let you know whether the store is in full health, whether the store has experienced some failures but is operational, or whether the store has critical problems. ping uses the nodes specified by the -helper-hosts or -host/-port arguments to locate topology metadata describing the store. Using that topology, ping contacts all the RNs, SNs, Arbiters, and Admin services associated with a store. You can also indicate a specific shard to return its status information.

Specify the -helper-hosts flag as an alternative to the existing -host and -port flags. If multiple helper hosts are in use, this utility has multiple nodes it can use to make an initial point of contact with the store, and will have a greater chance of success if some nodes of the store are unavailable.

Specify -shard <shardId> to return a subset of information.

Ping Command Line Parameters

The ping utility’s command line parameters are:

Ping Exit Codes

The following exit codes can be returned by this utility. Exit codes can be returned both as a process exit code, and as part of the JSON output.

Name Code Description
EXIT_OK 0 All services in the store could be located and are in a known, good state (for example, RUNNING).
EXIT_OPERATIONAL 1 One or more services in the store could not be reached, or are in an unknown or not usable state. In this case the store should support all data operations across all shards, as well as all administrative operations, but may be in a state of degraded performance. Some action should be taken to find and fix the problem before part of the store becomes unavailable.
EXIT_NO_ADMIN_QUORUM 2 The Admin Service replication group does not have quorum or is not available at all, and it is not possible to execute administrative operations which modify store configuration. The store supports all normal data operations despite the loss of admin quorum, but this state requires immediate attention to restore full store capabilities.
EXIT_NO_SHARD_QUORUM 3 One or more of the shards does not have quorum and either cannot accept write requests, or is completely unavailable. This state requires immediate attention to restore store capabilities. The exit code takes precedence over EXIT_NO_ADMIN_QUORUM, so if this exit code is used, it is possible that the administrative capabilities are also reduced or unavailable.
EXIT_USAGE 100 Illegal ping command usage.
EXIT_TOPOLOGY_FAILURE 101 ping was unable to find a topology in order to operate. This could be a store problem, a network problem, or it could be a usage problem with the parameters passed to ping. For example, the specified -host/-port pair are not part of the store, or none of the hosts specified on -helper-hosts can be contacted.
EXIT_UNEXPECTED 102 The utility has experienced an unexpected error.
EXIT_STATUS_UNKNOWN 103 The store is operational but some Replication Nodes are in unknown state.

Note: Exit codes 1 through 3 may indicate a network connectivity issue that should be checked first before concluding that any services have a problem.

Ping Report Text Output

By default, the ping utility reports store health in human readable format. For example:

Note: Extra line breaks have been added so that the command output fits in the available space.

$ java -Xmx64m -Xms64m -jar <KVHOME>/lib/kvstore.jar ping -host nodeA -port 1310
Pinging components of store mystore based upon topology sequence #108
100 partitions and 3 storage nodes
Time: 2026-05-01 10:37:43 UTC Version:
26.1.14
Shard Status: healthy:1 writable-degraded:0 read-only:0 offline:0 total:1
Admin Status: healthy
Zone [name=MyDC id=zn1 type=PRIMARY allowArbiters=false masterAffinity=false]
RN Status: online:3 read-only:0 offline:0 maxDelayMillis:0 maxCatchupTimeSecs:0
Storage Node [sn1] on nodeA:13100
Zone: [name=MyDC id=zn1 type=PRIMARY allowArbiters=false masterAffinity=false]
Status: RUNNING Ver: 26.1.14 2026-05-01 05:02:01 UTC
Build id: 0ce629097e92 Edition: Enterprise isMasterBalanced:true
        Admin [admin1]         Status: RUNNING,MASTER
        Rep Node [rg1-rn1]     Status: RUNNING,MASTER
        sequenceNumber:227 haPort:13117 available storage size:16 GB storage type:HD
Storage Node [sn2] on nodeB:13200
    Zone: [name=MyDC id=zn1 type=PRIMARY allowArbiters=false masterAffinity=false]
    Status: RUNNING Ver: 26.1.14 2026-05-01 05:02:01 UTC
    Build id: 0ce629097e92
        Admin [admin2]         Status: RUNNING,REPLICA
        Rep Node [rg1-rn2]     Status: RUNNING,REPLICA
            sequenceNumber:227 haPort:13217 available storage size:14 GB storage type:HD delayMillis:0
            catchupTimeSecs:0
Storage Node [sn3] on nodeC:13300
    Zone: [name=MyDC id=zn1 type=PRIMARY allowArbiters=false masterAffinity=false]
    Status: RUNNING Ver: 26.1.14 2026-05-01 05:02:01 UTC
    Build id: 0ce629097e92
        Admin [admin3]         Status: RUNNING,REPLICA
        Rep Node [rg1-rn3]     Status: RUNNING,REPLICA
            sequenceNumber:227 haPort:13317 available storage size:24 GB storage type:HD delayMillis:0
            catchupTimeSecs:0

Ping Report JSON Output

When the -json command line parameter is specified, this utility provides its report in JSON formatting. Note: Extra line breaks have been introduced to allow this output to fit in the available space.

bash-3.2$ java -Xmx64m -Xms64m \
-jar dist/lib/kvstore.jar ping -host node01 \
-port 5000 -json
{
  "operation" : "ping",
  "returnCode" : 5000,
  "description" : "No errors found",
  "returnValue" : {
    "topology" : {
      "storeName" : "orcl",
      "sequenceNumber" : 9,
      "numPartitions" : 0,
      "numStorageNodes" : 2,
      "time" : 1539857069504,
      "version" : "26.1.14"
    },
    "adminStatus" : "healthy",
    "shardStatus" : {
      "healthy" : 1,
      "writable-degraded" : 1,
      "read-only" : 0,
      "offline" : 0,
      "total" : 2
    },
    "zoneStatus" : [ {
      "resourceId" : "zn1",
      "name" : "Atlanta",
      "type" : "PRIMARY",
      "allowArbiters" : false,
      "masterAffinity" : false,
      "rnSummaryStatus" : {
        "online" : 2,
        "offline" : 0,
        "read-only" : 0,
        "hasReplicas" : false
      }
    }, {
      "resourceId" : "zn2",
      "name" : "Boston",
      "type" : "SECONDARY",
      "allowArbiters" : false,
      "masterAffinity" : false,
      "rnSummaryStatus" : {
        "online" : 1,
        "offline" : 0,
        "read-only" : 0,
        "hasReplicas" : true,
        "maxDelayMillis" : 0,
        "maxCatchupTimeSecs" : 0
      }
    } ],
    "snStatus" : [ {
      "resourceId" : "sn1",
      "hostname" : "node01",
      "registryPort" : 5000,
      "zone" : {
        "resourceId" : "zn1",
        "name" : "Atlanta",
        "type" : "PRIMARY",
        "allowArbiters" : false,
        "masterAffinity" : false
      },
      "serviceStatus" : "RUNNING",
      "version" : "26.1.14 2026-05-01 09:33:45 UTC  Build id: a72484b8b33c Edition: Enterprise",
      "adminStatus" : {
        "resourceId" : "admin1",
        "status" : "RUNNING",
        "state" : "MASTER",
        "authoritativeMaster" : true
      },
      "rnStatus" : [ {
        "resourceId" : "rg1-rn1",
        "status" : "RUNNING",
        "requestsEnabled" : "ALL",
        "state" : "MASTER",
        "authoritativeMaster" : true,
        "sequenceNumber" : 23,
        "haPort" : 5002,
        "availableStorageSize" : "3 GB"
      }, {
        "resourceId" : "rg2-rn1",
        "status" : "RUNNING",
        "requestsEnabled" : "ALL",
        "state" : "MASTER",
        "authoritativeMaster" : true,
        "sequenceNumber" : 23,
        "haPort" : 5003,
        "availableStorageSize" : "3 GB"
      } ],
      "anStatus" : [ ]
    }, {
      "resourceId" : "sn2",
      "hostname" : "node02",
      "registryPort" : 6000,
      "zone" : {
        "resourceId" : "zn2",
        "name" : "Boston",
        "type" : "SECONDARY",
        "allowArbiters" : false,
        "masterAffinity" : false
      },
      "serviceStatus" : "RUNNING",
      "version" : "26.1.14 2026-05-01 09:33:45 UTC  Build id: a72484b8b33c Edition: Enterprise",
      "adminStatus" : {
        "resourceId" : "admin2",
        "status" : "RUNNING",
        "state" : "REPLICA"
      },
      "rnStatus" : [ {
        "resourceId" : "rg1-rn2",
        "status" : "RUNNING",
        "requestsEnabled" : "ALL",
        "state" : "REPLICA",
        "sequenceNumber" : 23,
        "haPort" : 6003,
        "availableStorageSize" : "3 GB",
        "networkRestoreUnderway" : false,
        "delayMillis" : 0,
        "catchupTimeSecs" : 0,
        "catchupRateMillisPerMinute" : 0
      } ],
      "anStatus" : [ ]
    } ],
    "exitCode" : 0
  }
}