Using gfsh

This topic describes ways to use the gfsh command-line interface to manage VMware Tanzu GemFire for Tanzu Application Service.

gfsh Command Restrictions

Developers may invoke all gfsh commands. Given credentials with sufficient permissions, those gfsh commands will be invoked. However, not all gfsh commands are supported. An invocation of an unsupported command may lead to incorrect results. Those results range from ineffective results to inconsistent region entries. Do not use these listed gfsh commands; each has an explanation why it must not be used.

The following gfsh start commands will bring up members contrary to the configured plan. Their configuration will be wrong, and their existence is likely to contribute to data loss. Since they are not part of the configured plan, any upgrade will not include them, and if they were to stop or crash, the BOSH Director will not restart them.

gfsh start locator
gfsh start server

The following gfsh cluster stop commands will temporarily stop the member or cluster. However, the BOSH Director will notice that members are not running and restart them. This renders the following commands ineffective:

gfsh stop locator
gfsh stop server
gfsh shutdown

The following Lucene-related commands are not supported:

gfsh create lucene index
gfsh describe lucene index
gfsh destroy lucene index
gfsh list lucene indexes
gfsh search lucene

The following JNDI binding-related commands are not supported:

gfsh create jndi-binding
gfsh describe jndi-binding
gfsh destroy jndi-binding
gfsh list jndi-binding

The following configure command will instill configuration contrary to the already-configured plan. Since it is not part of the configured plan, any upgrade will not include it. Therefore, do not use the following command:

gfsh configure pdx

The creation of a gateway receiver will never be appropriate for any situation. The GemFire for Tanzu Application Service cluster will already have gateway receivers, and there is no situation in which the cluster can benefit from creating more. Therefore, do not use the following command:

gfsh create gateway receiver

Do Not Export from a Tanzu GemFire Cluster to a GemFire for Tanzu Application Service Cluster

While the expectation is that configuration and data can be exported from a Tanzu GemFire cluster and then imported into a GemFire for Tanzu Application Service cluster, this does not work. Using export and import commands will not have the desired effect of migration from one cluster to another. The import of cluster configuration requires a state that cannot be provided by a GemFire for Tanzu Application Service cluster. The GemFire for Tanzu Application Service cluster will already have its configuration, and upon restart or upgrade, that same configuration will be used. Given that the configuration cannot be imported, data import is problematic. Therefore, do not use the following command:

gfsh import cluster-configuration
gfsh import data

Create Regions

After connecting with gfsh with a role that is able to manage a cluster’s data, you can define a new cache region.

The following command creates a partitioned region with a single redundant copy:

gfsh>create region --name=my-cache-region --type=PARTITION_REDUNDANT_HEAP_LRU
     Member      | Status
---------------- | -------------------------------------------------------
cacheserver-z2-1 | Region "/my-cache-region" created on "cacheserver-z2-1"
cacheserver-z3-2 | Region "/my-cache-region" created on "cacheserver-z3-2"
cacheserver-z1-0 | Region "/my-cache-region" created on "cacheserver-z1-0"
cacheserver-z1-3 | Region "/my-cache-region" created on "cacheserver-z1-3"

See Region Design for guidelines about choosing a region type.

You can test the newly created region by writing and reading values with gfsh:

gfsh>put --region=/my-cache-region --key=test --value=thevalue
Result      : true
Key Class   : java.lang.String
Key         : test
Value Class : java.lang.String
Old Value   : NULL


gfsh>get --region=/my-cache-region --key=test
Result      : true
Key Class   : java.lang.String
Key         : test
Value Class : java.lang.String
Value       : thevalue

In practice, you should perform these get/put operations from a deployed app. To do this, you must bind the service instance to these apps.

Working with Disk Stores

Persistent regions and regions that overflow upon eviction use disk stores. Use gfsh to create or destroy a disk store.

Create a Disk Store

To create a disk store for use with a persistent or overflow type of region:

Use the directions in Connect with gfsh over HTTPS to connect to the GemFire for Tanzu Application Service service instance with a role that is able to manage a cluster’s data.
Create the disk store with a gfsh command of the form:
```
create disk-store --name=<name-of-disk-store>
 --dir=<relative/path/to/diskstore/directory>
```
Specify a relative path for the disk store location. That relative path will be created within /var/vcap/store/gemfire-server/. For more details about further options, see the gfsh create disk-store command in the Tanzu GemFire documentation.

Destroy a Disk Store

To destroy a disk store:

Use the directions in Connect with gfsh over HTTPS to connect to the GemFire for Tanzu Application Service service instance with a role that is able to manage a cluster’s data.
Destroy the disk store with a gfsh command of the form:
```
destroy disk-store --name=<name-of-disk-store>
```
For more details about further options, see the gfsh destroy disk-store command in the Tanzu GemFire documentation.

Use the Pulse Dashboard

You can access the Pulse dashboard for a service instance in a web browser using the Pulse URL specified in the service key you created following the directions in Create Service Keys.

Access Service Instance Metrics

To access service metrics, you must have Enable Plan selected under Service Plan Access on the page where you configure your tile properties. (For details, see the Configure Service Plans page.)

