Product Documentation : Ehcache Configuration Guide : Sizing Storage Tiers : Built-In Sizing Computation and Enforcement
Built-In Sizing Computation and Enforcement
Internal Ehcache mechanisms track data-element sizes and enforce the limits set by CacheManager sizing pools.
Sizing of Elements
Elements put in a memory-limited cache will have their memory sizes measured. The entire Element instance added to the cache is measured, including key and value, as well as the memory footprint of adding that instance to internal data structures. Key and value are measured as object graphs – each reference is followed and the object reference also measured. This goes on recursively.
Shared references will be measured by each class that references it. This will result in an overstatement. Shared references should therefore be ignored.
Ignoring for Size Calculations
For the purposes of measurement, references can be ignored using the @IgnoreSizeOf annotation. The annotation may be declared at the class level, on a field, or on a package. You can also specify a file containing the fully qualified names of classes, fields, and packages to be ignored.
This annotation is not inherited, and must be added to any subclasses that should also be excluded from sizing.
The following example shows how to ignore the Dog class.
public class Dog {
private Gender gender;
private String name;
The following example shows how to ignore the sharedInstance field.
public class MyCacheEntry {
private final SharedClass sharedInstance;
Packages may be also ignored if you add the @IgnoreSizeOf annotation to appropriate of the desired package. Here is a sample for and in the com.pany.ignore package:
package com.pany.ignore;
import net.sf.ehcache.pool.sizeof.filter.IgnoreSizeOf;
Alternatively, you may declare ignored classes and fields in a file and specify a net.sf.ehcache.sizeof.filter system property to point to that file.
# That field references a common graph between all cached entries
# This will ignore all instances of that type
# This ignores a package
Note that these measurements and configurations apply only to on-heap storage. Once Elements are moved to disk, they are serialized as byte arrays. The serialized size is then used as the basis for measurement.
Configuration for Limiting the Traversed Object Graph
As noted above, sizing caches involves traversing object graphs, a process that can be limited with annotations. This process can also be controlled at both the CacheManager and cache levels.
Size-Of Limitation at the CacheManager Level
Control how deep the size-of engine can go when sizing on-heap elements by adding the following element at the CacheManager level:
<sizeOfPolicy maxDepth="100" maxDepthExceededBehavior="abort"/>
This element has the following attributes
*maxDepth – Controls how many linked objects can be visited before the size-of engine takes any action. This attribute is required.
*maxDepthExceededBehavior – Specifies what happens when the max depth is exceeded while sizing an object graph:
*"continue" – (DEFAULT) Forces the size-of engine to log a warning and continue the sizing operation. If this attribute is not specified, "continue" is the behavior used.
*"abort" – Forces the SizeOf engine to abort the sizing, log a warning, and mark the cache as not correctly tracking memory usage. With this setting, Ehcache.hasAbortedSizeOf() returns true.
The SizeOf policy can be configured at the CacheManager level (directly under <ehcache>) and at the cache level (under <cache> or <defaultCache>). The cache policy always overrides the CacheManager if both are set.
Size-Of Limitation at the Cache level
Use the <sizeOfPolicy> as a sub-element in any <cache> block to control how deep the size-of engine can go when sizing on-heap elements belonging to the target cache. This cache-level setting overrides the CacheManager size-of setting.
Debugging of Size-Of Related Errors
If warnings or errors appear that seem related to size-of measurement (usually caused by the size-of engine walking the graph), generate more log information on sizing activities:
*Set the net.sf.ehcache.sizeof.verboseDebugLogging system property to true.
*Enable debug logs on net.sf.ehcache.pool.sizeof in your chosen implementation of SLF4J.
Copyright © 2010-2015 Software AG, Darmstadt, Germany.

Product Logo |   Feedback