Configuring and Using Statistics

You configure statistics and statistics archiving in gemfire.properties

Configure Statistics

In this procedure it is assumed that you understand Basic Configuration and Programming.
  1. Configure gemfire.properties for the statistics monitoring and archival that you need:
    1. Enable statistics gathering for the distributed system. This is required for all other statistics activities:
      statistic-sampling-enabled=true
      Note: Statistics sampling at the default sample rate (1000 milliseconds) does not impact system performance and is recommended in production environments for troubleshooting.
    2. Change the statistics sample rate as needed. Example:
      statistic-sampling-enabled=true
      statistic-sample-rate=2000
    3. To archive the statistics to disk, enable that and set any file or disk space limits that you need. Example:
      statistic-sampling-enabled=true
      statistic-archive-file=myStatisticsArchiveFile.gfs
      archive-file-size-limit=100
      archive-disk-space-limit=1000
    4. If you need time-based statistics, enable that. Time-based statistics require statistics sampling and archival. Example:
      statistic-sampling-enabled=true
      statistic-archive-file=myStatisticsArchiveFile.gfs
      enable-time-statistics=true
      Note: Time-based statistics can impact system performance and is not recommended for production environments.
  2. Enable transient region and entry statistics gathering on the regions where you need it. Expiration requires statistics. Example:
    <region name="myRegion" refid="REPLICATE">
    	<region-attributes statistics-enabled="true">
    	</region-attributes>
    </region>
    Note: Region and entry statistics are not archived and can only be accessed through the API. As needed, retrieve region and entry statistics through the getStatistics methods of the Region and Region.Entry objects. Example:
    out.println("Current Region:\n\t" + this.currRegion.getName());
    RegionAttributes attrs = this.currRegion.getAttributes();
    if (attrs.getStatisticsEnabled()) {
    	CacheStatistics stats = this.currRegion.getStatistics();
    	out.println("Stats:\n\tHitCount is " + stats.getHitCount() +
    		"\n\tMissCount is " + stats.getMissCount() +
    		"\n\tLastAccessedTime is " + stats.getLastAccessedTime() +
    		"\n\tLastModifiedTime is " + stats.getLastModifiedTime());
    }
  3. Create and manage any custom statistics that you need through the cache.xml and the API. Example:
    // Create custom statistics
    <?xml version="1.0" encoding="UTF-8"?>
      <!DOCTYPE statistics PUBLIC
        "-//GemStone Systems, Inc.//GemFire Statistics Type//EN"
        "http://www.gemstone.com/dtd/statisticsType.dtd">
      <statistics>
        <type name="StatSampler">
          <description>Stats on the statistic sampler.</description>
          <stat name="sampleCount" storage="int" counter="true">
            <description>Total number of samples taken by this sampler.</description>
            <unit>samples</unit>
          </stat>
          <stat name="sampleTime" storage="long" counter="true">
            <description>Total amount of time spent taking samples.</description>
            <unit>milliseconds</unit>
          </stat>
        </type>
      </statistics>
    // Update custom stats through the API
    this.samplerStats.incInt(this.sampleCountId, 1);
    this.samplerStats.incLong(this.sampleTimeId, nanosSpentWorking / 1000000);
  4. Access archived statistics through these utilities:

Controlling the Size of Archive Files

You can specify limits on the archive files for statistics. These are the areas of control:
  • Archive File Growth Rate.
    • The gemfire.properties statistic-sample-rate controls how often samples are taken, which affects the speed at which the archive file grows.
    • The gemfire.properties statistic-archive-file controls whether the statistics files are compressed. If you give the file name a .gz suffix, it is compressed, thereby taking up less disk space.
  • Maximum Size of a Single Archive File. If the value of the gemfire.properties archive-file-size-limit is greater than zero, a new archive is started when the size of the current archive exceeds the limit. Only one archive can be active at a time.
    Note: If you modify the value of archive-file-size-limit while the distributed system is running, the new value does not take effect until the current archive becomes inactive (that is, when a new archive is started).
  • Maximum Size of All Archive Files. The gemfire.properties archive-disk-space-limit controls the maximum size of all inactive archive files combined. By default, the limit is set to 0, meaning that archive space is unlimited. Whenever an archive becomes inactive or when the archive file is renamed, the combined size of the inactive files is calculated. If the size exceeds the archive-disk-space-limit, the inactive archive with the oldest modification time is deleted. This continues until the combined size is less than the limit. If archive-disk-space-limit is less than or equal to archive-file-size-limit, when the active archive is made inactive due to its size, it is immediately deleted.
    Note: If you modify the value of archive-disk-space-limit while the distributed system is running, the new value does not take effect until the current archive becomes inactive.

Examining Archived Statistics

When sampling and archiving are enabled, you can study statistics in archive files through VSD or by using the gfsh show metrics command. You can use VSD to examine archived historical data and to help diagnose performance problems. The VSD tool reads the sampled statistics and produces graphical displays for analysis.