ignite-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From dma...@apache.org
Subject ignite git commit: Improved MemoryMetrics documentation.
Date Thu, 27 Apr 2017 17:19:46 GMT
Repository: ignite
Updated Branches:
  refs/heads/ignite-5072-merge 1c9701dcf -> 25d85e5ed


Improved MemoryMetrics documentation.


Project: http://git-wip-us.apache.org/repos/asf/ignite/repo
Commit: http://git-wip-us.apache.org/repos/asf/ignite/commit/25d85e5e
Tree: http://git-wip-us.apache.org/repos/asf/ignite/tree/25d85e5e
Diff: http://git-wip-us.apache.org/repos/asf/ignite/diff/25d85e5e

Branch: refs/heads/ignite-5072-merge
Commit: 25d85e5ed16d1332f154dc49c78788a2780092ce
Parents: 1c9701d
Author: Denis Magda <dmagda@gridgain.com>
Authored: Thu Apr 27 10:19:40 2017 -0700
Committer: Denis Magda <dmagda@gridgain.com>
Committed: Thu Apr 27 10:19:40 2017 -0700

----------------------------------------------------------------------
 .../src/main/java/org/apache/ignite/Ignite.java |  3 +-
 .../java/org/apache/ignite/MemoryMetrics.java   | 50 ++++++++++-------
 .../configuration/MemoryConfiguration.java      |  8 +--
 .../MemoryPolicyConfiguration.java              |  6 +-
 .../ignite/mxbean/MemoryMetricsMXBean.java      | 59 ++++++++++----------
 5 files changed, 69 insertions(+), 57 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/ignite/blob/25d85e5e/modules/core/src/main/java/org/apache/ignite/Ignite.java
