[DOCU-2246] Provide clearer explanation of defaults and optional properties in documentation of eager-recaching Created: 22/Sep/21  Updated: 19/Oct/21  Resolved: 19/Oct/21

Status: Closed
Project: Documentation
Component/s: None
Affects Version/s: 6.2.9
Fix Version/s: None

Type: Bug Priority: Neutral
Reporter: Marty Glaubitz Assignee: Ashraf Khamis
Resolution: Done Votes: 0
Labels: external
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Attachments: PNG File image-2021-09-22-12-35-40-592.png    
Template:
Acceptance criteria:
Empty
Bug DoR:
[ ]* Steps to reproduce, expected, and actual results filled
[ ]* Affected version filled
Date of First Response:

 Description   

From current documentation it is confusing at first glanc what needs to be configured and what is already provided by default and can be optionally switched off. Separating the two would make documentation easier to read and make it harder for users to make a mistake. For more details see original description of the problem (and misunderstanding) from the user.

 

Original description:

We configured eager-recaching on our server but wondering why the contents of the hitlist were always droped on flushing. After looking into the source code of EagerRecacheFlushPolicy i think i found the problem: the documentation (https://docs.magnolia-cms.com/product-docs/6.2/Modules/List-of-modules/Advanced-cache-modules/Advanced-Cache-Policies-module.html#_eager_re_caching) states to set the property resetAfterUpdate to true. However by the looks of the code:

This leads to the flush policy droping the contents of the Hitlist, thus ignoring the information about the most recently gathered Hits, which is what the policy uses to refresh the cache contents after a flush.

Isn't that what you ideally do not want in your cache configuration? Indeed it looks like, after setting resetAfterUpdate to false, the contents of our cache stay populated now..

 



 Comments   
Comment by Jan Haderka [ 22/Sep/21 ]

That’s what the docu already says, no?

By default, statistics about served pages are retained indefinitely. However, you can force the system to flush the cache after each content update. To do this:

  • Create a resetAfterUpdate property node under flushPolicy.
  • Set the value to true.

Statistics will not be reset, unless you set resetAfterUpdate to true. In other words, if you set this flag, stats will be reset.  Which is what you observed as well. Why do you think the wording is wrong?

Comment by Jan Haderka [ 22/Sep/21 ]

Default value is indeed false as implied by documentation. https://git.magnolia-cms.com/projects/ENTERPRISE/repos/advanced-cache/browse/magnolia-advanced-cache/src/main/java/info/magnolia/module/advancedcache/EagerRecacheFlushPolicy.java#69,172,236-237

Comment by Marty Glaubitz [ 22/Sep/21 ]

@Jan i see, the thing is just when enabling such a feature, one usually just glances over the checklist of things the docs tell you to enable. And this config on the first glance looks like something you have to enable to get things working properly, only when you read again you see its for handling other circumstances.

Maybe its a good idea to introduce a new headline or something like this, to tell apart the configuration that is really required from the optional stuff. 

This might sound nit-picky but might help other people to run into the same mistake

Comment by Jan Haderka [ 22/Sep/21 ]

Hi martyglaubitz thx for the details. Indeed we should differentiate between optional stuff and highlight better that the defaults should be satisfactory for most users already. Thanks for pointing it out.

Comment by Ashraf Khamis [ 19/Oct/21 ]

Hi Marty. Thanks for reporting this issue. I restructured and cleaned up https://docs.magnolia-cms.com/product-docs/6.2/Modules/List-of-modules/Advanced-cache-modules/Advanced-Cache-Policies-module.html#_eager_re_caching. Hope that helps.

Generated at Mon Feb 12 01:25:21 CET 2024 using Jira 9.4.2#940002-sha1:46d1a51de284217efdcb32434eab47a99af2938b.