Deep dive: Cache dependencies

Hi there,

Before you even start reading this post, you should have some knowledge about the Kentico CMS caching and maybe also some API and what is it's current state in Kentico CMS 5.5, you should also be aware about the performance differences you can gain with caching. So the prerequisities are following:

• http://devnet.kentico.com/Blogs/Martin-Hejtmanek/April-2009/Deep-Dive---Kentico-CMS-Caching.aspx
• http://devnet.kentico.com/Blogs/Martin-Hejtmanek/June-2010/New-in-5-5--Caching-API.aspx
• http://www.kentico.com/downloads/KenticoCMS_5_5_Performance.pdf

Version

Types of caching

There are several types of cache that may be on the path to the result that the site visitor gets, I list them in the order they are evaluated which means (in case the particular cache is enabled) that the request attempts to get the data from the cache. If the data is available in the cache, it is used in the higher level. If the data is not available, it is either taken from DB or lower level (depending on the situation and control), and the result is cached for later use by other requests. The page levels are following:

• Full page cache (1)
• Partial cache (2)
• Content cache (3)
• Page info cache (4)

The image cache is standing beside this (isn't related to the output HTML) and I will cover it in some other post.

Cache dependencies

Cache dependency is a single control point that can be used to flush multiple cache items somehow relevant to it. Technically, it is a dummy cache item on which the other (real cache items) are depending. If we look at a sample cache space, we can see the cache items with the data (blue) and the dummy keys (white). You may notice the arrows in there which are the actual cache dependencies in the meaning of "dummy item can influence data item" or "data item is depending on the dummy item".



You may notice that the arrows are always from dummy item to data item, and never the oposite way or between the items of the same type. That serves a purpose that you will learn right now.

If there is some change done to the data, we need to flush everything that possibly contains such data. What happens is we "touch" the dummy cache item. Touching in terms of cache means throwing the dummy cache item away and recreating it. The effect of this is that all the depending cache items (in the direction of arrows are also thrown away which is what we call "flush the cache".



If you are not familiar with how cache and the dependencies in .NET work, I may have a better explanation for you. Imagine that "touching" the dummy item is the same as infecting it with a disease, and that the disease can always spread only in the direction of arrows. So in the end, everything connected to the dummy cache item by a forward arrow gets infected. Unlike the dummy item, that can survive the infection and cure itself, everything else dies (disappears from the cache) while the dummy item stays there, uninfected.



So in the end, only the data items are erased and the new items upon next request connect to the same dummy keys the same way.

This was a simple example, in reality, the cache namespace has many items and different CMS objects provide different dummy keys, but the concept is the same. If you are thinking about cache dependency, you always need to only think this simple: Single dummy key and it's leafs as the data items. When you touch the key, the leafs get deleted. So if you want to make something dependent on something, you just need to know which dummy keys to use, which leads us back to the dummy keys that are touched upon object change from one of my previous post. The table is reviewed for 5.5:

Object	Touched keys	Examples
Document (TreeNode)	node|<sitename>|<aliaspath>|<culture> node|<sitename>|<aliaspath> nodeid|<nodeid> nodeid|<linkednodeid> documentid|<documentid> documentid|<documentid>|attachments nodeguid|<nodeguid> nodes|<sitename>|<classname>|all + for every parent node: node|<sitename>|<aliaspath>|childnodes	node|corporatesite|/home|en-us  node|corporatesite|/home nodeid|12 nodeid|34 documentid|56 documentid|56|attachments nodeguid|1ced44f3-f2fc- ... nodes|corporatesite|cms.menuitem|all node|sitename|/|childnodes
Any object (except document)	<classname>|all <classname>|byid|<id>  <classname>|byname|<codename> <classname>|byguid|<guid>	cms.user|all cms.user|byid|53 cms.user|byname|administrator cms.user|byguid|1ced44f3-f2fc- ...
Metafile	metafile|<guid>	metafile|1ced44f3-f2fc- ...
Document attachment	cms.attachment|all attachment|<guid>  documentid|<documentid>|attachments	cms.attachment|all attachment|1ced44f3-f2fc- ... documentid|56|attachments
Forum attachment	forumattachment|<guid>	forumattachment|1ced44f3-f2fc- ...
Avatar	avatarfile|<guid>	avatarfile|1ced44f3-f2fc- ...
Media file	mediafile|<guid> mediafile|preview|<guid>	mediafile|1ced44f3-f2fc- ... mediafile|preview|1ced44f3-f2fc- ...
Page template	template|<id>	template|12
CacheHelper .ClearFullPageCache	fullpage	fullpage
CacheHelper .ClearPartialCache	partial	partial

Note: The dependencies are always LOWERCASE.

Also note, that for documents under workflow, the keys are touched upon any change to the document since the document consist of both versioned and not-versioned data.

Debug the cache

There are two ways how to debug the cache, one of them is observing the cache items in the cache on the Cache items tab under Debug, this is more static debugging (just look at the cache space without the arrows):



And the other is to enable dynamic debugging of the cache actions using the web.config keys:

<add key="CMSDebugCache" value="true"/>
<add key="CMSDebugCacheLive" value="true"/>
<add key="CMSDebugAllCaches" value="true"/>
<add key="CMSDebugCacheLogLength" value="10"/>
<add key="CMSLogCache" value="true" />
 
And see what happened with the cache on the Cache access tab in the same location or on the live site depending on the settings, more information here: http://devnet.kentico.com/docs/devguide/index.html?cache_debugging.htm



Great thing about Kentico CMS 6.0 which is now under development is that is also provides a list of used dependencies upon ADD action to the cache so it will be even easier to debug.

Very important thing for you is that most of the cache dependencies are covered by default so most of the data is flushed correctly. As you will see in the following text, there are some exceptions that may require your manual work in setting some additional properties if you want this behavior.

Full page cache and it's dependencies (1)

• pageinfo|<sitename>|<aliaspath>|<culture>|<urlpath>|<combinewithdefaultculture> e.g. pageinfo|corporatesite|/home|en-us||true

• Do not use full page caching at all (not recommended)
• Provide a custom cache dependencies specific to your setup (with possibility of worse performance upon change)
• Live with the fact that some pages will not refresh right away and try to avoid such changes on the live web site (recommended), you may help yourselves by either clearing the cache from Site manager in case of some important change or shorten the cache interval to get the changes sooner.

• fullpage
• fullpage|<siteid>|<aliaspath> e.g. fullpage|1|/home
• fullpage|<siteid>|<aliaspath>|<culture> e.g. fullpage|1|/home|en-us
• nodeid|<nodeid> e.g. nodeid|12
• documentid|<documentid> e.g. documentid|56

You can get these by calling method PageInfo.GetResponseCacheDependencies().

You can use them to manually flush some output cache for individual pages.

Partial caching (2)

Partial caching (or also Output caching for controls) is similar to Full page caching, but applies only to fragment of the page (specific control). You can set it up in the web part properties, at the very end of the form:

You cannot control the cache item name since this is purely build on the control Output cache provided by .NET framework.

There is no default dependency on any content (there is no context, value is just string without additional context), just on the web part settings (you change the web part properties, the cache flushes), the system dependency is:

• webpartinstance|<instanceguid>, where instance GUID is unique identifier of the web part on template, you can see it only in the URL of the web part properties dialog or get it through the web part control property. You may need to touch it manually only in case you modify the structure of the page template programatically (I will cover that on my blog sometimes later) and show the changes right away.

You can specify additional dependencies in the web part properties under „Partical caching“ category.

One important thing to note here is that this partial cache relates only to web parts in web part zones in portal engine mode. The partial cache properties are not supported when the web part is used as a standard user control in your own code. If you want to use the partial caching in ASPX mode, you need to use the standard Output cache for controls: http://msdn.microsoft.com/en-us/library/h30h475z.aspx

Content caching (3)

Content caching is caching of the data used by the controls and web parts to populate their content. Typically, it is a DataSet or some object based on the nature of the particular control. The default value can be set in the web site settings:

And it can be overriden in the web part or control properties (if you leave it blank, it will use the web site settings):



The cache item name can be controlled via the property of the web part, this is the only cache type where it actually may make sense to change it, see below.

The default dependencies (only if checked in the web part properties under „System settings“) are typically related to the source of the data (plus there is a dependency on web part settings just as with partial caching). It is always the smallest subset of objects that could possibly be returned as a result, some examples:

Query repeater – No default dependencies, since query can potentially cover anything, there is no relevant context.

Document repeater (CMSRepeater) or other document lists (data sources), including menus

Typically dependency on the section covered by path and document types covered by document type. The dependencies of such document viewer (data source) can be of two types.

If there are specific classes (document types) configured, for each document type:

• nodes|<sitename>|<classname>|all e.g. nodes|corporatesite|cms.menuitem|all

If there are no specific document types defined, the dependencies are based purely on path, in case of list (path ending with /%) it is:

• node|<sitename>|<path>|childnodes, e.g. node|corporatesite|/news|childnodes

In case of single document (detail view):

• node|<sitename>|<path>, e.g. node|corporatesite|/News/News-1

You can get these by calling method TreeProvider.GetDocumentCacheDependencies(...).

As you can see, they are pretty general to cover all possible modifications, so they may ocassionally cause "unwanted" flushes of not related data, if you want to replace them by something more accurate, you need to use custom ones.

Users viewer or other object lists (data sources)

Dependency on change of any object of the given type since any object can be potentially displayed in it, it typically is:

• <classname>|all e.g. cms.user|all

Page info caching

• template|<templateid> e.g. template|12
• nodeid|<nodeid> e.g. nodeid|12
• nodeid|<linkednodeid> e.g. nodeid|34 - only for links
• pageinfo - general key for all page infos

Summary on cache types

• CMSRepeater – Uses caches (1), (2) and (3) in that order (3 because the data is provided by general API in various ways)
• Editable region – Uses caches (1), (2) and (4) in that order (4 because editable content is cached in PageInfo)
• Static text web part – Uses caches (1), (2) and (4) in that order (4 because the web part settings are cached in PageInfo as part of the template structure) 

• In partial caching (2), everything must be done manually if you want to flush the content somehow
• In full page caching (1), it must be done manually if you want to flush other pages than current one

Cache dependencies of the files (images)

Caching of the files works on the same principle, except that the file cache is configured in special setting:

The dependencies is based on the type of file:

• Document attachment (including CMS.File) uses typically dependency on that particular attachment item and also uses Content cache (3) for the related information from the document (the only file cache working with two levels) and it's dependencies.
• Media library file is depending of that single media file and also on the Media library itself
• CSS stylesheet which is also considered a file depends on the stylesheet itself
• Object attachment (meta file) is usually depending on that particular meta file
• Other files are also typically depending on that particular single files

It would be whole new post to cover caching of the files in detail, so I will leave it for some of the next times. The important thing here is that when you do some change, the files get flushed from the cache.

Cache item names

• Ifyou want to merge the same data items used by different controls, and the cache item names aren't the same by default - This may be typical to save some redundant, but is mostly covered from version 5.0:
• If you want to split the data items to the independent ones, but the default cache keys are the same - This may be needed in case you further manipulate the data somehow in one of the locations and do not want the same change in others.

Cache dependencies and API

You should always use the CacheHelper method to work with the cache, only that way, you can get the full support of Kentico CMS cache features including the proper behavior of dummy keys and flushing of the cache or propagating the changes to the cache across web farms. Except for the . The most important parts of it you should know are:

• CachedSection - New caching API in 5.5, totally contention-proof http://devnet.kentico.com/Blogs/Martin-Hejtmanek/June-2010/New-in-5-5--Caching-API.aspx
• ClearCache(null) - To clear all the cache items
• CacheHelper.TouchKey("somekey") - This is how you can manually touch a dummy key and flush depending data
• CacheHelper.GetCacheDependency("somekey") - This is how you can get the cache dependency for your cache item. It basically ensures the dummy keys with the given names and returns the dependency object that you pass to the cache.

Web farms and touch key

Summary

I hope I made the cache dependencies and cache clearer to everyone. If not, let me know what else you need to clarify so I can cover that, too.

See you next time!