GemFire for Tanzu Application Service service instances output metrics to the Loggregator Firehose. You can use the Firehose plugin to view metrics output on the cf CLI directly. For more information about using the Firehose plugin, see Installing the Loggregator Firehose Plugin for cf CLI in the VMware Tanzu Application Service for VMs documentation.

You can also connect the output to a Firehose nozzle. Nozzles are programs that consume data from the Loggregator Firehose. For example, to connect the output to the nozzle for Datadog, see Datadog Firehose Nozzle on GitHub.

GemFire for Tanzu Application Service supports metrics for the whole cluster and metrics for each member. Each server and locator in the cluster outputs metrics.

Service Instance (Cluster-wide) Metrics

serviceinstance.MemberCount: the number of VMs in the cluster
serviceinstance.TotalHeapSize: the total MBs of heap available in the cluster
serviceinstance.UsedHeapSize: the total MBs of heap in use in the cluster

Member (per-VM) Metrics

member.GarbageCollectionCount: the number of JVM garbage collections that have occurred on this member since startup
member.CpuUsage: the percentage of CPU time used by the cluster process
member.GetsAvgLatency: the avg latency of GET requests to this cluster member
member.PutsAvgLatency: the avg latency of PUT requests to this cluster member
member.JVMPauses: the number of JVM pauses that have occurred on this member since startup
member.FileDescriptorLimit: the number of files this member allows to be open at once
member.TotalFileDescriptorOpen: the number of files this member has open now
member.FileDescriptorRemaining: the number of files that this member could open before hitting its limit
member.TotalHeapSize: the number of megabytes allocated for the heap
member.UsedHeapSize: the number of megabytes currently in use for the heap
member.UnusedHeapSizePercentage: the percentage of the total heap size that is not currently being used

Access Service Broker Metrics

Service broker metrics are on by default and can be accessed through the Loggregator Firehose CLI plugin. For more information, see Installing the Loggregator Firehose Plugin for cf CLI in the VMware Tanzu Application Service for VMs documentation. For more information about broker metrics, see Configure Service Metrics in Operating an On-Demand Broker in the On-Demand Services SDK for VMware Tanzu documentation.

Export gfsh Logs

You can retrieve logs and .gfs stats files from your GemFire for Tanzu Application Service service instances using the export logs command in gfsh.

Use the Connect with gfsh over HTTPS procedure to connect to the service instance for which you want to see logs. Use a role that can read cluster information.

Run export logs. If you see a message of the following form, your logs exceed an expanded size of 100 megabytes, and they were not exported:

Estimated exported logs expanded file size = 289927115, file-size-limit = 104857600. To deactivate exported logs file size check use option "--file-size-limit=0".

To export in this case, use the `gfsh` command:

export logs --file-size-limit=0

Find the ZIP file in the directory where you started gfsh. This file contains a folder for each member of the cluster. The member folder contains the associated log files and stats files for that member.

For more information about the gfsh export logs command, see export logs in the VMware GemFire documentation.

Deploy or Redeploy an App JAR File to the Servers

You can deploy or redeploy an app JAR file to the servers in the cluster.

Deploy an App JAR File to the Servers

To initially deploy an app JAR file after connecting within gfsh using credentials that can manage the cluster, run the following gfsh command:

deploy --jar=PATH-TO-JAR/FILENAME.jar

For example:

gfsh>deploy --jar=working-directory/myJar.jar

Redeploy an App JAR File to the Servers

To redeploy an app JAR file after connecting within gfsh using credentials that can manage the cluster:

Deploy the updated JAR file by running the following gfsh command:

deploy --jar=PATH-TO-UPDATED-JAR/FILENAME.jar

For example:

gfsh>deploy --jar=newer-jars/myJar.jar

Restart the cluster and load the updated JAR file by running the following cf CLI command:

cf update-service SERVICE-INSTANCE-NAME -c '{"restart": true}'

For example:

$ cf update-service my-service-instance -c '{"restart": true}'

Scripting Common Operations

You can place gfsh commands in files to provide a way to script common maintenance operations. Scripting operations reduces errors that might occur when manually entering commands, and can be used for running test cases and in deployment automation.

Running a gfsh Script

The gfsh run command invokes the gfsh commands that are in a file. Start up the gfsh command line interface first, and then run the command:

gfsh>run --file=thecommands.gfsh

To see the gfsh run options:

gfsh>help run

File specification can be a relative or absolute path and file name. Scripted commands are not interactive, and any command that would have prompted for input will instead use default values.

To eliminate placing cleartext passwords within a script, run gfsh and connect to the cluster prior to running a script with the gfsh run command. The password will appear on the command line, but it will not appear in the file that logs and captures gfsh commands.

Example Scripts

Tightly focussed scripts will ease cluster maintenance. Most of these scripts will do cluster management operations, so connect to the cluster with a role that is able to manage both the cluster and the data.

Creating the regions hosted on the servers is a common operation. The following example gfsh script contents creates two regions:

create region --name=sessions --type=PARTITION_REDUNDANT
create region --name=customers --type=REPLICATE

The following example gfsh script contents deploys a app JAR file to the cluster servers:

deploy --jar=/path/to/app-classes.jar

The following example gfsh script contents creates the disk store needed for persistent regions:

create disk-store --name=all-regions-disk --dir=regions