Program guide > Programming for administrative tasks



Monitor with the statistics API

The Statistics API is the direct interface to the internal statistics tree. Statistics are disabled by default, but can be enabled by setting a StatsSpec interface. A StatsSpec interface defines how WebSphere eXtreme Scale should monitor statistics.

Use the local StatsAccessor API to query data and access statistics on any ObjectGrid instance that is in the same Java™ virtual machine (JVM) as the running code. For more information about the specific interfaces, see the API documentation. Use the following steps to enable monitoring of the internal statistics tree.


Procedure

  1. Retrieve the StatsAccessor object. The StatsAccessor interface follows the singleton pattern. So, apart from problems related to the classloader, one StatsAccessor instance should exist for each JVM. This class serves as the main interface for all local statistics operations. The following code is an example of how to retrieve the accessor class. Call this operation before any other ObjectGrid calls.

    public class LocalClient
    {
    
       public static void main(String[] args) {
    
          // retrieve a handle to the StatsAccessor
          StatsAccessor accessor = StatsAccessorFactory.getStatsAccessor();
    
       }
    
    }
    

  2. Set the data grid StatsSpec interface. Set this JVM to collect all statistics at the ObjectGrid level only. You must ensure that an application enables all statistics that might be needed before you begin any transactions. The following example sets the StatsSpec interface using both a static constant field and using a spec String. Using a static constant field is simpler because the field has already defined the specification. However, by using a spec String, you can enable any combination of statistics that are required.

    public static void main(String[] args) {
    
          // retrieve a handle to the StatsAccessor
          StatsAccessor accessor = StatsAccessorFactory.getStatsAccessor();
    
          // Set the spec via the static field
          StatsSpec spec = new StatsSpec(StatsSpec.OG_ALL);
          accessor.setStatsSpec(spec);
    
          // Set the spec via the spec String
          StatsSpec spec = new StatsSpec("og.all=enabled");
          accessor.setStatsSpec(spec);
    
    }
    

  3. Send transactions to the grid to force data to be collected for monitoring.

    To collect useful data for statistics, send transactions to the data grid. The following code excerpt inserts a record into MapA, which is in ObjectGridA. Because the statistics are at the ObjectGrid level, any map within the ObjectGrid yields the same results.

    public static void main(String[] args) {
    
          // retrieve a handle to the StatsAccessor
          StatsAccessor accessor = StatsAccessorFactory.getStatsAccessor();
    
          // Set the spec via the static field
          StatsSpec spec = new StatsSpec(StatsSpec.OG_ALL);
          accessor.setStatsSpec(spec);
    
          ObjectGridManager manager = 
                    ObjectGridmanagerFactory.getObjectGridManager();
          ObjectGrid grid = manager.getObjectGrid("ObjectGridA");
          Session session = grid.getSession();
          Map map = session.getMap("MapA");
    
          // Drive insert
          session.begin();
          map.insert("SomeKey", "SomeValue");
          session.commit();
    }
    

  4. Query a StatsFact by using the StatsAccessor API. Every statistics path is associated with a StatsFact interface. The StatsFact interface is a generic placeholder that is used to organize and contain a StatsModule object. Before you can access the actual statistics module, the StatsFact object must be retrieved.

    public static void main(String[] args)
    {
    
          // retrieve a handle to the StatsAccessor
          StatsAccessor accessor = StatsAccessorFactory.getStatsAccessor();
    
          // Set the spec via the static field
          StatsSpec spec = new StatsSpec(StatsSpec.OG_ALL);
          accessor.setStatsSpec(spec);
    
          ObjectGridManager manager = 
                    ObjectGridManagerFactory.getObjectGridManager();
          ObjectGrid grid = manager.getObjectGrid("ObjectGridA");
          Session session = grid.getSession();
          Map map = session.getMap("MapA");
    
          // Drive insert
          session.begin();
          map.insert("SomeKey", "SomeValue");
          session.commit();
    
          // Retrieve StatsFact
    
          StatsFact fact = accessor.getStatsFact(new String[] {"EmployeeGrid"}, 
                    StatsModule.MODULE_TYPE_OBJECT_GRID);
    
    }
    

  5. Interact with the StatsModule object. The StatsModule object is contained within the StatsFact interface. You can obtain a reference to the module by using the StatsFact interface. Since the StatsFact interface is a generic interface, cast the returned module to the expected StatsModule type. Because this task collects eXtreme Scale statistics, the returned StatsModule object is cast to an OGStatsModule type. After the module is cast, you have access to all of the available statistics.

    public static void main(String[] args) {
    
          // retrieve a handle to the StatsAccessor
          StatsAccessor accessor = StatsAccessorFactory.getStatsAccessor();
    
          // Set the spec via the static field
          StatsSpec spec = new StatsSpec(StatsSpec.OG_ALL);
          accessor.setStatsSpec(spec);
    
          ObjectGridManager manager = 
                    ObjectGridmanagerFactory.getObjectGridManager();
          ObjectGrid grid = manager.getObjectGrid("ObjectGridA");
          Session session = grid.getSession();
          Map map = session.getMap("MapA");
    
          // Drive insert
          session.begin();
          map.insert("SomeKey", "SomeValue");
          session.commit();
    
          // Retrieve StatsFact
          StatsFact fact = accessor.getStatsFact(new String[] {"EmployeeGrid"}, 
                    StatsModule.MODULE_TYPE_OBJECT_GRID);
    
          // Retrieve module and time
          OGStatsModule module = (OGStatsModule)fact.getStatsModule();
          ActiveTimeStatistic timeStat = 
                    module.getTransactionTime("Default", true);
          double time = timeStat.getMeanTime(); 
    
    }
    


Parent topic:

Program for administrative tasks


Related concepts

Embedded server API


Related tasks

Use the embedded server API to start and stop servers

Monitor with WAS PMI