Sample: xsadmin utility

With the xsadmin utility, you can format and display textual information about your WebSphere® eXtreme Scale topology. The sample utility provides a method for parsing and discovering current deployment data, and can be used as a foundation for writing custom utilities.

Before you begin

The xsadmin utility is provided as a sample of how you can create custom utilities for your deployment. The xscmd utility is provided as a supported utility for monitoring and administering your environment. For more information, see Administering with the xscmd utility.
For the xsadmin utility to display results, you must have created your data grid topology. Your catalog servers and container servers must be started. See Starting and stopping stand-alone servers for more information.
Verify that the JAVA_HOME environment variable is set to use the runtime environment that installed with the product. If you are using the trial version of the product, you must set the JAVA_HOME environment variable.

About this task

The xsadmin sample utility uses an implementation of Managed Beans (MBeans). This sample monitoring application enables rapidly integrated monitoring capabilities that you can extend by using the interfaces in the com.ibm.websphere.objectgrid.management package. You can look at the source code of the xsadmin sample application in the wxs_home/samples/xsadmin.jar file in a stand-alone installation, or in the wxs_home/xsadmin.jar file in a WebSphere Application Server installation.

You can use the xsadmin sample utility to view the current layout and specific state of the data grid, such as map content. In this example, the layout of the data grid in this task consists of a single ObjectGridA data grid with one MapA map that belongs to the MapSetA map set. This example demonstrates how you can display all active containers within a data grid and print filtered metrics regarding the map size of the MapA map. To see all possible command options, run the xsadmin utility without any arguments or with the -help option.

Procedure

Go to the bin directory.
```
cd wxs_home/bin
```
Run the xsadmin utility.
- To display the online help, run the following command:
```
xsadmin.sh
```
```
xsadmin.bat
```
  You must pass in only one of the listed options for the utility to work. If no -g or -m option is specified, the xsadmin utility prints out information for every grid in the topology.
- To enable statistics for all of the servers, run the following command:
```
xsadmin.sh ObjectGridA -setstatsspec ALL=enabled
```
```
xsadmin.bat ObjectGridA -setstatsspec ALL=enabled
```
- To display all online containers for a grid, run the following command:
```
xsadmin.sh -g ObjectGridA -m MapSetA -containers
```
```
xsadmin.bat -g ObjectGridA -m MapSetA -containers
```
  All container information is displayed. An example of the output follows:
```
Connecting to Catalog service at localhost:1099


*** Show all online containers for grid - ObjectGridA & mapset - MapSetA

Host: 192.168.0.186
Container: server1_C-0, Server:server1, Zone:DefaultZone
Partition Shard Type
        0 Primary

Num containers matching = 1
Total known containers = 1
Total known hosts = 1
```
  Attention: To obtain this information when Transport Layer Security/Secure Sockets Layer (TLS/SSL) is enabled, you must start the catalog and container servers with the JMX service port set. To set the JMX service port, you can either use the -JMXServicePort option on the startOgServer script or you can call the setJMXServicePort method on the ServerProperties interface.
- To connect to the catalog service and display information about MapA, run the following command:
```
xsadmin.sh -g ObjectGridA -m MapSetA -mapsizes -fm MapA
```
```
xsadmin.bat -g ObjectGridA -m MapSetA -mapsizes -fm MapA
```
  The size of the specified map is displayed. An example of the output follows:
```
Connecting to Catalog service at localhost:1099

****Displaying Results for Grid - ObjectGridA, MapSet - MapSetA*****


*** Listing Maps for server1 ***
 Map Name Partition Map Size Used Bytes (B) Shard Type
 MapA     0         0        0              Primary
```
- To connect to the catalog service using a specific JMX port and display information about the MapA map, run the following command:
```
xsadmin.sh -g ObjectGridA -m MapSetA -mapsizes -fm MapA 
		-ch CatalogMachine -p 6645
```
```
xsadmin.bat -g ObjectGridA -m MapSetA -mapsizes -fm MapA 
		-ch CatalogMachine -p 6645
```
  The xsadmin sample utility connects to the MBean server that is running on a catalog server. A catalog server can run as a stand-alone process, WebSphere Application Server process, or embedded within a custom application process. Use the -ch option to specify the catalog service host name, and the -p option to specify the catalog service naming port.
  
  The size of the specified map is displayed. An example of the output follows:
```
Connecting to Catalog service at CatalogMachine:6645

*****Displaying Results for Grid - ObjectGridA, MapSet - MapSetA*****


*** Listing Maps for server1 ***
Map Name: MapA  Partition #: 0  Map Size: 0  Shard Type: Primary
Server Total: 0
```
- To connect to a catalog service hosted in a WebSphere Application Server process, perform the following steps:
  The -dmgr option is required when connecting to a catalog service hosted by any WebSphere Application Server process or cluster of processes. Use the -ch option to specify the host name if not localhost, and the -p option to override the catalog service bootstrap port, which uses the process BOOTSTRAP_ADDRESS. The -p option is only needed if the BOOTSTRAP_ADDRESS is not set to the default of 9809.
  
  Note: The stand-alone version of WebSphere eXtreme Scale cannot be used to connect to a catalog service hosted by a WebSphere Application Server process. Use the xsadmin that is script included in the was_root/bin directory, which is available when the installing WebSphere eXtreme Scale on WebSphere Application Server or WebSphere Application Server Network Deployment.
  1. Navigate to the WebSphere Application Server bin directory:
```
cd was_root/bin
```
  2. Launch the xsadmin utility using the following command:
```
 xsadmin.sh -g ObjectGridA -m MapSetA -mapsizes -fm MapA -dmgr
```
```
xsadmin.bat -g ObjectGridA -m MapSetA -mapsizes -fm MapA -dmgr
```
  The size of the specified map is displayed.
```
Connecting to Catalog service at localhost:9809

****Displaying Results for Grid - ObjectGridA, MapSet - MapSetA*****


*** Listing Maps for server1 ***
Map Name: MapA  Partition #: 0  Map Size: 0  Shard Type: Primary
Server Total: 0
```
- To display the configured and runtime placement of your configuration, run one of the following commands:
```
xsadmin -placementStatus
xsadmin -placementStatus -g myOG -m myMapSet
xsadmin -placementStatus -m myMapSet
xsadmin -placementStatus -g myOG
```
  You can scope the command to display placement information for the entire configuration, a single data grid, a single map set, or a combination of a data grid and map set. An example of the output follows:
```
***********Printing Placement Status for Grid - Grid, MapSet - mapSet**************

<objectGrid name="Grid" mapSetName="mapSet">
  <configuration>
    <attribute name="placementStrategy" value="FIXED_PARTITIONS"/>
    <attribute name="numInitialContainers" value="3"/>
    <attribute name="minSyncReplicas" value="0"/>
    <attribute name="developmentMode" value="true"/>
  </configuration>
  <runtime>
    <attribute name="numContainers" value="3"/>
    <attribute name="numMachines" value="1"/>
    <attribute name="numOutstandingWorkItems" value="0"/>
  </runtime>
</objectGrid>
```