http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/84cfbdfc/geode-docs/managing/heap_use/heap_management.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/managing/heap_use/heap_management.html.md.erb b/geode-docs/managing/heap_use/heap_management.html.md.erb deleted file mode 100644 index 7fab249..0000000 --- a/geode-docs/managing/heap_use/heap_management.html.md.erb +++ /dev/null @@ -1,225 +0,0 @@ ---- -title: Managing Heap and Off-heap Memory ---- - -<!-- -Licensed to the Apache Software Foundation (ASF) under one or more -contributor license agreements. See the NOTICE file distributed with -this work for additional information regarding copyright ownership. -The ASF licenses this file to You under the Apache License, Version 2.0 -(the "License"); you may not use this file except in compliance with -the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -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. ---> - -By default, Apache Geode uses the JVM heap. Apache Geode also offers an option to store data off heap. This section describes how to manage heap and off-heap memory to best support your application. - -## <a id="section_590DA955523246ED980E4E351FF81F71" class="no-quick-link"></a>Tuning the JVM's Garbage Collection Parameters - -Because Apache Geode is specifically designed to manipulate data held in memory, you can optimize your application's performance by tuning the way Apache Geode uses the JVM heap. - -See your JVM documentation for all JVM-specific settings that can be used to improve garbage collection (GC) response. At a minimum, do the following: - -1. Set the initial and maximum heap switches, `-Xms` and `-Xmx`, to the same values. The `gfsh start server` options `--initial-heap` and `--max-heap` accomplish the same purpose, with the added value of providing resource manager defaults such as eviction threshold and critical threshold. -2. Configure your JVM for concurrent mark-sweep (CMS) garbage collection. -3. If your JVM allows, configure it to initiate CMS collection when heap use is at least 10% lower than your setting for the resource manager `eviction-heap-percentage`. You want the collector to be working when Geode is evicting or the evictions will not result in more free memory. For example, if the `eviction-heap-percentage` is set to 65, set your garbage collection to start when the heap use is no higher than 55%. - -| JVM | CMS switch flag | CMS initiation (begin at heap % N) | -|-------------|---------------------------|----------------------------------------| -| Sun HotSpot | `âXX:+UseConcMarkSweepGC` | `âXX:CMSInitiatingOccupancyFraction=N` | -| JRockit | `-Xgc:gencon` | `-XXgcTrigger:N` | -| IBM | `-Xgcpolicy:gencon` | N/A | - -For the `gfsh start server` command, pass these settings with the `--J` switch, for example: `ââJ=âXX:+UseConcMarkSweepGC`. - -The following is an example of setting JVM for an application: - -``` pre -$ java app.MyApplication -Xms=30m -Xmx=30m -XX:+UseConcMarkSweepGC -XX:CMSInitiatingOccupancyFraction=60 -``` - -**Note:** Do not use the `-XX:+UseCompressedStrings` and `-XX:+UseStringCache` JVM configuration properties when starting up servers. These JVM options can cause issues with data corruption and compatibility. - -Or, using `gfsh`: - -``` pre -$ gfsh start server --name=app.MyApplication --initial-heap=30m --max-heap=30m \ ---J=-XX:+UseConcMarkSweepGC --J=-XX:CMSInitiatingOccupancyFraction=60 -``` - -## <a id="how_the_resource_manager_works" class="no-quick-link"></a>Using the Geode Resource Manager - -The Geode resource manager works with your JVM's tenured garbage collector to control heap use and protect your member from hangs and crashes due to memory overload. - -<a id="how_the_resource_manager_works__section_53E80B61991447A2915E8A754383B32D"></a> -The Geode resource manager prevents the cache from consuming too much memory by evicting old data. If the garbage collector is unable to keep up, the resource manager refuses additions to the cache until the collector has freed an adequate amount of memory. - -The resource manager has two threshold settings, each expressed as a percentage of the total tenured heap. Both are disabled by default. - - 1. **Eviction Threshold**. Above this, the manager orders evictions for all regions with `eviction-attributes` set to `lru-heap-percentage`. This prompts dedicated background evictions, independent of any application threads and it also tells all application threads adding data to the regions to evict at least as much data as they add. The JVM garbage collector removes the evicted data, reducing heap use. The evictions continue until the manager determines that heap use is again below the eviction threshold. - - The resource manager enforces eviction thresholds only on regions whose LRU eviction policies are based on heap percentage. Regions whose eviction policies based on entry count or memory size use other mechanisms to manage evictions. See [Eviction](../../developing/eviction/chapter_overview.html) for more detail regarding eviction policies. - - 2. **Critical Threshold**. Above this, all activity that might add data to the cache is refused. This threshold is set above the eviction threshold and is intended to allow the eviction and GC work to catch up. This JVM, all other JVMs in the distributed system, and all clients to the system receive `LowMemoryException` for operations that would add to this critical member's heap consumption. Activities that fetch or reduce data are allowed. For a list of refused operations, see the Javadocs for the `ResourceManager` method `setCriticalHeapPercentage`. - - Critical threshold is enforced on all regions, regardless of LRU eviction policy, though it can be set to zero to disable its effect. - -<img src="../../images/DataManagement-9.png" id="how_the_resource_manager_works__image_C3568D47EE1B4F2C9F0742AE9C291BF1" class="image" /> - -When heap use passes the eviction threshold in either direction, the manager logs an info-level message. - -When heap use exceeds the critical threshold, the manager logs an error-level message. Avoid exceeding the critical threshold. Once identified as critical, the Geode member becomes a read-only member that refuses cache updates for all of its regions, including incoming distributed updates. - -For more information, see `org.apache.geode.cache.control.ResourceManager` in the online API documentation. - -## <a id="how_the_resource_manager_works__section_EA5E52E65923486488A71E3E6F0DE9DA" class="no-quick-link"></a>How Background Eviction Is Performed - -When the manager kicks off evictions: - -1. From all regions in the local cache that are configured for heap LRU eviction, the background eviction manager creates a randomized list containing one entry for each partitioned region bucket (primary or secondary) and one entry for each non-partitioned region. So each partitioned region bucket is treated the same as a single, non-partitioned region. - -2. The background eviction manager starts four evictor threads for each processor on the local machine. The manager passes each thread its share of the bucket/region list. The manager divides the bucket/region list as evenly as possible by count, and not by memory consumption. - -3. Each thread iterates round-robin over its bucket/region list, evicting one LRU entry per bucket/region until the resource manager sends a signal to stop evicting. - -See also [Memory Requirements for Cached Data](../../reference/topics/memory_requirements_for_cache_data.html#calculating_memory_requirements). - -## <a id="configuring_resource_manager_controlling_heap_use" class="no-quick-link"></a>Controlling Heap Use with the Resource Manager - -Resource manager behavior is closely tied to the triggering of Garbage Collection (GC) activities, the use of concurrent garbage collectors in the JVM, and the number of parallel GC threads used for concurrency. - -<a id="configuring_resource_manager__section_B47A78E7BA0048C89FBBDB7441C308BE"></a> -The recommendations provided here for using the manager assume you have a solid understanding of your Java VM's heap management and garbage collection service. - -The resource manager is available for use in any Apache Geode member, but you may not want to activate it everywhere. For some members it might be better to occasionally restart after a hang or OME crash than to evict data and/or refuse distributed caching activities. Also, members that do not risk running past their memory limits would not benefit from the overhead the resource manager consumes. Cache servers are often configured to use the manager because they generally host more data and have more data activity than other members, requiring greater responsiveness in data cleanup and collection. - -For the members where you want to activate the resource manager: - -1. Configure Geode for heap LRU management. - -2. Set the JVM GC tuning parameters to handle heap and garbage collection in conjunction with the Geode manager. - -3. Monitor and tune heap LRU configurations and your GC configurations. - -4. Before going into production, run your system tests with application behavior and data loads that approximate your target systems so you can tune as well as possible for production needs. - -5. In production, keep monitoring and tuning to meet changing needs. - -## <a id="configuring_resource_manager__section_4949882892DA46F6BB8588FA97037F45" class="no-quick-link"></a>Configure Geode for Heap LRU Management - -The configuration terms used here are `cache.xml` elements and attributes, but you can also configure through `gfsh` and the `org.apache.geode.cache.control.ResourceManager` and `Region` APIs. - -1. When starting up your server, set `initial-heap` and `max-heap` to the same value. - -2. Set the `resource-manager` `critical-heap-percentage` threshold. This should be as as close to 100 as possible while still low enough so the manager's response can prevent the member from hanging or getting `OutOfMemoryError`. The threshold is zero (no threshold) by default. - - **Note:** When you set this threshold, it also enables a query monitoring feature that prevents most out-of-memory exceptions when executing queries or creating indexes. See [Monitoring Queries for Low Memory](../../developing/querying_basics/monitor_queries_for_low_memory.html#topic_685CED6DE7D0449DB8816E8ABC1A6E6F). - -3. Set the `resource-manager` `eviction-heap-percentage` threshold to a value lower than the critical threshold. This should be as high as possible while still low enough to prevent your member from reaching the critical threshold. The threshold is zero (no threshold) by default. - -4. Decide which regions will participate in heap eviction and set their `eviction-attributes` to `lru-heap-percentage`. See [Eviction](../../developing/eviction/chapter_overview.html). The regions you configure for eviction should have enough data activity for the evictions to be useful and should contain data your application can afford to delete or offload to disk. - -<a id="configuring_resource_manager__section_5D88064B75C643B0849BBD4345A6671B"></a> - -gfsh example: - -``` pre -gfsh>start server --name=server1 --initial-heap=30m --max-heap=30m \ ---critical-heap-percentage=80 --eviction-heap-percentage=60 -``` - -cache.xml example: - -``` pre -<cache> -<region refid="REPLICATE_HEAP_LRU" /> -... -<resource-manager critical-heap-percentage="80" eviction-heap-percentage="60"/> -</cache> -``` - -**Note:** The `resource-manager` specification must appear after the region declarations in your cache.xml file. - -## <a id="set_jvm_gc_tuning_params" class="no-quick-link"></a>Set the JVM GC Tuning Parameters - -If your JVM allows, configure it to initiate concurrent mark-sweep (CMS) garbage collection when heap use is at least 10% lower than your setting for the resource manager `eviction-heap-percentage`. You want the collector to be working when Geode is evicting or the evictions will not result in more free memory. For example, if the `eviction-heap-percentage` is set to 65, set your garbage collection to start when the heap use is no higher than 55%. - -## <a id="configuring_resource_manager__section_DE1CC494C2B547B083AA00821250972A" class="no-quick-link"></a>Monitor and Tune Heap LRU Configurations - -In tuning the resource manager, your central focus should be keeping the member below the critical threshold. The critical threshold is provided to avoid member hangs and crashes, but because of its exception-throwing behavior for distributed updates, the time spent in critical negatively impacts the entire distributed system. To stay below critical, tune so that the Geode eviction and the JVM's GC respond adequately when the eviction threshold is reached. - -Use the statistics provided by your JVM to make sure your memory and GC settings are sufficient for your needs. - -The Geode `ResourceManagerStats` provide information about memory use and the manager thresholds and eviction activities. - -If your application spikes above the critical threshold on a regular basis, try lowering the eviction threshold. If the application never goes near critical, you might raise the eviction threshold to gain more usable memory without the overhead of unneeded evictions or GC cycles. - -The settings that will work well for your system depend on a number of factors, including these: - - - The size of the data objects you store in the cache -Very large data objects can be evicted and garbage collected relatively quickly. The same amount of space in use by many small objects takes more processing effort to clear and might require lower thresholds to allow eviction and GC activities to keep up. - - - Application behavior -Applications that quickly put a lot of data into the cache can more easily overrun the eviction and GC capabilities. Applications that operate more slowly may be more easily offset by eviction and GC efforts, possibly allowing you to set your thresholds higher than in the more volatile system. - - - Your choice of JVM -Each JVM has its own GC behavior, which affects how efficiently the collector can operate, how quickly it kicks in when needed, and other factors. - -## <a id="resource_manager_example_configurations" class="no-quick-link"></a>Resource Manager Example Configurations - -<a id="resource_manager_example_configurations__section_B50C552B114D47F3A63FC906EB282024"></a> -These examples set the critical threshold to 85 percent of the tenured heap and the eviction threshold to 75 percent. The region `bigDataStore` is configured to participate in the resource manager's eviction activities. - -- gfsh Example: - - ``` pre - gfsh>start server --name=server1 --initial-heap=30MB --max-heap=30MB \ - --critical-heap-percentage=85 --eviction-heap-percentage=75 - ``` - - ``` pre - gfsh>create region --name=bigDataStore --type=PARTITION_HEAP_LRU - ``` - -- XML: - - ``` pre - <cache> - <region name="bigDataStore" refid="PARTITION_HEAP_LRU"/> - ... - <resource-manager critical-heap-percentage="85" eviction-heap-percentage="75"/> - </cache> - ``` - - **Note:** The `resource-manager` specification must appear after the region declarations in your cache.xml file. - -- Java: - - ``` pre - Cache cache = CacheFactory.create(); - - ResourceManager rm = cache.getResourceManager(); - rm.setCriticalHeapPercentage(85); - rm.setEvictionHeapPercentage(75); - - RegionFactory rf = - cache.createRegionFactory(RegionShortcut.PARTITION_HEAP_LRU); - Region region = rf.create("bigDataStore"); - ``` - -## <a id="resource_manager_example_configurations__section_95497FDF114A4DC8AC5D899E05E324E5" class="no-quick-link"></a>Use Case for the Example Code - -This is one possible scenario for the configuration used in the examples: - -- A 64-bit Java VM with 8 Gb of heap space on a 4 CPU system running Linux. -- The data region bigDataStore has approximately 2-3 million small values with average entry size of 512 bytes. So approximately 4-6 Gb of the heap is for region storage. -- The member hosting the region also runs an application that may take up to 1 Gb of the heap. -- The application must never run out of heap space and has been crafted such that data loss in the region is acceptable if the heap space becomes limited due to application issues, so the default `lru-heap-percentage` action destroy is suitable. -- The application's service guarantee makes it very intolerant of `OutOfMemoryException` errors. Testing has shown that leaving 15% head room above the critical threshold when adding data to the region gives 99.5% uptime with no `OutOfMemoryException` errors, when configured with the CMS garbage collector using `-XX:CMSInitiatingOccupancyFraction=70`.
http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/84cfbdfc/geode-docs/managing/heap_use/lock_memory.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/managing/heap_use/lock_memory.html.md.erb b/geode-docs/managing/heap_use/lock_memory.html.md.erb deleted file mode 100644 index f97e7e3..0000000 --- a/geode-docs/managing/heap_use/lock_memory.html.md.erb +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: Locking Memory (Linux Systems Only) ---- - -<!-- -Licensed to the Apache Software Foundation (ASF) under one or more -contributor license agreements. See the NOTICE file distributed with -this work for additional information regarding copyright ownership. -The ASF licenses this file to You under the Apache License, Version 2.0 -(the "License"); you may not use this file except in compliance with -the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -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. ---> - -<a id="locking-memory"></a> - - -On Linux systems, you can lock memory to prevent the operating system from paging out heap or off-heap memory. - -To use this feature: - -1. Configure the operating system limits for locked memory. Increase the operating system's `ulimit -l` value (the maximum size that may be locked in memory) from the default (typically 32 KB or 64 KB) to at least the total amount of memory used by Geode for on-heap or off-heap storage. To view the current setting, enter `ulimit -a` at a shell prompt and find the value for `max locked memory`: - - ``` pre - # ulimit -a - ... - max locked memory (kbytes, -l) 64 - ... - ``` - - Use `ulimit -l max-size-in-kbytes` to raise the limit. For example, to set the locked memory limit to 64 GB: - - ``` pre - # ulimit -l 64000000 - ``` - -2. Using locked memory in this manner increases the time required to start Geode. The additional time required to start Geode depends on the total amount of memory used, and can range from several seconds to 10 minutes or more. To improve startup time and reduce the potential of member timeouts, instruct the kernel to free operating system page caches just before starting a Geode member by issuing the following command: - - ``` pre - $ echo 1 > /proc/sys/vm/drop_caches - ``` - -3. Start each Geode data store with the gfsh `-lock-memory=true` option. If you deploy more than one server per host, begin by starting each server sequentially. Starting servers sequentially avoids a race condition in the operating system that can cause failures (even machine crashes) if you accidentally over-allocate the available RAM. After you verify that the system configuration is stable, you can then start servers concurrently. - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/84cfbdfc/geode-docs/managing/heap_use/off_heap_management.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/managing/heap_use/off_heap_management.html.md.erb b/geode-docs/managing/heap_use/off_heap_management.html.md.erb deleted file mode 100644 index 05f33e1..0000000 --- a/geode-docs/managing/heap_use/off_heap_management.html.md.erb +++ /dev/null @@ -1,209 +0,0 @@ ---- -title: Managing Off-Heap Memory ---- - -<!-- -Licensed to the Apache Software Foundation (ASF) under one or more -contributor license agreements. See the NOTICE file distributed with -this work for additional information regarding copyright ownership. -The ASF licenses this file to You under the Apache License, Version 2.0 -(the "License"); you may not use this file except in compliance with -the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -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. ---> -<a id="managing-off-heap-memory"></a> - - -Geode can be configured to store region values in off-heap memory, which is memory within the JVM that is not subject to Java garbage collection. - -Garbage collection (GC) within a JVM can prove to be a performance impediment. A server cannot exert control over when garbage collection within the JVM heap memory takes place, and the server has little control over the triggers for invocation. Off-heap memory offloads values to a storage area that is not subject to Java GC. By taking advantage of off-heap storage, an application can reduce the amount of heap storage that is subject to GC overhead. - -Off-heap memory works in conjunction with the heap, it does not replace it. The keys are stored in heap memory space. Geode's own memory manager handles the off-heap memory with better performance than the Java garbage collector would for certain sets of region data. - -The resource manager monitors the contents of off-heap memory and invokes memory management operations in accordance with two thresholds similar to those used for monitoring the JVM heap: `eviction-off-heap-percentage` and `critical-off-heap-percentage`. - -## On-heap and Off-heap Objects - -The following objects are always stored in the JVM heap: - -- Region metadata -- Entry metadata -- Keys -- Indexes -- Subscription queue elements - -The following objects can be stored in off-heap memory: - -- Values - maximum value size is 2GB -- Reference counts -- List of free memory blocks -- WAN queue elements - -**Note:** -Do not use functional range indexes with off-heap data, as they are not supported. An attempt to do so generates an exception. - -## Off-heap Recommendations - -Off-heap storage is best suited to data patterns where: - -- Stored values are relatively uniform in size -- Stored values are mostly less than 128K in size -- The usage patterns involve cycles of many creates followed by destroys or clear -- The values do not need to be frequently deserialized -- Many of the values are long-lived reference data - -Be aware that Geode has to perform extra work to access the data stored in off-heap memory since it is stored in serialized form. This extra work may cause some use cases to run slower in an off-heap configuration, even though they use less memory and avoid garbage collection overhead. However, even with the extra deserialization, off-heap storage may give you the best performance. Features that may increase overhead include - -- frequent updates -- stored values of widely varying sizes -- deltas -- queries - -## Implementation Details - -The off-heap memory manager is efficient at handling region data values that are all the same size or are of fixed sizes. With fixed and same-sized data values allocated within the off-heap memory, freed chunks can often be re-used, and there is little or no need to devote cycles to defragmentation. - -Region values that are less than or equal to eight bytes in size will not reside in off-heap memory, even if the region is configured to use off-heap memory. These very small size region values reside in the JVM heap in place of a reference to an off-heap location. This performance enhancement saves space and load time. - -## Controlling Off-heap Use with the Resource Manager - -The Geode resource manager controls off-heap memory by means of two thresholds, in much the same way as it does JVM heap memory. See [Using the Geode Resource Manager](heap_management.html#how_the_resource_manager_works). The resource manager prevents the cache from consuming too much off-heap memory by evicting old data. If the off-heap memory manager is unable to keep up, the resource manager refuses additions to the cache until the off-heap memory manager has freed an adequate amount of memory. - -The resource manager has two threshold settings, each expressed as a percentage of the total off-heap memory. Both are disabled by default. - -1. **Eviction Threshold**. The percentage of off-heap memory at which eviction should begin. Evictions continue until the resource manager determines that off-heap memory use is again below the eviction threshold. Set the eviction threshold with the `eviction-off-heap-percentage` region attribute. The resource manager enforces an eviction threshold only on regions with the HEAP\_LRU characteristic. If critical threshold is non-zero, the default eviction threshold is 5% below the critical threshold. If critical threshold is zero, the default eviction threshold is 80% of total off-heap memory. - - The resource manager enforces eviction thresholds only on regions whose LRU eviction policies are based on heap percentage. Regions whose eviction policies based on entry count or memory size use other mechanisms to manage evictions. See [Eviction](../../developing/eviction/chapter_overview.html) for more detail regarding eviction policies. - -2. **Critical Threshold**. The percentage of off-heap memory at which the cache is at risk of becoming inoperable. When cache use exceeds the critical threshold, all activity that might add data to the cache is refused. Any operation that would increase consumption of off-heap memory throws a `LowMemoryException` instead of completing its operation. Set the critical threshold with the `critical-off-heap-percentage` region attribute. - - Critical threshold is enforced on all regions, regardless of LRU eviction policy, though it can be set to zero to disable its effect. - -## Specifying Off-heap Memory - -To use off-heap memory, specify the following options when setting up servers and regions: - -- Start the JVM as described in [Tuning the JVM's Garbage Collection Parameters](heap_management.html#section_590DA955523246ED980E4E351FF81F71). In particular, set the initial and maximum heap sizes to the same value. Sizes less than 32GB are optimal when you plan to use off-heap memory. -- From gfsh, start each server that will support off-heap memory with a non-zero `off-heap-memory-size` value, specified in megabytes (m) or gigabytes (g). If you plan to use the resource manager, specify critical threshold, eviction threshold, or (in most cases) both. - - Example: - - ``` pre - gfsh> start server --name=server1 -âinitial-heap=10G -âmax-heap=10G -âoff-heap-memory-size=200G \ - -âlock-memory=true -âcritical-off-heap-percentage=90 -âeviction-off-heap-percentage=80 - ``` - -- Mark regions whose entry values should be stored off-heap by setting the `off-heap` region attribute to `true` Configure other region attributes uniformly for all members that host data for the same region. . - - Example: - - ``` pre - gfsh>create region --name=region1 --type=PARTITION_HEAP_LRU --off-heap=true - ``` - -## gfsh Off-heap Support - -gfsh supports off-heap memory in server and region creation operations and in reporting functions: - -alter disk-store -`--off-heap=(true | false)` resets the off-heap attribute for the specified region. See [alter disk-store](../../tools_modules/gfsh/command-pages/alter.html#topic_99BCAD98BDB5470189662D2F308B68EB) for details. - -create region -`--off-heap=(true | false) `sets the off-heap attribute for the specified region. See [create region](../../tools_modules/gfsh/command-pages/create.html#topic_54B0985FEC5241CA9D26B0CE0A5EA863) for details. - -describe member -displays off-heap size - -describe offline-disk-store -shows if an off-line region is off-heap - -describe region -displays the value of a region's off-heap attribute - -show metrics -includes off-heap metrics `maxMemory`, `freeMemory`, `usedMemory`, `objects`, `fragmentation` and `defragmentationTime` - -start server -supports off-heap options `--lock-memory`, `ââoff-heap-memory-size`, `ââcritical-off-heap-percentage`, and `ââeviction-off-heap-percentage` See [start server](../../tools_modules/gfsh/command-pages/start.html#topic_3764EE2DB18B4AE4A625E0354471738A) for details. - -## ResourceManager API - -The `org.apache.geode.cache.control.ResourceManager` interface defines methods that support off-heap use: - -- `public void setCriticalOffHeapPercentage(float Percentage)` -- `public float getCriticalOffHeapPercentage()` -- `public void setEvictionOffHeapPercentage(float Percentage)` -- `public float getEvictionOffHeapPercentage()` - -The gemfire.properties file supports one off-heap property: - -`off-heap-memory-size` -Specifies the size of off-heap memory in megabytes (m) or gigabytes (g). For example: - -``` pre -off-heap-memory-size=4096m -off-heap-memory-size=120g -``` - -See [gemfire.properties and gfsecurity.properties (Geode Properties)](../../reference/topics/gemfire_properties.html) for details. - -The cache.xml file supports one region attribute: - -`off-heap(=true | false)` -Specifies that the region uses off-heap memory; defaults to `false`. For example: - -``` pre -<region-attributes - off-heap="true"> -</region-attributes> -``` - -See [<region-attributes>](../../reference/topics/cache_xml.html#region-attributes) for details. - -The cache.xml file supports two resource manager attributes: - -`critical-off-heap-percentage=value` -Specifies the percentage of off-heap memory at or above which the cache is considered in danger of becoming inoperable due to out of memory exceptions. See [<resource-manager>](../../reference/topics/cache_xml.html#resource-manager) for details. - -`eviction-off-heap-percentage=value` -Specifies the percentage of off-heap memory at or above which eviction should begin. Can be set for any region, but actively operates only in regions configured for HEAP\_LRU eviction. See [<resource-manager>](../../reference/topics/cache_xml.html#resource-manager) for details. - -For example: - -``` pre -<cache> -... - <resource-manager - critical-off-heap-percentage="99.9" - eviction-off-heap=-percentage="85"/> -... -</cache> -``` - -## <a id="managing-off-heap-memory__section_o4s_tg5_gv" class="no-quick-link"></a>Tuning Off-heap Memory Usage - -Geode collects statistics on off-heap memory usage which you can view with the gfsh `show metrics` command. See [Off-Heap (OffHeapMemoryStats)](../../reference/statistics/statistics_list.html#topic_ohc_tjk_w5) for a description of available off-heap statistics. - -Off-heap memory is optimized, by default, for storing values of 128 KB in size. This figure is known as the "maximum optimized stored value size," which we will denote here by *maxOptStoredValSize*. If your data typically runs larger, you can enhance performance by increasing the OFF\_HEAP\_FREE\_LIST\_COUNT system parameter to a number larger than `maxOptStoredValSize/8`, where *maxOptStoredValSize* is expressed in KB (1024 bytes). So, the default values correspond to: - -``` pre -128 KB / 8 = (128 * 1024) / 8 = 131,072 / 8 = 16,384 --Dgemfire.OFF_HEAP_FREE_LIST_COUNT=16384 -``` - -To optimize for a maximum optimized stored value size that is twice the default, or 256 KB, the free list count should be doubled: - -``` pre --Dgemfire.OFF_HEAP_FREE_LIST_COUNT=32768 -``` - -During the tuning process, you can toggle the `off-heap` region attribute on and off, leaving other off-heap settings and parameters in place, in order to compare your application's on-heap and off-heap performance. - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/84cfbdfc/geode-docs/managing/logging/configuring_log4j2.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/managing/logging/configuring_log4j2.html.md.erb b/geode-docs/managing/logging/configuring_log4j2.html.md.erb deleted file mode 100644 index 06b5c56..0000000 --- a/geode-docs/managing/logging/configuring_log4j2.html.md.erb +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Advanced UsersâConfiguring Log4j 2 for Geode ---- - -<!-- -Licensed to the Apache Software Foundation (ASF) under one or more -contributor license agreements. See the NOTICE file distributed with -this work for additional information regarding copyright ownership. -The ASF licenses this file to You under the Apache License, Version 2.0 -(the "License"); you may not use this file except in compliance with -the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -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. ---> - -Basic Geode logging configuration is configured via the gemfire.properties file. This topic is intended for advanced users who need increased control over logging due to integration with third-party libraries. - -The default `log4j2.xml` that Geode uses is stored in geode.jar as `log4j2-default.xml`. The contents of the configuration can be viewed in the product distribution in the following location: `$GEMFIRE/defaultConfigs/log4j2.xml`. - -To specify your own `log4j2.xml` configuration file (or anything else supported by Log4j 2 such as .json or .yaml), use the following flag when starting up your JVM or Geode member: - -``` pre --Dlog4j.configurationFile=<location-of-your-file> -``` - -If the Java system property `log4j.configurationFile` is specified, then Geode will not use the `log4j2-default.xml` included in geode.jar. However, Geode will still create and register a AlertAppender and LogWriterAppender if the `alert-level` and `log-file` Geode properties are configured. You can then use the Geode LogWriter to log to Geode's log or to generate an Alert and receive log statements from customer's application and all third party libraries. Alternatively, you can use any front-end logging API that is configured to log to Log4j 2. - -## Using Different Front-End Logging APIs to Log to Log4j2 - -You can also configure Log4j 2 to work with various popular and commonly used logging APIs. To obtain and configure the most popular front-end logging APIs to log to Log4j 2, see the instructions on the Apache Log4j 2 web site at [http://logging.apache.org/log4j/2.x/](http://logging.apache.org/log4j/2.x/). - -For example, if you are using: - -- **Commons Logging**, download "Commons Logging Bridge" (`log4j-jcl-2.1.jar`) -- **SLF4J**, download "SLFJ4 Binding" (`log4j-slf4j-impl-2.1.jar`) -- **java.util.logging**, download the "JUL adapter" (`log4j-jul-2.1.jar`) - -See [http://logging.apache.org/log4j/2.x/faq.html](http://logging.apache.org/log4j/2.x/faq.html) for more examples. - -All three of the above JAR files are in the full distribution of Log4J 2.1 which can be downloaded at [http://logging.apache.org/log4j/2.x/download.html](http://logging.apache.org/log4j/2.x/download.html). Download the appropriate bridge, adapter, or binding JARs to ensure that Geode logging is integrated with every logging API used in various third-party libraries or in your own applications. - -**Note:** -Apache Geode has been tested with Log4j 2.1. As newer versions of Log4j 2 come out, you can find 2.1 under Previous Releases on that page. - -## Customizing Your Own log4j2.xml File - -Advanced users may want to move away entirely from setting `log-*` gemfire properties and instead specify their own `log4j2.xml` using `-Dlog4j.configurationFile`. - -Custom Log4j 2 configuration in Geode comes with some caveats and notes: - -- Do not use `"monitorInterval="` in your log4j2.xml file because doing so can have significant performance impact. This setting instructs Log4j 2 to monitor the log4j2.xml config file at runtime and automatically reload and reconfigure if the file changes. -- Geode's default `log4j2.xml` specifies status="FATAL" because Log4j 2's StatusLogger generates warnings to standard out at ERROR level anytime Geode stops its AlertAppender or LogWriterAppender. Geode uses a lot of concurrent threads that are executing code with log statements; these threads may be logging while the Geode appenders are being stopped. -- Geode's default log4j2.xml specifies `shutdownHook="disable"` because Geode has a shutdown hook which disconnects the DistributedSystem and closes the Cache, which is executing the code that performs logging. If the Log4J2 shutdown hook stops logging before Geode completes its shutdown, Log4j 2 will attempt to start back up. This restart in turn attempts to register another Log4j 2 shutdown hook which fails resulting in a FATAL level message logged by Log4j 2. -- The GEMFIRE\_VERBOSE marker (Log4J2 Marker are discussed on [http://logging.apache.org/log4j/2.x/manual/markers.html](http://logging.apache.org/log4j/2.x/manual/markers.html)) can be used to enable additional verbose log statements at TRACE level. Many log statements are enabled simply by enabling DEBUG or TRACE. However, even more log statements can be further enabled by using MarkerFilter to accept GEMFIRE\_VERBOSE. The default Geode `log4j2.xml` disables GEMFIRE\_VERBOSE with this line: - - ``` pre - <MarkerFilter marker="GEMFIRE_VERBOSE" onMatch="DENY" onMismatch="NEUTRAL"/> - ``` - - You can enable the GEMFIRE\_VERBOSE log statements by changing `onMatch="DENY"` to `onMatch="ACCEPT"`. Typically, it's more useful to simply enable DEBUG or TRACE on certain classes or packages instead of for the entire Geode product. However, this setting can be used for internal debugging purposes if all other debugging methods fail. - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/84cfbdfc/geode-docs/managing/logging/how_logging_works.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/managing/logging/how_logging_works.html.md.erb b/geode-docs/managing/logging/how_logging_works.html.md.erb deleted file mode 100644 index 22634c6..0000000 --- a/geode-docs/managing/logging/how_logging_works.html.md.erb +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: How Geode Logging Works ---- - -<!-- -Licensed to the Apache Software Foundation (ASF) under one or more -contributor license agreements. See the NOTICE file distributed with -this work for additional information regarding copyright ownership. -The ASF licenses this file to You under the Apache License, Version 2.0 -(the "License"); you may not use this file except in compliance with -the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -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. ---> - -Apache Geode uses Apache Log4j 2 as the basis for its logging system. - -Geode uses [Apache Log4j 2](http://logging.apache.org/log4j/2.x/) API and Core libraries as the basis for its logging system. Log4j 2 API is a popular and powerful front-end logging API used by all the Geode classes to generate log statements. Log4j 2 Core is a backend implementation for logging; you can route any of the front-end logging API libraries to log to this backend. Geode uses the Core backend to run two custom Log4j 2 Appenders: **AlertAppender** and **LogWriterAppender**. - -Geode has been tested with Log4j 2.1. - -**Note:** -For this reason, Geode now always requires the following JARs to be in the classpath: `log4j-api-2.1.jar`, `log4j-core-2.1.jar`. Both of these JARs are distributed in the `$GEMFIRE/lib` directory and included in the appropriate `*-dependencies.jar` convenience libraries. - -**AlertAppender** is the component that generates Geode alerts that are then managed by the JMX Management and Monitoring system. See [Notification Federation](../management/notification_federation_and_alerts.html#topic_212EE5A2ABAB4E8E8EF71807C9ECEF1A) for more details. - -**LogWriterAppender** is the component that is configured by all the `log-*` Geode properties such as `log-file`, `log-file-size-limit` and `log-disk-space-limit`. - -Both of these appenders are created and controlled programmatically. You configure their behavior with the `log-*` Geode properties and the alert level that is configured within the JMX Management & Monitoring system. These appenders do not currently support configuration within a `log4j2.xml` config file. - -Advanced users may wish to define their own `log4j2.xml`. See [Advanced UsersâConfiguring Log4j 2 for Geode](configuring_log4j2.html) for more details. - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/84cfbdfc/geode-docs/managing/logging/log_collection_utility.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/managing/logging/log_collection_utility.html.md.erb b/geode-docs/managing/logging/log_collection_utility.html.md.erb deleted file mode 100644 index e83634f..0000000 --- a/geode-docs/managing/logging/log_collection_utility.html.md.erb +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: Log Collection Utility ---- - -<!-- -Licensed to the Apache Software Foundation (ASF) under one or more -contributor license agreements. See the NOTICE file distributed with -this work for additional information regarding copyright ownership. -The ASF licenses this file to You under the Apache License, Version 2.0 -(the "License"); you may not use this file except in compliance with -the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -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. ---> - -To aid in the troubleshooting of Apache Geode issues, you can use the provided log collection utility to gather and upload log files and other troubleshooting artifacts. This tool is only supported on Linux machines. - -This utility is used to gather log files and other troubleshooting artifacts from a Geode cluster. - -The tool goes through and collects all files ending with `.log`, `.err`, .`cfg`, `.gfs`, `.stack`, `.xml`, `.properties,` and `.txt` from the working directories of running Geode processes. It also obtains thread dumps for each Geode process but will not collect heap dumps. - -The collection utility copies all log and artifact files to its host machine and then compresses all the files. You should ensure that the machine running the utility has sufficient disk space to hold all the collected log and artifact files from the cluster. - -In default mode, the tool requires that a Geode process is running on each machine where the tool is gathering logs and artifact files. If you would like to collect log and artifact files from a machine or machines where Geode processes are not running, use *Static Copy Mode* by specifying the `-m` option and providing a file that lists log and artifact file locations. - -The utility is provided in `$GEMFIRE/tools/LogCollectionUtility`. - -## Usage - -``` pre -java -jar gfe-logcollect.jar -c <company> -o <output dir> [OPTIONS] - -Required arguments: - -c company name to append to output filename - -o output directory to store all collected log files - -Optional arguments: - -a comma separated list of hosts with no spaces. EG. host1,host2,host3 (defaults to localhost) - -u username to use to connect via ssh (defaults to current user) - -i identity file to use for PKI based ssh (defaults to ~/.ssh/id_[dsa|rsa] - -p prompt for a password to use for ssh connections - -t ticket number to append to created zip file - -d don't clean up collected log files after the zip has been created - -s send the zip file to Pivotal support - -f ftp server to upload collected logs to. Defaults to ftp.gemstone.com - -v print version of this utility - -h print this help information - -Static Copy Mode - -m <file> Use a file with log locations instead of scanning for logs. - Entries should be in the format hostname:/log/location -``` - -## Known Limitations - -The following are known limitations with the tool: - -1. Only supports Linux hosts. -2. Requires SSH access between machines. -3. Requires that the username be the same for each host that this app scans. For example, you can't specify user@host1, anotherUser@host2, etc. -4. Requires that SSH access is available across all hosts using either the same password or the same public key. -5. In order to get stacks using jstack, this process must be ran as the same user who owns the Geode process. -6. Requires 'jps' (typically in $JAVA\_HOME/bin) to be in the user's PATH on each machine. - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/84cfbdfc/geode-docs/managing/logging/logging.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/managing/logging/logging.html.md.erb b/geode-docs/managing/logging/logging.html.md.erb deleted file mode 100644 index db4de7e..0000000 --- a/geode-docs/managing/logging/logging.html.md.erb +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Logging ---- - -<!-- -Licensed to the Apache Software Foundation (ASF) under one or more -contributor license agreements. See the NOTICE file distributed with -this work for additional information regarding copyright ownership. -The ASF licenses this file to You under the Apache License, Version 2.0 -(the "License"); you may not use this file except in compliance with -the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -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. ---> - -Comprehensive logging messages help you confirm system configuration and debug problems in configuration and code. - -- **[How Geode Logging Works](../../managing/logging/how_logging_works.html)** - - Apache Geode uses Apache Log4j 2 as the basis for its logging system. - -- **[Understanding Log Messages and Their Categories](../../managing/logging/logging_categories.html)** - - System logging messages typically pertain to startup; logging management; connection and system membership; distribution; or cache, region, and entry management. - -- **[Naming, Searching, and Creating Log Files](../../managing/logging/logging_whats_next.html)** - - The best way to manage and understand the logs is to have each member log to its own files. - -- **[Set Up Logging](../../managing/logging/setting_up_logging.html)** - - You configure logging in a member's `gemfire.properties` or at startup with `gfsh`. - -- **[Advanced UsersâConfiguring Log4j 2 for Geode](../../managing/logging/configuring_log4j2.html)** - - Basic Geode logging configuration is configured via the gemfire.properties file. This topic is intended for advanced users who need increased control over logging due to integration with third-party libraries. - -- **[Log Collection Utility](../../managing/logging/log_collection_utility.html)** - - To aid in the troubleshooting of Apache Geode issues, you can use the provided log collection utility to gather and upload log files and other troubleshooting artifacts. This tool is only supported on Linux machines. - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/84cfbdfc/geode-docs/managing/logging/logging_categories.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/managing/logging/logging_categories.html.md.erb b/geode-docs/managing/logging/logging_categories.html.md.erb deleted file mode 100644 index 6dc94fa..0000000 --- a/geode-docs/managing/logging/logging_categories.html.md.erb +++ /dev/null @@ -1,247 +0,0 @@ ---- -title: Understanding Log Messages and Their Categories ---- - -<!-- -Licensed to the Apache Software Foundation (ASF) under one or more -contributor license agreements. See the NOTICE file distributed with -this work for additional information regarding copyright ownership. -The ASF licenses this file to You under the Apache License, Version 2.0 -(the "License"); you may not use this file except in compliance with -the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -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. ---> - -System logging messages typically pertain to startup; logging management; connection and system membership; distribution; or cache, region, and entry management. - -- **Startup information**. Describe the Java version, the Geode native version, the host system, current working directory, and environment settings. These messages contain all information about the system and configuration the process is running with. -- **Logging management**. Pertain to the maintenance of the log files themselves. This information is always in the main log file (see the discussion at Log File Name). -- **Connections and system membership**. Report on the arrival and departure of distributed system members (including the current member) and any information related to connection activities or failures. This includes information on communication between tiers in a hierarchical cache. -- **Distribution**. Report on the distribution of data between system members. These messages include information about region configuration, entry creation and modification, and region and entry invalidation and destruction. -- **Cache, region, and entry management**. Cache initialization, listener activity, locking and unlocking, region initialization, and entry updates. - -## <a id="how_logging_works__section_578DFE8DD92F4237A8571593EAC9C3B1" class="no-quick-link"></a>Structure of a Log Message - -Every logged message contains: - -- The message header within square brackets: - 1. The message level - 2. The time the message was logged - 3. The ID of the connection and thread that logged the message, which might be the main program or a system management process -- The message itself, which can be a string and/or an exception with the exception stack trace - -``` pre -[config 2005/11/08 15:46:08.710 PST PushConsumer main nid=0x1] -Cache initialized using "file:/Samples/quickstart/xml/PushConsumer.xml". -``` - -## <a id="how_logging_works__section_43A099C67FF04A1EB0A07B617D653A38" class="no-quick-link"></a>Log File Name - -Specify your Geode system member's main log in the gemfire property `log-file` setting. - -Geode uses this name for the most recent log file, actively in use if the member is running, or used for the last run. Geode creates the main log file when the application starts. - -By default, the main log contains the entire log for the member session. If you specify a `log-file-size-limit`, Geode splits the logging into these files: - -- **The main, current log**. Holding current logging entries. Named with the string you specified in `log-file`. -- **Child logs**. Holding older logging entries. These are created by renaming the main, current log when it reaches the size limit. -- **A metadata log file, with `meta-` prefixed to the name**. Used to track of startup, shutdown, child log management, and other logging management operations - -The current log is renamed, or rolled, to the next available child log when the specified size limit is reached. - -When your application connects with logging enabled, it creates the main log file and, if required, the `meta-` log file. If the main log file is present when the member starts up, it is renamed to the next available child log to make way for new logging. - -Your current, main log file always has the name you specified in `log-file`. The old log files and child log files have names derived from the main log file name. These are the pieces of a renamed log or child log file name where `filename.extension` is the `log-file` specification - -<img src="../../images/logging-1.gif" id="how_logging_works__image_A144E5195FDA49A1A8914F233495BA88" class="image" /> - -If child logs are not used, the child file sequence number is a constant 00 (two zeros). - -For locators, the log file name is fixed. For the standalone locator started in `gfsh`, it is always named `<locator_name>.log` where the locator\_name corresponds to the name specified at locator startup. For the locator that runs colocated inside another member, the log file is the memberâs log file. - -For applications and the servers, your log file specification can be relative or absolute. If no file is specified, the defaults are standard output for applications and `<server_name>.log` for servers started with gfsh and `cacheserver.log` for servers started with the older cacheserver script. - -To figure out the member's most recent activities, look at the `meta-` log file or, if no meta file exists, the main log file. - -## <a id="how_logging_works__section_D464FDFFC30141F385689A47CE5E8D38" class="no-quick-link"></a>How the System Renames Logs - -The log file that you specify is the base name used for all logging and logging archives. If a log file with the specified name already exists at startup, the distributed system automatically renames it before creating the current log file. This is a typical directory listing after a few runs with `log-file=system.log`: - -``` pre -bash-2.05$ ls -tlra system* --rw-rw-r-- 1 jpearson users 11106 Nov 3 11:07 system-01-00.log --rw-rw-r-- 1 jpearson users 11308 Nov 3 11:08 system-02-00.log --rw-rw-r-- 1 jpearson users 11308 Nov 3 11:09 system.log -bash-2.05$ -``` - -The first run created `system.log` with a timestamp of Nov 3 11:07. The second run renamed that file to `system-01-00.log` and created a new `system.log` with a timestamp of Nov 3 11:08. The third run renamed that file to `system-02-00.log` and created the file named `system.log` in this listing. - -When the distributed system renames the log file, it assigns the next available number to the new file, as XX of `filename-XX-YY.extension`. This next available number depends on existing old log files and also on any old statistics archives. The system assigns the next number that is higher than any in use for statistics or logging. This keeps current log files and statistics archives paired up regardless of the state of the older files in the directory. Thus, if an application is archiving statistics and logging to `system.log` and `statArchive.gfs`, and it runs in a Unix directory with these files: - -``` pre -bash-2.05$ ls -tlr stat* system* --rw-rw-r-- 1 jpearson users 56143 Nov 3 11:07 statArchive-01-00.gfs --rw-rw-r-- 1 jpearson users 56556 Nov 3 11:08 statArchive-02-00.gfs --rw-rw-r-- 1 jpearson users 56965 Nov 3 11:09 statArchive-03-00.gfs --rw-rw-r-- 1 jpearson users 11308 Nov 3 11:27 system-01-00.log --rw-rw-r-- 1 jpearson users 59650 Nov 3 11:34 statArchive.gfs --rw-rw-r-- 1 jpearson users 18178 Nov 3 11:34 system.log -``` - -the directory contents after the run look like this (changed files in **bold**): - -``` pre -bash-2.05$ ls -ltr stat* system* --rw-rw-r-- 1 jpearson users 56143 Nov 3 11:07 statArchive-01-00.gfs --rw-rw-r-- 1 jpearson users 56556 Nov 3 11:08 statArchive-02-00.gfs --rw-rw-r-- 1 jpearson users 56965 Nov 3 11:09 statArchive-03-00.gfs --rw-rw-r-- 1 jpearson users 11308 Nov 3 11:27 system-01-00.log --rw-rw-r-- 1 jpearson users 59650 Nov 3 11:34 statArchive-04-00.gfs --rw-rw-r-- 1 jpearson users 18178 Nov 3 11:34 system-04-00.log --rw-rw-r-- 1 jpearson users 55774 Nov 4 10:08 statArchive.gfs --rw-rw-r-- 1 jpearson users 17681 Nov 4 10:08 system.log - -``` - -The statistics and the log file are renamed using the next integer that is available to both, so the log file sequence jumps past the gap in this case. - -## <a id="how_logging_works__section_02D8D53AC740490D842C6525FA7DB815" class="no-quick-link"></a>Log Level - -The higher the log level, the more important and urgent the message. If you are having problems with your system, a first-level approach is to lower the log-level (thus sending more of the detailed messages to the log file) and recreate the problem. The additional log messages often help uncover the source. - -These are the levels, in descending order, with sample output: - -- **severe (highest level)**. This level indicates a serious failure. In general, severe messages describe events that are of considerable importance that will prevent normal program execution. You will likely need to shut down or restart at least part of your system to correct the situation. - - This severe error was produced by configuring a system member to connect to a non-existent locator: - - ``` pre - [severe 2005/10/24 11:21:02.908 PDT nameFromGemfireProperties - DownHandler (FD_SOCK) nid=0xf] GossipClient.getInfo(): - exception connecting to host localhost:30303: - java.net.ConnectException: Connection refused - ``` - -- **error**. This level indicates that something is wrong in your system. You should be able to continue running, but the operation noted in the error message failed. - - This error was produced by throwing a `Throwable` from a `CacheListener`. While dispatching events to a customer-implemented cache listener, Geode catches any `Throwable` thrown by the listener and logs it as an error. The text shown here is followed by the output from the `Throwable` itself. - - ``` pre - [error 2007/09/05 11:45:30.542 PDT gemfire1_newton_18222 - <vm_2_thr_5_client1_newton_18222-0x472e> nid=0x6d443bb0] - Exception occurred in CacheListener - ``` - -- **warning**. This level indicates a potential problem. In general, warning messages describe events that are of interest to end users or system managers, or that indicate potential problems in the program or system. - - This message was obtained by starting a client with a Pool configured with queueing enabled when there was no server running to create the clientâs queue: - - ``` pre - [warning 2008/06/09 13:09:28.163 PDT <queueTimer-client> tid=0xe] - QueueManager - Could not create a queue. No queue servers available - ``` - - This message was obtained by trying to get an entry in a client region while there was no server running to respond to the client request: - - ``` pre - [warning 2008/06/09 13:12:31.833 PDT <main> tid=0x1] Unable to create a - connection in the allowed time - org.apache.geode.cache.client.NoAvailableServersException - at org.apache.geode.cache.client.internal.pooling.ConnectionManagerImpl. - borrowConnection(ConnectionManagerImpl.java:166) - . . . - org.apache.geode.internal.cache.LocalRegion.get(LocalRegion.java:1122 - ) - ``` - -- **info**. This is for informational messages, typically geared to end users and system administrators. - - This is a typical info message created at system member startup. This indicates that no other `DistributionManager`s are running in the distributed system, which means no other system members are running: - - ``` pre - [info 2005/10/24 11:51:35.963 PDT CacheRunner main nid=0x1] - DistributionManager straw(7368):41714 started on 192.0.2.0[10333] - with id straw(7368):41714 (along with 0 other DMs) - ``` - - When another system member joins the distributed system, these info messages are output by the members that are already running: - - ``` pre - [info 2005/10/24 11:52:03.934 PDT CacheRunner P2P message reader for - straw(7369):41718 nid=0x21] Member straw(7369):41718 has joined the - distributed cache. - ``` - - When another member leaves because of an interrupt or through normal program termination: - - ``` pre - [info 2005/10/24 11:52:05.128 PDT CacheRunner P2P message reader for - straw(7369):41718 nid=0x21] Member straw(7369):41718 has left the - distributed cache. - ``` - - And when another member is killed: - - ``` pre - [info 2005/10/24 13:08:41.389 PDT CacheRunner DM-Puller nid=0x1b] Member - straw(7685):41993 has unexpectedly left the distributed cache. - ``` - -- **config**. This is the default setting for logging. This level provides static configuration messages that are often used to debug problems associated with particular configurations. - - You can use this config message to verify your startup configuration: - - ``` pre - [config 2008/08/08 14:28:19.862 PDT CacheRunner <main> tid=0x1] Startup Configuration: - ack-severe-alert-threshold="0" - ack-wait-threshold="15" - archive-disk-space-limit="0" - archive-file-size-limit="0" - async-distribution-timeout="0" - async-max-queue-size="8" - async-queue-timeout="60000" - bind-address="" - cache-xml-file="cache.xml" - conflate-events="server" - conserve-sockets="true" - ... - socket-buffer-size="32768" - socket-lease-time="60000" - ssl-ciphers="any" - ssl-enabled="false" - ssl-protocols="any" - ssl-require-authentication="true" - start-locator="" - statistic-archive-file="" - statistic-sample-rate="1000" - statistic-sampling-enabled="false" - tcp-port="0" - udp-fragment-size="60000" - udp-recv-buffer-size="1048576" - udp-send-buffer-size="65535" - ``` - -- **fine**. This level provides tracing information that is generally of interest to developers. It is used for the lowest volume, most important, tracing messages. - - **Note:** - Generally, you should only use this level if instructed to do so by technical support. At this logging level, you will see a lot of noise that might not indicate a problem in your application. This level creates very verbose logs that may require significantly more disk space than the higher levels. - - ``` pre - [fine 2011/06/21 11:27:24.689 PDT <locatoragent_ds_w1-gst-dev04_2104> tid=0xe] SSL Configuration: - ssl-enabled = false - ``` - -- **finer, finest, and all**. These levels exist for internal use only. They produce a large amount of data and so consume large amounts of disk space and system resources. - **Note:** - Do not use these settings unless asked to do so by technical support. - -**Note:** -Geode no longer supports setting system properties for VERBOSE logging. To enable VERBOSE logging, see [Advanced UsersâConfiguring Log4j 2 for Geode](configuring_log4j2.html) http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/84cfbdfc/geode-docs/managing/logging/logging_whats_next.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/managing/logging/logging_whats_next.html.md.erb b/geode-docs/managing/logging/logging_whats_next.html.md.erb deleted file mode 100644 index 4af7de0..0000000 --- a/geode-docs/managing/logging/logging_whats_next.html.md.erb +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Naming, Searching, and Creating Log Files ---- - -<!-- -Licensed to the Apache Software Foundation (ASF) under one or more -contributor license agreements. See the NOTICE file distributed with -this work for additional information regarding copyright ownership. -The ASF licenses this file to You under the Apache License, Version 2.0 -(the "License"); you may not use this file except in compliance with -the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -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. ---> - -The best way to manage and understand the logs is to have each member log to its own files. - -## <a id="logging_whats_next__section_82C0D09E8A414693A7E6342E30209FC4" class="no-quick-link"></a>Log File Naming Recommendation - -For members running on the same machine, you can have them log to their own files by starting them in different working directories and using the same, relative `log-file` specification. For example, you could set this in `<commonDirectoryPath>/gemfire.properties`: - -``` pre -log-file=./log/member.log -``` - -then start each member in a different directory with this command, which points to the common properties file: - -``` pre -java -DgemfirePropertyFile=<commonDirectoryPath>/gemfire.properties -``` - -This way, each member has its own log files under its own working directory. - -## <a id="logging_whats_next__section_5502E3248A424E978B13B1142360F445" class="no-quick-link"></a>Searching the Log Files - -For the clearest picture, merge the log files, with the `gfsh export logs` command: - -``` pre -gfsh> export logs --dir=myDir --dir=myDir --merge-log=true -``` - -Search for lines that begin with these strings: - -- \[warning -- \[error -- \[severe - -## <a id="logging_whats_next__section_32F26033A2134525BCC10F3A6C6FAD7B" class="no-quick-link"></a>Creating Your Own Log Messages - -In addition to the system logs, you can add your own application logs from your Java code. For information on adding custom logging to your applications, see the online Java documentation for the `org.apache.geode.LogWriter` interface. Both system and application logging is output and stored according to your logging configuration settings. http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/84cfbdfc/geode-docs/managing/logging/setting_up_logging.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/managing/logging/setting_up_logging.html.md.erb b/geode-docs/managing/logging/setting_up_logging.html.md.erb deleted file mode 100644 index f2ab52e..0000000 --- a/geode-docs/managing/logging/setting_up_logging.html.md.erb +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: Set Up Logging ---- - -<!-- -Licensed to the Apache Software Foundation (ASF) under one or more -contributor license agreements. See the NOTICE file distributed with -this work for additional information regarding copyright ownership. -The ASF licenses this file to You under the Apache License, Version 2.0 -(the "License"); you may not use this file except in compliance with -the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -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. ---> - -You configure logging in a member's `gemfire.properties` or at startup with `gfsh`. - -<a id="setting_up_logging__section_35F8A9028A91441785BCACD6CD40A498"></a> -Before you begin, make sure you understand [Basic Configuration and Programming](../../basic_config/book_intro.html). - -1. Run a time synchronization service such as NTP on all Geode host machines. This is the only way to produce logs that are useful for troubleshooting. Synchronized time stamps ensure that log messages from different hosts can be merged to accurately reproduce a chronological history of a distributed run. -2. Use a sniffer to monitor your logs Look for new or unexpected warnings, errors, or severe messages. The logs output by your system have their own characteristics, indicative of your system configuration and of the particular behavior of your applications, so you must become familiar with your applications' logs to use them effectively. -3. Configure member logging in each member's `gemfire.properties` as needed: - - ``` pre - # Default gemfire.properties log file settings - log-level=config - log-file= - log-file-size-limit=0 - log-disk-space-limit=0 - ``` - - **Note:** - You can also specify logging parameters when you start up members (either locators or servers) using the `gfsh` command-line utility. In addition, you can modify log file properties and log-level settings while a member is already running by using the [alter runtime](../../tools_modules/gfsh/command-pages/alter.html#topic_7E6B7E1B972D4F418CB45354D1089C2B) command. - - 1. Set `log-level`. Options are `severe` (the highest level), `error`, `warning`, `info`, `config`, and `fine`. The lower levels include higher level settings, so a setting of `warning` would log `warning`, `error`, and `severe` messages. For general troubleshooting, we recommend setting the log level at `config` or higher. The `fine` setting can fill up disk rather quickly and impact system performance. Use `fine` only if necessary. - - 2. Specify the log file name in `log-file`. This can be relative or absolute. If this property is not specified, the defaults are: - - Standard output for applications - - For servers, the default log file location is: - - ``` pre - working-directory/server-name.log - ``` - - By default, when starting a server through `gfsh`, the *working -directory* corresponds to the directory (named after itself) that the cache server creates upon startup. Alternatively, you can specify a different working directory path when you start the cache server. The *server-name* corresponds to the name of the cache server provided upon startup. - - For a standalone locator, the default log file location is: - - ``` pre - working-directory/locator-name.log - ``` - - By default, when starting a locator through `gfsh`, the *working -directory* corresponds to the directory (named after itself) created when the locator starts up. Alternatively, you can specify a different working directory path when you start a locator. The *locator-name* corresponds to the name of the locator provided upon startup. If you are using a colocated or embedded locator, the locator logs will be part of the memberâs log file. - - For the easiest logs examination and troubleshooting, send your logs to files instead of standard out. - **Note:** - Make sure each member logs to its own files. This makes the logs easier to decipher. - - 3. Set the maximum size of a single log file in `log-file-size-limit`. If not set, the single, main log file is used. If set, the metadata file, the main log, and rolled child logs are used. - 4. Set the maximum size of all log files in `log-disk-space-limit`. If non-zero, this limits the combined size of all inactive log files, deleting oldest files first to stay under the limit. A zero setting indicates no limit. - -4. If you are using the `gfsh` command-line interface, `gfsh` can creates its own log file in the directory where you run the `gfsh` or `gfsh.bat` script. By default, gfsh does not generate log files for itself. To enable gfsh logs, set the following system property to the desired log level before starting gfsh: - - ``` pre - export JAVA_ARGS=-Dgfsh.log-level=[severe|warning|info|config|fine|finer|finest] - ``` - - gfsh log files are named `gfsh-0_0.log`. - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/84cfbdfc/geode-docs/managing/management/configuring_rmi_connector.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/managing/management/configuring_rmi_connector.html.md.erb b/geode-docs/managing/management/configuring_rmi_connector.html.md.erb deleted file mode 100644 index 5b29149..0000000 --- a/geode-docs/managing/management/configuring_rmi_connector.html.md.erb +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Configuring RMI Registry Ports and RMI Connectors ---- - -<!-- -Licensed to the Apache Software Foundation (ASF) under one or more -contributor license agreements. See the NOTICE file distributed with -this work for additional information regarding copyright ownership. -The ASF licenses this file to You under the Apache License, Version 2.0 -(the "License"); you may not use this file except in compliance with -the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -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. ---> - -Geode programmatically emulates out-of-the-box JMX provided by Java and creates a JMXServiceURL with RMI Registry and RMI Connector ports on all manageable members. - -## <a id="concept_BC793A7ACF9A4BD9A29C2DCC6894767D__section_143531EBBCF94033B8058FCF5F8A5A0D" class="no-quick-link"></a>Configuring JMX Manager Port and Bind Addresses - -You can configure a specific connection port and address when launching a process that will host the Geode JMX Manager. To do this, specify values for the `jmx-manager-bind-address`, which specifies the JMX manager's IP address and `jmx-manager-port`, which defines the RMI connection port. - -The default Geode JMX Manager RMI port is 1099. You may need to modify this default if 1099 is reserved for other uses. - -## <a id="concept_BC793A7ACF9A4BD9A29C2DCC6894767D__section_BF6352A05CE94F35A8355232D22AC2BC" class="no-quick-link"></a>Using Out-of-the-Box RMI Connectors - -If for some reason you need to use standard JMX RMI in your deployment for other monitoring purposes, set the Geode property `jmx-manager-port` to 0 on any members where you want to use standard JMX RMI. - -If you use out-of-the-box JMX RMI instead of starting an embedded Geode JMX Manager, you should consider setting `-Dsun.rmi.dgc.server.gcInterval=Long.MAX_VALUE-1` when starting the JVM for customer applications and client processes. Every Geode process internally sets this setting before creating and starting the JMX RMI connector in order to prevent full garbage collection from pausing processes. http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/84cfbdfc/geode-docs/managing/management/gfsh_and_management_api.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/managing/management/gfsh_and_management_api.html.md.erb b/geode-docs/managing/management/gfsh_and_management_api.html.md.erb deleted file mode 100644 index e7ee5c2..0000000 --- a/geode-docs/managing/management/gfsh_and_management_api.html.md.erb +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: Executing gfsh Commands through the Management API ---- - -<!-- -Licensed to the Apache Software Foundation (ASF) under one or more -contributor license agreements. See the NOTICE file distributed with -this work for additional information regarding copyright ownership. -The ASF licenses this file to You under the Apache License, Version 2.0 -(the "License"); you may not use this file except in compliance with -the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -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. ---> - -You can also use management APIs to execute gfsh commands programmatically. - -**Note:** -If you start the JMX Manager programmatically and wish to enable command processing, you must also add the absolute path of `gfsh-dependencies.jar` (located in `$GEMFIRE/lib` of your Geode installation) to the CLASSPATH of your application. Do not copy this library to your CLASSPATH because this library refers to other dependencies in `$GEMFIRE/lib` by a relative path. The following code samples demonstrate how to process and execute `gfsh` commands using the Java API. - -First, retrieve a CommandService instance. - -**Note:** -The CommandService API is currently only available on JMX Manager nodes. - -``` pre -// Get existing CommandService instance or create new if it doesn't exist -commandService = CommandService.createLocalCommandService(cache); - -// OR simply get CommandService instance if it exists, don't create new one -CommandService commandService = CommandService.getUsableLocalCommandService(); -``` - -Next, process the command and its output: - -``` pre -// Process the user specified command String -Result regionListResult = commandService.processCommand("list regions"); - -// Iterate through Command Result in String form line by line -while (regionListResult.hasNextLine()) { - System.out.println(regionListResult.nextLine()); -} - -``` - -Alternatively, instead of processing the command, you can create a CommandStatement Object from the command string which can be re-used. - -``` pre -// Create a command statement that can be reused multiple times -CommandStatement showDeadLocksCmdStmt = commandService.createCommandStatement - ("show dead-locks --file=deadlock-info.txt"); -Result showDeadlocksResult = showDeadLocksCmdStmt.process(); - -// If there is a file as a part of Command Result, it can be saved -// to a specified directory -if (showDeadlocksResult.hasIncomingFiles()) { - showDeadlocksResult.saveIncomingFiles(System.getProperty("user.dir") + - "/commandresults"); -} -``` - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/84cfbdfc/geode-docs/managing/management/jmx_manager_node.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/managing/management/jmx_manager_node.html.md.erb b/geode-docs/managing/management/jmx_manager_node.html.md.erb deleted file mode 100644 index 97ca066..0000000 --- a/geode-docs/managing/management/jmx_manager_node.html.md.erb +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: JMX Manager Operations ---- - -<!-- -Licensed to the Apache Software Foundation (ASF) under one or more -contributor license agreements. See the NOTICE file distributed with -this work for additional information regarding copyright ownership. -The ASF licenses this file to You under the Apache License, Version 2.0 -(the "License"); you may not use this file except in compliance with -the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -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. ---> -<a id="topic_36C918B4202D45F3AC225FFD23B11D7C"></a> - - -Any member can host an embedded JMX Manager, which provides a federated view of all MBeans for the distributed system. The member can be configured to be a manager at startup or anytime during its life by invoking the appropriate API calls on the ManagementService. - -You need to have a JMX Manager started in your distributed system in order to use Geode management and monitoring tools such as [gfsh](../../tools_modules/gfsh/chapter_overview.html) and [Geode Pulse](../../tools_modules/pulse/chapter_overview.html). - -**Note:** -Each node that acts as the JMX Manager has additional memory requirements depending on the number of resources that it is managing and monitoring. Being a JMX Manager can increase the memory footprint of any process, including locator processes. See [Memory Requirements for Cached Data](../../reference/topics/memory_requirements_for_cache_data.html#calculating_memory_requirements) for more information on calculating memory overhead on your Geode processes. - -- **[Starting a JMX Manager](jmx_manager_operations.html)** - -- **[Configuring a JMX Manager](jmx_manager_operations.html#topic_263072624B8D4CDBAD18B82E07AA44B6)** - -- **[Stopping a JMX Manager](jmx_manager_operations.html#topic_5B6DF783A14241399DC25C6EE8D0048A)** - -
