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:
-
-hostidentifies the name of a specific host in the store. Use this option to check whether the SNA on that particular host can be contacted.If this parameter is specified, then
-portmust also be specified. Further, if the-hostand-portparameters are specified, then the-helper-hostsmust not be specified. -
-portidentifies the listening port for a specific host in the store. Use this parameter only if you are also using the-hostparameter. -
-helper-hostsidentifies a comma-separated list of one or more host:port pairs in the store. Use this parameter to check the health of the entire store.Using the
–helper-hostsparameter precludes specifying the-hostand-portflags.If multiple helper hosts are provided, this utility has multiple nodes it can use to make an initial point of contact with the store, and thus a greater chance of success if some nodes of the store are unavailable. For example:
-helper-hosts hst1:5000,hst2:5100, hst3:5100 -
-usernameis the name of the user that you want to ping the store as. This parameter is required if your store is configured to require authentication. This user should have at leastSYSVIEWaccess to the store. The built-indbadminrole is sufficient. -
-securityis the client security configuration file. This parameter is required if your store is configured to require authentication. For information on the parameters contained in this file, see Configuring SSL in the Java Direct Driver Developer's Guide. For example:oracle.kv.auth.username=clientUID1 oracle.kv.auth.pwdfile.file=/home/nosql/login.pwd oracle.kv.transport=ssl oracle.kv.ssl.trustStore=/home/nosql/client.trustIf you are using Kerberos, then this file would look something like this:
oracle.kv.auth.kerberos.keytab = kerberos/mykeytab oracle.kv.auth.username = krbuser@EXAMPLE.COM oracle.kv.auth.external.mechanism=kerberos oracle.kv.auth.kerberos.services= node01:oraclenosql/node01.example.com@EXAMPLE.COM oracle.kv.auth.kerberos.mutualAuth=false -
-verboseis optional. It causes thepingutility to provide additional information about the utility's current actions. -
-jsoncauses thepingutility to write its output in JSON format. -
-shard <shardId>is optional and returns a subset of status information about the specific shard ID you supply. .For example:
bash-4.1$ java -jar $KVHOME/lib/kvstore.jar ping -host mynode.mycompany.com -port 5000 -shard rg2 Pinging components of store mystore based upon topology sequence #2376 shard rg2 500 partitions and 3 storage nodes Time: 2018-09-28 06:57:10 UTC Version: 18.3.2 Shard Status: healthy Admin Status: healthy Zone [name=myshardzone id=zn1 type=PRIMARY allowArbiters=false masterAffinity=false] RN Status: online:3 offline:0 maxDelayMillis:0 maxCatchupTimeSecs:0 Storage Node [sn10] on nodeA:5000 Zone: [name=myshardzone id=zn1 type=PRIMARY allowArbiters=false masterAffinity=false] Status: RUNNING Ver: 18.3.2 2018-09-17 09:33:45 UTC Build id: a72484b8b33c Edition: Enterprise Rep Node [rg2-rn1] Status: RUNNING,MASTER sequenceNumber:71,166 haPort:5010 available storage size:12 GB Storage Node [sn11] on nodeB:5000 Zone: [name=myshardzone id=zn1 type=PRIMARY allowArbiters=false masterAffinity=false] Status: RUNNING Ver: 18.3.2 2018-09-17 09:33:45 UTC Build id: a72484b8b33c Edition: Enterprise Rep Node [rg2-rn2] Status: RUNNING,REPLICA sequenceNumber:71,166 haPort:5011 available storage size:14 GB delayMillis:0 catchupTimeSecs:0 Storage Node [sn12] on nodeC:5000 Zone: [name=myshardzone id=zn1 type=PRIMARY allowArbiters=false masterAffinity=false] Status: RUNNING Ver: 18.3.2 2018-09-17 09:33:45 UTC Build id: a72484b8b33c Edition: Enterprise Rep Node [rg2-rn3] Status: RUNNING,REPLICA sequenceNumber:71,166 haPort:5012 available storage size:24 GB delayMillis:0 catchupTimeSecs:0
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: 2021-04-08 10:37:43 UTC Version: 21.1.11
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: 21.1.11 2021-03-30 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: 21.1.11 2021-03-30 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: 21.1.11 2021-03-30 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" : "18.3.2"
},
"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" : "18.3.2 2018-09-17 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" : "18.3.2 2018-09-17 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
}
}