----------------------------------------------------------------------
diff --git a/modules/core/src/main/java/org/apache/ignite/Ignite.java b/modules/core/src/main/java/org/apache/ignite/Ignite.java
index 267f4f2..671efca 100644
--- a/modules/core/src/main/java/org/apache/ignite/Ignite.java
+++ b/modules/core/src/main/java/org/apache/ignite/Ignite.java
@@ -616,7 +616,8 @@ public interface Ignite extends AutoCloseable {
     public void resetLostPartitions(Collection<String> cacheNames);
 
     /**
-     * Returns collection {@link MemoryMetrics} objects providing information about memory
usage in current Ignite instance.
+     * Returns a collection of {@link MemoryMetrics} that reflects page memory usage on this
Apache Ignite node
+     * instance.
      *
      * @return Collection of {@link MemoryMetrics}
      */

http://git-wip-us.apache.org/repos/asf/ignite/blob/25d85e5e/modules/core/src/main/java/org/apache/ignite/MemoryMetrics.java
----------------------------------------------------------------------
diff --git a/modules/core/src/main/java/org/apache/ignite/MemoryMetrics.java b/modules/core/src/main/java/org/apache/ignite/MemoryMetrics.java
index 96eedfe..81f8309 100644
--- a/modules/core/src/main/java/org/apache/ignite/MemoryMetrics.java
+++ b/modules/core/src/main/java/org/apache/ignite/MemoryMetrics.java
@@ -22,63 +22,71 @@ import org.apache.ignite.configuration.MemoryPolicyConfiguration;
 import org.apache.ignite.mxbean.MemoryMetricsMXBean;
 
 /**
- * An interface to collect metrics about page memory usage on Ignite node. Overall page memory
architecture
- * is described in {@link MemoryConfiguration} javadoc.
+ * This interface provides page memory related metrics of a specific Apache Ignite node.
The overall page memory
+ * architecture is covered in {@link MemoryConfiguration}.
  * <p>
- * As multiple page memories may be configured on a single Ignite node; memory metrics will
be collected
- * for each page memory separately.
- * </p>
+ * Since there are can be several memory regions configured with {@link MemoryPolicyConfiguration}
on an individual
+ * Apache Ignite node, the metrics for every region will be collected and obtained separately.
  * <p>
- * There are two ways to access metrics on local node.
+ * There are two ways to get the metrics of an Apache Ignite node.
  * <ol>
  *     <li>
- *       Firstly, collection of metrics can be obtained through {@link Ignite#memoryMetrics()}
call.<br/>
- *       Please pay attention that this call returns snapshots of memory metrics and not
live objects.
+ *       First, a collection of the metrics can be obtained through {@link Ignite#memoryMetrics()}
method. Note that
+ *       the method returns memory metrics snapshots rather than just in time memory state.
  *     </li>
  *     <li>
- *       Secondly, all {@link MemoryMetrics} on local node are exposed through JMX interface.
<br/>
- *       See {@link MemoryMetricsMXBean} interface describing information provided about
metrics
- *       and page memory configuration.
+ *       Second, all {@link MemoryMetrics} of a local Apache Ignite node are visible through
JMX interface. Refer to
+ *       {@link MemoryMetricsMXBean} for more details.
  *     </li>
  * </ol>
  * </p>
  * <p>
- * Also users must be aware that using memory metrics has some overhead and for performance
reasons is turned off
- * by default.
- * For turning them on both {@link MemoryPolicyConfiguration#setMetricsEnabled(boolean)}
configuration property
- * or {@link MemoryMetricsMXBean#enableMetrics()} method of JMX bean can be used.
- * </p>
+ * Memory metrics collection is not a free operation and might affect performance of an application.
This is the reason
+ * why the metrics are turned off by default. To enable the collection you can use both
+ * {@link MemoryPolicyConfiguration#setMetricsEnabled(boolean)} configuration property or
+ * {@link MemoryMetricsMXBean#enableMetrics()} method of a respective JMX bean.
  */
 public interface MemoryMetrics {
     /**
-     * @return Name of memory region metrics are collected for.
+     * A name of a memory region the metrics are collected for.
+     *
+     * @return Name of the memory region.
      */
     public String getName();
 
     /**
+     * Gets a total number of allocated pages in a memory region.
+     *
      * @return Total number of allocated pages.
      */
     public long getTotalAllocatedPages();
 
     /**
-     * @return Number of allocated pages per second within PageMemory.
+     * Gets pages allocation rate of a memory region.
+     *
+     * @return Number of allocated pages per second.
      */
     public float getAllocationRate();
 
     /**
-     * @return Number of evicted pages per second within PageMemory.
+     * Gets eviction rate of a given memory region.
+     *
+     * @return Number of evicted pages per second.
      */
     public float getEvictionRate();
 
     /**
-     * Large entities bigger than page are split into fragments so each fragment can fit
into a page.
+     * Gets percentage of pages that are fully occupied by large entries that go beyond page
size. The large entities
+     * are split into fragments in a way so that each fragment can fit into a single page.
      *
      * @return Percentage of pages fully occupied by large entities.
      */
     public float getLargeEntriesPagesPercentage();
 
     /**
-     * @return Free space to overall size ratio across all pages in FreeList.
+     * Gets the percentage of space that is still free and can be filled in.
+     *
+     * @return The percentage of space that is still free and can be filled in.
      */
     public float getPagesFillFactor();
 }

http://git-wip-us.apache.org/repos/asf/ignite/blob/25d85e5e/modules/core/src/main/java/org/apache/ignite/configuration/MemoryConfiguration.java
----------------------------------------------------------------------
diff --git a/modules/core/src/main/java/org/apache/ignite/configuration/MemoryConfiguration.java
b/modules/core/src/main/java/org/apache/ignite/configuration/MemoryConfiguration.java
index cadc033..585335b 100644
--- a/modules/core/src/main/java/org/apache/ignite/configuration/MemoryConfiguration.java
+++ b/modules/core/src/main/java/org/apache/ignite/configuration/MemoryConfiguration.java
@@ -23,11 +23,11 @@ import org.apache.ignite.internal.util.typedef.internal.U;
 
 /**
  * A page memory configuration for an Apache Ignite node. The page memory is a manageable
off-heap based memory
- * architecture that divides all continuously allocated memory regions into pages of fixed
size
+ * architecture that divides all expandable memory regions into pages of fixed size
  * (see {@link MemoryConfiguration#getPageSize()}. An individual page can store one or many
cache key-value entries
  * that allows reusing the memory in the most efficient way and avoid memory fragmentation
issues.
  * <p>
- * By default, the page memory allocates a single continuous memory region using settings
of
+ * By default, the page memory allocates a single expandable memory region using settings
of
  * {@link MemoryConfiguration#createDefaultPolicyConfig()}. All the caches that will be configured
in an application
  * will be mapped to this memory region by default, thus, all the cache data will reside
in that memory region.
  * <p>
@@ -154,7 +154,7 @@ public class MemoryConfiguration implements Serializable {
     }
 
     /**
-     * The pages memory consists of one or more continuous memory regions defined by {@link
MemoryPolicyConfiguration}.
+     * The pages memory consists of one or more expandable memory regions defined by {@link
MemoryPolicyConfiguration}.
      * Every memory region is split on pages of fixed size that store actual cache entries.
      *
      * @return Page size in bytes.
@@ -202,7 +202,7 @@ public class MemoryConfiguration implements Serializable {
     }
 
     /**
-     * Creates a configuration for the default memory policy that will instantiate the default
continuous memory region.
+     * Creates a configuration for the default memory policy that will instantiate the default
memory region.
      * To override settings of the default memory policy in order to create the default memory
region with different
      * parameters, create own memory policy first, pass it to
      * {@link MemoryConfiguration#setMemoryPolicies(MemoryPolicyConfiguration...)} method
and change the name of the

http://git-wip-us.apache.org/repos/asf/ignite/blob/25d85e5e/modules/core/src/main/java/org/apache/ignite/configuration/MemoryPolicyConfiguration.java
----------------------------------------------------------------------
diff --git a/modules/core/src/main/java/org/apache/ignite/configuration/MemoryPolicyConfiguration.java
b/modules/core/src/main/java/org/apache/ignite/configuration/MemoryPolicyConfiguration.java
index 55da5bd..c93b423 100644
--- a/modules/core/src/main/java/org/apache/ignite/configuration/MemoryPolicyConfiguration.java
+++ b/modules/core/src/main/java/org/apache/ignite/configuration/MemoryPolicyConfiguration.java
@@ -163,11 +163,11 @@ public final class MemoryPolicyConfiguration implements Serializable
{
     }
 
     /**
-     * A path to the memory-mapped file the memory region defined by this memory policy will
be mapped to. Having
+     * A path to the memory-mapped files the memory region defined by this memory policy
will be mapped to. Having
      * the path set, allows relying on swapping capabilities of an underlying operating system
for the memory region.
      *
-     * @return A path to the memory-mapped file or {@code null} if this feature is not used
for the memory region defined
-     *         by this memory policy.
+     * @return A path to the memory-mapped files or {@code null} if this feature is not used
for the memory region
+     *         defined by this memory policy.
      */
     public String getSwapFilePath() {
         return swapFilePath;

http://git-wip-us.apache.org/repos/asf/ignite/blob/25d85e5e/modules/core/src/main/java/org/apache/ignite/mxbean/MemoryMetricsMXBean.java
----------------------------------------------------------------------
diff --git a/modules/core/src/main/java/org/apache/ignite/mxbean/MemoryMetricsMXBean.java
b/modules/core/src/main/java/org/apache/ignite/mxbean/MemoryMetricsMXBean.java
index 6835073..b371d2a 100644
--- a/modules/core/src/main/java/org/apache/ignite/mxbean/MemoryMetricsMXBean.java
+++ b/modules/core/src/main/java/org/apache/ignite/mxbean/MemoryMetricsMXBean.java
@@ -17,39 +17,40 @@
 package org.apache.ignite.mxbean;
 
 import org.apache.ignite.MemoryMetrics;
+import org.apache.ignite.configuration.MemoryPolicyConfiguration;
 
 /**
- * This interface defines JMX view on {@link MemoryMetrics}.
+ * This interface defines a JMX view on {@link MemoryMetrics}.
  */
-@MXBeanDescription("MBean that provides access to MemoryMetrics of current Ignite node.")
+@MXBeanDescription("MBean that provides access to MemoryMetrics of a local Apache Ignite
node.")
 public interface MemoryMetricsMXBean extends MemoryMetrics {
     /** {@inheritDoc} */
-    @MXBeanDescription("Name of MemoryPolicy metrics are collected for.")
+    @MXBeanDescription("A name of a memory region the metrics are collected for.")
     @Override public String getName();
 
     /**
-     * Initial size configured for MemoryPolicy on local node.
+     * Gets initial memory region size defined by its {@link MemoryPolicyConfiguration}.
      *
      * @return Initial size in MB.
      */
-    @MXBeanDescription("Initial size configured for MemoryPolicy on local node.")
+    @MXBeanDescription("Initial memory region size defined by its memory policy.")
     public int getInitialSize();
 
     /**
-     * Maximum size configured for MemoryPolicy on local node.
+     * Maximum memory region size defined by its {@link MemoryPolicyConfiguration}.
      *
      * @return Maximum size in MB.
      */
-    @MXBeanDescription("Maximum size configured for MemoryPolicy on local node.")
+    @MXBeanDescription("Maximum memory region size defined by its memory policy.")
     public int getMaxSize();
 
     /**
-     * Path from MemoryPolicy configuration to directory where memory-mapped files used for
swap are created.
-     * Depending on configuration may be absolute or relative; in the latter case it is relative
to IGNITE_HOME.
+     * A path to the memory-mapped files the memory region defined by {@link MemoryPolicyConfiguration}
will be
+     * mapped to.
      *
-     * @return path to directory with memory-mapped files.
+     * @return Path to the memory-mapped files.
      */
-    @MXBeanDescription("Path to directory with memory-mapped files.")
+    @MXBeanDescription("Path to the memory-mapped files.")
     public String getSwapFilePath();
 
     /** {@inheritDoc} */
@@ -65,35 +66,35 @@ public interface MemoryMetricsMXBean extends MemoryMetrics {
     @Override public float getEvictionRate();
 
     /** {@inheritDoc} */
-    @MXBeanDescription("Percentage of pages fully occupied by large entities' fragments.")
+    @MXBeanDescription("Percentage of pages that are fully occupied by large entries that
go beyond page size.")
     @Override public float getLargeEntriesPagesPercentage();
 
     /** {@inheritDoc} */
-    @MXBeanDescription("Pages fill factor: size of all entries in cache over size of all
allocated pages.")
+    @MXBeanDescription("Percentage of space that is still free and can be filled in.")
     @Override public float getPagesFillFactor();
 
     /**
-     * Enables collecting memory metrics on local node.
+     * Enables memory metrics collection on an Apache Ignite node.
      */
-    @MXBeanDescription("Enables collecting memory metrics on local node.")
+    @MXBeanDescription("Enables memory metrics collection on an Apache Ignite node.")
     public void enableMetrics();
 
     /**
-     * Disables collecting memory metrics on local node.
+     * Disables memory metrics collection on an Apache Ignite node.
      */
-    @MXBeanDescription("Disables collecting memory metrics on local node.")
+    @MXBeanDescription("Disables memory metrics collection on an Apache Ignite node.")
     public void disableMetrics();
 
     /**
-     * Sets interval of time (in seconds) to monitor allocation rate.
-     *
-     * E.g. after setting rateTimeInterval to 60 seconds subsequent calls to {@link #getAllocationRate()}
+     * Sets time interval for {@link #getAllocationRate()} and {@link #getEvictionRate()}
monitoring purposes.
+     * <p>
+     * For instance, after setting the interval to 60 seconds, subsequent calls to {@link
#getAllocationRate()}
      * will return average allocation rate (pages per second) for the last minute.
      *
-     * @param rateTimeInterval Time interval used to calculate allocation/eviction rate.
+     * @param rateTimeInterval Time interval used for allocation and eviction rates calculations.
      */
     @MXBeanDescription(
-        "Sets time interval average allocation rate (pages per second) is calculated over."
+        "Sets time interval for pages allocation and eviction monitoring purposes."
     )
     @MXBeanParametersNames(
         "rateTimeInterval"
@@ -104,15 +105,17 @@ public interface MemoryMetricsMXBean extends MemoryMetrics {
     public void rateTimeInterval(int rateTimeInterval);
 
     /**
-     * Sets number of subintervals the whole rateTimeInterval will be split into to calculate
allocation rate,
-     * 5 by default.
-     * Setting it to bigger number allows more precise calculation and smaller drops of allocationRate
metric
-     * when next subinterval has to be recycled but introduces bigger calculation overhead.
+     * Sets a number of sub-intervals the whole {@link #rateTimeInterval(int)} will be split
into to calculate
+     * {@link #getAllocationRate()} and {@link #getEvictionRate()} rates (5 by default).
+     * <p>
+     * Setting it to a bigger value will result in more precise calculation and smaller drops
of
+     * {@link #getAllocationRate()} metric when next sub-interval has to be recycled but
introduces bigger
+     * calculation overhead.
      *
-     * @param subInts Number of subintervals.
+     * @param subInts A number of sub-intervals.
      */
     @MXBeanDescription(
-        "Sets number of subintervals to calculate allocationRate metrics."
+        "Sets a number of sub-intervals to calculate allocation and eviction rates metrics."
     )
     @MXBeanParametersNames(
         "subInts"


Mime
View raw message