Return-Path: X-Original-To: archive-asf-public-internal@cust-asf2.ponee.io Delivered-To: archive-asf-public-internal@cust-asf2.ponee.io Received: from cust-asf.ponee.io (cust-asf.ponee.io [163.172.22.183]) by cust-asf2.ponee.io (Postfix) with ESMTP id C11DA200C72 for ; Thu, 27 Apr 2017 19:19:48 +0200 (CEST) Received: by cust-asf.ponee.io (Postfix) id BD80A160BA7; Thu, 27 Apr 2017 17:19:48 +0000 (UTC) Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by cust-asf.ponee.io (Postfix) with SMTP id 97694160B9E for ; Thu, 27 Apr 2017 19:19:47 +0200 (CEST) Received: (qmail 79743 invoked by uid 500); 27 Apr 2017 17:19:46 -0000 Mailing-List: contact commits-help@ignite.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@ignite.apache.org Delivered-To: mailing list commits@ignite.apache.org Received: (qmail 79734 invoked by uid 99); 27 Apr 2017 17:19:46 -0000 Received: from git1-us-west.apache.org (HELO git1-us-west.apache.org) (140.211.11.23) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 27 Apr 2017 17:19:46 +0000 Received: by git1-us-west.apache.org (ASF Mail Server at git1-us-west.apache.org, from userid 33) id B2E31DFDAC; Thu, 27 Apr 2017 17:19:46 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: dmagda@apache.org To: commits@ignite.apache.org Message-Id: <3bb5d6c25ab54df3b5253deefcedd20f@git.apache.org> X-Mailer: ASF-Git Admin Mailer Subject: ignite git commit: Improved MemoryMetrics documentation. Date: Thu, 27 Apr 2017 17:19:46 +0000 (UTC) archived-at: Thu, 27 Apr 2017 17:19:48 -0000 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 Authored: Thu Apr 27 10:19:40 2017 -0700 Committer: Denis Magda 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 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}. *

- * As multiple page memories may be configured on a single Ignite node; memory metrics will be collected - * for each page memory separately. - *

+ * 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. *

- * There are two ways to access metrics on local node. + * There are two ways to get the metrics of an Apache Ignite node. *

    *
  1. - * Firstly, collection of metrics can be obtained through {@link Ignite#memoryMetrics()} call.
    - * 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. *
    2. *
  2. - * Secondly, all {@link MemoryMetrics} on local node are exposed through JMX interface.
    - * 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. *
    3. *
*

*

- * 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. - *

+ * 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. *

- * 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. *

@@ -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. + *

+ * 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). + *

+ * 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"