This is an automated email from the ASF dual-hosted git repository.
kmiller pushed a commit to branch develop
in repository https://gitbox.apache.org/repos/asf/geode.git
The following commit(s) were added to refs/heads/develop by this push:
new 4ec2878 GEODE-5350: User Guide: Specifying that 'statistics-enabled'
parameter for region (#2081)
4ec2878 is described below
commit 4ec28788d76666ca9e2543720c77cd12243b5ace
Author: Nick Vallely <[email protected]>
AuthorDate: Mon Jul 2 17:13:58 2018 -0700
GEODE-5350: User Guide: Specifying that 'statistics-enabled' parameter for
region (#2081)
* Specifying that 'statistics-enabled' parameter is required at the REGION
level to differentiate between 'statistics' at the Server or Cluster level,
which if enabled will NOT allow Expiration functionality.
* Format corrections
* Specifying that 'statistics-enabled' parameter is required at the REGION
level to differentiate between 'statistics' at the Server or Cluster level,
which if enabled will NOT allow Expiration functionality.
* Specifying that 'statistics-enabled' parameter is required at the REGION
level to differentiate between 'statistics' at the Server or Cluster level,
which if enabled will NOT allow Expiration functionality.
---
.../configuring_data_expiration.html.md.erb | 7 +-
.../statistics/chapter_overview.html.md.erb | 2 +-
.../statistics/how_statistics_work.html.md.erb | 5 +-
.../statistics/setting_up_statistics.html.md.erb | 191 +++++++++++----------
.../gfsh/command-pages/alter.html.md.erb | 6 +-
.../gfsh/command-pages/start.html.md.erb | 4 +-
6 files changed, 116 insertions(+), 99 deletions(-)
diff --git
a/geode-docs/developing/expiration/configuring_data_expiration.html.md.erb
b/geode-docs/developing/expiration/configuring_data_expiration.html.md.erb
index 6c19b3f..b153b0f 100644
--- a/geode-docs/developing/expiration/configuring_data_expiration.html.md.erb
+++ b/geode-docs/developing/expiration/configuring_data_expiration.html.md.erb
@@ -21,14 +21,13 @@ limitations under the License.
Configure the type of expiration and the expiration action to use.
-<a
id="configuring_data_expiration__section_ADB8302125624E01A808EA5E4FF79A5C"></a>
+- Expiration actions require setting the region attribute of
`statistics-enabled` to `true`. This can be done in the region element of a
`cache.xml` file, the `gfsh` command line, or through the API.
-- Set the region's `statistics-enabled` attribute to true.
-
- The statistics used for expiration are available directly to the
application through the `CacheStatistics` object returned by the `Region` and
`Region.Entry` `getStatistics` methods. The `CacheStatistics` object also
provides a method for resetting the statistics counters.
- Set the expiration attributes by expiration type, with the max times and
expiration actions. See the region attributes listings for
`entry-time-to-live`, `entry-idle-time`, `region-time-to-live`, and
`region-idle-time` in
[<region-attributes>](../../reference/topics/cache_xml.html#region-attributes).
+The statistics used for expiration are available directly to the application
through the `CacheStatistics` object returned by the `Region` and
`Region.Entry` `getStatistics` methods. The `CacheStatistics` object also
provides a method for resetting the statistics counters.
+
**For partitioned regions:**
- On a partitioned region, expiration is supported only for the region's
entries, not for the region itself. Region-wide expiration attributes, such as
`region-time-to-live` and `region-idle-time` do not apply to the data items in
partitioned regions.
diff --git a/geode-docs/managing/statistics/chapter_overview.html.md.erb
b/geode-docs/managing/statistics/chapter_overview.html.md.erb
index 650b852..22eaed7 100644
--- a/geode-docs/managing/statistics/chapter_overview.html.md.erb
+++ b/geode-docs/managing/statistics/chapter_overview.html.md.erb
@@ -35,7 +35,7 @@ Every application and server in a distributed system can
access statistical data
- **[Configuring and Using Statistics](setting_up_statistics.html)**
- You configure statistics and statistics archiving in gemfire.properties
+ You configure statistics and statistics archiving in several different
ways.
- **[Viewing Archived Statistics](viewing_statistics.html)**
diff --git a/geode-docs/managing/statistics/how_statistics_work.html.md.erb
b/geode-docs/managing/statistics/how_statistics_work.html.md.erb
index 44618e7..2ace4e0 100644
--- a/geode-docs/managing/statistics/how_statistics_work.html.md.erb
+++ b/geode-docs/managing/statistics/how_statistics_work.html.md.erb
@@ -18,11 +18,12 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
-
Each application or cache server that joins the distributed system can collect
and archive statistical data for analyzing system performance.
+<%=vars.product_name%> statistics can be enabled for a cluster, for an
application, for a server, or for a region. Statistics gathered for a cluster,
an application, or a cache server are saved to a file and can be archived,
whereas region statistics are transient and accessible only through the API.
+
<a id="how_statistics_work__section_C12B3CDFF04743688BA5F8FB374899D5"></a>
-Set the configuration attributes that control statistics collection in `gfsh`
or in the `gemfire.properties` configuration file. You can also collect your
own application defined statistics.
+Set the configuration attributes that control cluster, application, or cache
statistics collection in `gfsh` or in the `gemfire.properties` configuration
file. You can also collect your own application defined statistics.
When Java applications and servers join a distributed system, they can be
configured via the cluster configuration service to enable statistics sampling
and whether to archive the statistics that are gathered.
diff --git a/geode-docs/managing/statistics/setting_up_statistics.html.md.erb
b/geode-docs/managing/statistics/setting_up_statistics.html.md.erb
index 8467eed..59f27aa 100644
--- a/geode-docs/managing/statistics/setting_up_statistics.html.md.erb
+++ b/geode-docs/managing/statistics/setting_up_statistics.html.md.erb
@@ -19,125 +19,141 @@ See the License for the specific language governing
permissions and
limitations under the License.
-->
-You configure statistics and statistics archiving in gemfire.properties
+You can configure statistics and statistics archiving in several ways.
-## <a id="setting_up_statistics__section_215BB4074BD64834BAADA87BE84C34DE"
class="no-quick-link"></a>Configure Statistics
+## <a id="setting_up_statistics__section_215BB4074BD64834BAADA87BE84C34DE"
class="no-quick-link"></a>Configure Cluster or Server Statistics
In this procedure it is assumed that you understand [Basic Configuration and
Programming](../../basic_config/book_intro.html).
-1. In gfsh, start your locator running the cluster configuration service
(`--enable-cluster-configuration=true`).
-2. Execute the following command to modify the cluster's configuration:
+Execute the following commands to modify the cluster's configuration and
enable cluster or server statistics.
+
+``` pre
+gfsh>start locator --name=l1 --enable-cluster-configuration=true
+gfsh>alter runtime --enable-statistics=true
-–statistic-archive-file=myStatisticsArchiveFile.gfs
+```
+
+Note that an empty value of `statistics-archive-file` still calculates
statistics, but they are not archived to a file.
+
+You can also configure sample rate and the filename of your statistic archive
files. See [alter
runtime](../../tools_modules/gfsh/command-pages/alter.html#topic_7E6B7E1B972D4F418CB45354D1089C2B)
for more command options.
+
+Alternately, if you are not using the cluster configuration service, configure
`gemfire.properties` for the statistics monitoring and archiving that you need:
+
+1. Enable statistics gathering for the distributed system. This is required
for all other statistics activities:
``` pre
- gfsh>alter runtime --enable-statistics=true
+ statistic-sampling-enabled=true
+ statistic-archive-file=myStatisticsArchiveFile.gfs
```
- You can also configure sample rate and the filename of your statistic
archive files. See [alter
runtime](../../tools_modules/gfsh/command-pages/alter.html#topic_7E6B7E1B972D4F418CB45354D1089C2B)
for more command options.
+ **Note:**
+ Statistics sampling at the default sample rate (1000 milliseconds) does
not impact system performance and is recommended in production environments for
troubleshooting.
-3. Alternately, if you are not using the cluster configuration service,
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:
+2. Change the statistics sample rate as needed. Example:
- ``` pre
- statistic-sampling-enabled=true
- ```
+ ``` pre
+ statistic-sampling-enabled=true
+ statistic-archive-file=myStatisticsArchiveFile.gfs
+ statistic-sample-rate=2000
+ ```
- **Note:**
- Statistics sampling at the default sample rate (1000 milliseconds)
does not impact system performance and is recommended in production
environments for troubleshooting.
+3. To archive the statistics to disk, enable that and set any file or disk
space limits that you need. Example:
- 2. Change the statistics sample rate as needed. Example:
+ ``` pre
+ statistic-sampling-enabled=true
+ statistic-archive-file=myStatisticsArchiveFile.gfs
+ archive-file-size-limit=100
+ archive-disk-space-limit=1000
+ ```
- ``` pre
- statistic-sampling-enabled=true
- statistic-sample-rate=2000
- ```
+4. If you need time-based statistics, enable that. Time-based statistics
require statistics sampling and archiving. Example:
- 3. To archive the statistics to disk, enable that and set any file or
disk space limits that you need. Example:
+ ``` pre
+ statistic-sampling-enabled=true
+ statistic-archive-file=myStatisticsArchiveFile.gfs
+ enable-time-statistics=true
+ ```
- ``` pre
- statistic-sampling-enabled=true
- statistic-archive-file=myStatisticsArchiveFile.gfs
- archive-file-size-limit=100
- archive-disk-space-limit=1000
- ```
+ **Note:**
+ Time-based statistics can impact system performance and are not
recommended for production environments.
- 4. If you need time-based statistics, enable that. Time-based statistics
require statistics sampling and archival. Example:
+If these statistics are on, you are able to access archived statistics through
the `gfsh show metrics` command.
- ``` pre
- 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.
+## <a id="setting_up_statistics__section_region_level"
class="no-quick-link"></a>Configure Transient Region and Entry Statistics
-4. Enable transient region and entry statistics gathering on the regions
where you need it. Expiration requires statistics.
+Enable transient region and entry statistics gathering on the regions where
you need them. This configuration is distinct from the enabling of cluster or
server statistics.
- gfsh example:
+**gfsh example:**
- ``` pre
- gfsh>create region --name=myRegion --type=REPLICATE
--enable-statistics=true
- ```
+``` pre
+gfsh>create region --name=myRegion --type=REPLICATE --enable-statistics=true
+```
- Example:
+**cache.xml example:**
- ``` pre
- <region name="myRegion" refid="REPLICATE">
- <region-attributes statistics-enabled="true">
- </region-attributes>
- </region>
- ```
+``` pre
+<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:
+**API example:**
- ``` pre
- 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());
- }
+**Note:**
+Region and entry statistics are not archived and can be accessed only through
the API. As needed, retrieve region and entry statistics through the
`getStatistics` methods of the `Region` and `Region.Entry` objects. Example:
- ```
+``` pre
+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());
+ }
+```
-5. Create and manage any custom statistics that you need through the
`cache.xml` and the API. Example:
+## <a id="setting_up_statistics__section_custom_level"
class="no-quick-link"></a> Configure Custom Statistics
- ``` pre
- // Create custom statistics
- <?xml version="1.0" encoding="UTF-8"?>
- <!DOCTYPE statistics PUBLIC
- "-//Example Systems, Inc.//Example Statistics Type//EN"
- "http://www.example.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>
- ```
+Create and manage any custom statistics that you need through `cache.xml` and
the API.
- ``` pre
- // Update custom stats through the API
- this.samplerStats.incInt(this.sampleCountId, 1);
- this.samplerStats.incLong(this.sampleTimeId, nanosSpentWorking / 1000000);
- ```
+**cache/cluster.xml example:**
+
+``` pre
+// Create custom statistics
+<?xml version="1.0" encoding="UTF-8"?>
+ <!DOCTYPE statistics PUBLIC
+ "-//Example Systems, Inc.//Example Statistics Type//EN"
+ "http://www.example.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>
+```
+
+**API example:**
+
+``` pre
+// Update custom stats through the API
+this.samplerStats.incInt(this.sampleCountId, 1);
+this.samplerStats.incLong(this.sampleTimeId, nanosSpentWorking / 1000000);
+```
-6. Access archived statistics through the `gfsh show metrics` command.
## <a id="setting_up_statistics__section_D511BB61B27A44749E2012B066A5C906"
class="no-quick-link"></a>Controlling the Size of Archive Files
-You can specify limits on the archive files for statistics using `alter
runtime` command. These are the areas of control:
+You can specify limits on the archive files for statistics using the gfsh
`alter runtime` command. These are the areas of control:
- **Archive File Growth Rate**.
- The `--statistic-sample-rate` parameter controls how often samples are
taken, which affects the speed at which the archive file grows.
@@ -147,5 +163,6 @@ You can specify limits on the archive files for statistics
using `alter runtime`
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 `--archive-disk-space-limit`
parameter 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 [...]
- **Note:**
+
+**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.
diff --git a/geode-docs/tools_modules/gfsh/command-pages/alter.html.md.erb
b/geode-docs/tools_modules/gfsh/command-pages/alter.html.md.erb
index d008c15..413da0f 100644
--- a/geode-docs/tools_modules/gfsh/command-pages/alter.html.md.erb
+++ b/geode-docs/tools_modules/gfsh/command-pages/alter.html.md.erb
@@ -127,7 +127,7 @@ The three required options, `--name`, `--region`, and
`--disk-dirs`, identify th
</tr>
<tr class="even">
<td><span class="keyword parmname">\-\-enable-statistics</span></td>
-<td>Enables statistics for the region. Valid values are true or false. If the
parameter is specified without a value, the value of true is used.</td>
+<td>Enables statistics for the region specified by the <code>--region</code>
option. Valid values are true or false. If the parameter is specified without a
value, the value of true is used.</td>
</tr>
<tr class="odd">
<td><span class="keyword parmname">\-\-initial-capacity</span></td>
@@ -500,7 +500,7 @@ Valid values are: `ALL`, `TRACE`, `DEBUG`, `INFO`, `WARN`,
`ERROR`, `FATAL`, `OF
</tr>
<tr class="even">
<td><span class="keyword parmname">\-\-statistic-archive-file </span></td>
-<td>The file to which the running system member writes statistic samples. For
example: "StatisticsArchiveFile.gfs". An empty string disables
archiving. Adding .gz suffix to the file name causes it to be compressed. See
<a
href="../../../managing/statistics/chapter_overview.html">Statistics</a>.</td>
+<td>The file to which the running system member writes statistic samples. For
example: "StatisticsArchiveFile.gfs". Must be defined to store the
archiving to a file. Adding the <code>.gz</code> suffix to the file name causes
it to be compressed. See <a
href="../../../managing/statistics/chapter_overview.html">Statistics</a>.</td>
<td><em>not set</em></td>
</tr>
<tr class="odd">
@@ -510,7 +510,7 @@ Valid values are: `ALL`, `TRACE`, `DEBUG`, `INFO`, `WARN`,
`ERROR`, `FATAL`, `OF
</tr>
<tr class="even">
<td><span class="keyword parmname">\-\-enable-statistics</span></td>
-<td>Whether statistic sampling should be enabled. Valid values are: <code
class="ph codeph">true</code> and <code class="ph codeph">false</code>. See <a
href="../../../managing/statistics/chapter_overview.html">Statistics</a>.</td>
+<td>Whether statistic sampling should be enabled. Specify
<code>--statistic-archive-file</code> to store the statistics to a file. Valid
values are: <code class="ph codeph">true</code> and <code class="ph
codeph">false</code>. See <a
href="../../../managing/statistics/chapter_overview.html">Statistics</a>.</td>
<td>false</td>
</tr>
<tr class="odd">
diff --git a/geode-docs/tools_modules/gfsh/command-pages/start.html.md.erb
b/geode-docs/tools_modules/gfsh/command-pages/start.html.md.erb
index 3520231..f51cc6c 100644
--- a/geode-docs/tools_modules/gfsh/command-pages/start.html.md.erb
+++ b/geode-docs/tools_modules/gfsh/command-pages/start.html.md.erb
@@ -631,8 +631,8 @@ start server --name=value [--assign-buckets(=value)]
[--bind-address=value]
</tr>
<tr class="even">
<td><span class="keyword parmname">\-\-statistic-archive-file </span></td>
-<td>The file that statistic samples are written to. An empty string (default)
disables statistic archival.</td>
-<td>Â </td>
+<td>The file that statistic samples are written to. For example:
"StatisticsArchiveFile.gfs". Must be defined to store the archiving
to a file. An empty string (default) disables statistic archival.</td>
+<td><em>not set</em></td>
</tr>
<tr class="odd">
<td><span class="keyword parmname">\-\-initial-heap</span></td>
