You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@ignite.apache.org by ak...@apache.org on 2017/04/28 06:58:16 UTC
[55/59] [abbrv] ignite git commit: Improved MemoryMetrics
documentation.
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/e981f1d0
Tree: http://git-wip-us.apache.org/repos/asf/ignite/tree/e981f1d0
Diff: http://git-wip-us.apache.org/repos/asf/ignite/diff/e981f1d0
Branch: refs/heads/master
Commit: e981f1d06c524eddc7666a0787abf385111a07a9
Parents: 11c23b6
Author: Denis Magda <dm...@gridgain.com>
Authored: Thu Apr 27 10:19:40 2017 -0700
Committer: Alexey Goncharuk <al...@gmail.com>
Committed: Thu Apr 27 20:39:55 2017 +0300
----------------------------------------------------------------------
.../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/e981f1d0/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/e981f1d0/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/e981f1d0/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/e981f1d0/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/e981f1d0/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"