[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: |
|
| 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?
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. |