Moodle
  1. Moodle
  2. MDL-37145

Documentation for caching admin screens

    Details

    • Story Points (Obsolete):
      40
    • Sprint:
      FRONTEND Sprint 12

      Description

      We need to add much more docs to explain what is going on in the caching plugin screens.

      People are complaining about it on the forums:
      https://moodle.org/mod/forum/discuss.php?d=217195

        Gliffy Diagrams

          Issue Links

            Activity

            Hide
            Dan Poltawski added a comment -

            I've added some very basic info to http://docs.moodle.org/24/en/Caching#How_to_use_the_caching_settings

            Some thoughts I had when I was writing it:

            • 'Installed cache stores' could be renamed 'Cache Plugins'?
            • 'Configured store instances' could be encapsulated inside the above table, so you could have a top level Plugin and then instance management under them.
            • 'Known cache definitions' could be renamed something less developery, maybe 'Moodle caches'?
            • 'Stores used when no mapping is present' could be renamed 'Default cache stores' or something like that?
            • 'Stores used when no mapping is present' feels more logical to me above 'Stores used when no mapping is present' (i.e. defaults at top, and then tweak the configuration for individual caches below)
            • 'Summary of cache lock instances.' - is this worth having visible to normal admins? I guess I can't tell because there are no other cache lock instances
            • Do we need 'Rescan definitions' for non-developers?
            Show
            Dan Poltawski added a comment - I've added some very basic info to http://docs.moodle.org/24/en/Caching#How_to_use_the_caching_settings Some thoughts I had when I was writing it: 'Installed cache stores' could be renamed 'Cache Plugins'? 'Configured store instances' could be encapsulated inside the above table, so you could have a top level Plugin and then instance management under them. 'Known cache definitions' could be renamed something less developery, maybe 'Moodle caches'? 'Stores used when no mapping is present' could be renamed 'Default cache stores' or something like that? 'Stores used when no mapping is present' feels more logical to me above 'Stores used when no mapping is present' (i.e. defaults at top, and then tweak the configuration for individual caches below) 'Summary of cache lock instances.' - is this worth having visible to normal admins? I guess I can't tell because there are no other cache lock instances Do we need 'Rescan definitions' for non-developers?
            Hide
            Luciano Silva added a comment -

            I configured memcached in mdl 2.5, but the parameters are not clear. I would appreciate your help improving cache docs.

            Tks

            Show
            Luciano Silva added a comment - I configured memcached in mdl 2.5, but the parameters are not clear. I would appreciate your help improving cache docs. Tks
            Hide
            Dan Poltawski added a comment -

            More people struggling with this in this thread: https://moodle.org/mod/forum/discuss.php?d=251547

            I'm raising the priority to blocker since really this is way past overdue and adding to the backend backlog.

            Show
            Dan Poltawski added a comment - More people struggling with this in this thread: https://moodle.org/mod/forum/discuss.php?d=251547 I'm raising the priority to blocker since really this is way past overdue and adding to the backend backlog.
            Hide
            Mary Cooch added a comment -

            This would be much appreciated as it's not something I understand -if someone wants to add information to the 2.6 docs I am happy to copy and paste over to the others.

            Show
            Mary Cooch added a comment - This would be much appreciated as it's not something I understand -if someone wants to add information to the 2.6 docs I am happy to copy and paste over to the others.
            Hide
            Ankit Agarwal added a comment -

            I will make sure this gets in, in next sprint.

            Show
            Ankit Agarwal added a comment - I will make sure this gets in, in next sprint.
            Hide
            Howard Miller added a comment -

            I hope I don't sound insulting, but this seems to have been created from a "computer science" point of view (i.e., a theoretical understanding of cacheing) as opposed to a practical, end-user viewpoint.

            Caching needs to be straightforward for an average administrator to set up. That is the perspective all naming and help must be written from.

            To make matters worse, in many configurations a mis-configured MUC will kill the performance of a Moodle site so it isn't a "nice to have". This is properly critical stuff and needs some time and thought.

            Show
            Howard Miller added a comment - I hope I don't sound insulting, but this seems to have been created from a "computer science" point of view (i.e., a theoretical understanding of cacheing) as opposed to a practical, end-user viewpoint. Caching needs to be straightforward for an average administrator to set up. That is the perspective all naming and help must be written from. To make matters worse, in many configurations a mis-configured MUC will kill the performance of a Moodle site so it isn't a "nice to have". This is properly critical stuff and needs some time and thought.
            Hide
            Dan Poltawski added a comment -

            Hi Howard,

            Not sure what you are referring to what you say 'this seems to have been created'?

            Show
            Dan Poltawski added a comment - Hi Howard, Not sure what you are referring to what you say 'this seems to have been created'?
            Hide
            Howard Miller added a comment -

            The caching user interface. While I understand that it gives a great deal of flexibility - the terminology will go right over the heads of most users (especially given the lack of help and documentation). It would have been better IMO, to allow certain common scenarios to be selected and then have advanced settings for those that need them.

            Show
            Howard Miller added a comment - The caching user interface. While I understand that it gives a great deal of flexibility - the terminology will go right over the heads of most users (especially given the lack of help and documentation). It would have been better IMO, to allow certain common scenarios to be selected and then have advanced settings for those that need them.
            Hide
            Sam Hemelryk added a comment -

            Ok I've given http://docs.moodle.org/27/en/Caching an overhaul.
            I've also created http://docs.moodle.org/27/en/Cache_definitions

            I still need to add a bit more store specific information.

            Show
            Sam Hemelryk added a comment - Ok I've given http://docs.moodle.org/27/en/Caching an overhaul. I've also created http://docs.moodle.org/27/en/Cache_definitions I still need to add a bit more store specific information.
            Hide
            Andrew Nicols added a comment -

            Notes from my first read through of the Caching page:

            Otherwise, I've made a few typo and grammatical corrections.

            Show
            Andrew Nicols added a comment - Notes from my first read through of the Caching page: http://docs.moodle.org/27/en/Caching#Sharing - Language cache seems like a good example but it can easily be customised through the UI. If moodle admins aren't aware of this ability, it will catch them out. http://docs.moodle.org/27/en/Caching#Stores_used_when_no_mapping_is_present - Not sure what this is meant to say: "Of simply this shows the default cache store instances." http://docs.moodle.org/27/en/Caching#Adding_cache_store_instances - I think that the memcache(d) sections (and potentially mongodb) should re-iterate not to share the same instance between servers Otherwise, I've made a few typo and grammatical corrections.
            Hide
            Andrew Nicols added a comment -

            WRT, the Cache definitions:

            • I wonder whether it's worth stating whether the cache is more read, or write heavy as this may have an effect upon where the information is stored;
            • I think that this wiki is the wrong place to store this information - we should somehow store this alongside each cache definition so that we can display this information in the UI where it is most pertinent - perhaps even generating a report based on the data
            Show
            Andrew Nicols added a comment - WRT, the Cache definitions: I wonder whether it's worth stating whether the cache is more read, or write heavy as this may have an effect upon where the information is stored; I think that this wiki is the wrong place to store this information - we should somehow store this alongside each cache definition so that we can display this information in the UI where it is most pertinent - perhaps even generating a report based on the data
            Hide
            Howard Miller added a comment -

            This is much, much better - thanks. A few points...

            • It still doesn't explain what the difference is between 'Primary' and 'Final' in the store mappings screen. Perhaps it is thought to be obvious, but not to me
            • some reference to troubleshooting might be useful. For example, one I had the other day, MDL-45810, "This store doesn't meet the requirements for all known definitions. Definitions for which this store is inadequate will be given the original default store instead of the selected store". What can that possibly mean? I'm sure there are other errors that need properly documented.
            • Perhaps the Cache Definitions page strays a little too close to developer information at the start.
            • config-dist.php now has a bunch of settings for storing the session handler in memcached added as part of MDL-3150. How does this fit-in (or interfere possibly) with the MUC session caching?
            Show
            Howard Miller added a comment - This is much, much better - thanks. A few points... It still doesn't explain what the difference is between 'Primary' and 'Final' in the store mappings screen. Perhaps it is thought to be obvious, but not to me some reference to troubleshooting might be useful. For example, one I had the other day, MDL-45810 , "This store doesn't meet the requirements for all known definitions. Definitions for which this store is inadequate will be given the original default store instead of the selected store". What can that possibly mean? I'm sure there are other errors that need properly documented. Perhaps the Cache Definitions page strays a little too close to developer information at the start. config-dist.php now has a bunch of settings for storing the session handler in memcached added as part of MDL-3150 . How does this fit-in (or interfere possibly) with the MUC session caching?
            Hide
            Sam Hemelryk added a comment -

            Thanks for the feedback guys.

            Changes I've now made:

            • Language example in sharing section of caching now notes about language customisations.
            • Language cache in caching definitions doc now has a note about sharing and language customisation.
            • Opened MDL-45966 to investigate customlang tool purging of lang cache (or lack of)
            • Fixed up confusion in "Stores used when no mapping is present"
            • I've added implementation notes to memcache and memcached recommending that dedicated memcached servers get used for Moodle caching. Mongo does not suffer from this same fallback.
            • I've tried to further clarify Primary...Final mappings here http://docs.moodle.org/27/en/Caching#Mapping_a_cache_to_a_store_instance. Could you please read through that section and see if it is sufficient in your eyes Howard? If not I will seek help writing it as perhaps I am too close to trees to see the forrest.
            • I've added a troubleshooting section to the caching doc. At present there is nothing in it. I will endeavour to look at the issue you noted Howard but at a glance it looks like a more informative message, or additional output may help.
            • I've amended the start of the cache definitions document to try to better explain why you would be reading this document.

            Noting a couple of things:

            • I don't think there is much point in noting whether a cache is read/write heavy. There should always be more reading than writing. I think the priority thing should take this into account in some ways. A cache that is hit often is read often.
            • Absolutely I agree that the cache UI could be showing more. Time is the issue really. Writing this is got me thinking about how to improve the interfaces and I'll create an issue for that shortly. Really I think the wiki is still important, but having a bit more information in the caching UI would also be extremely useful, so both serve there purpose.

            I hope that covers the points you have raised so far.
            I'm going to copy this document back to the 2.6 docs as nothing has changed in the interfaces between 26 and 27.
            If there is anything more you think should be added to the doc please feel free to add it yourself or ask me and I'll see if I can add it in.

            Thanks
            Sam

            Show
            Sam Hemelryk added a comment - Thanks for the feedback guys. Changes I've now made: Language example in sharing section of caching now notes about language customisations. Language cache in caching definitions doc now has a note about sharing and language customisation. Opened MDL-45966 to investigate customlang tool purging of lang cache (or lack of) Fixed up confusion in "Stores used when no mapping is present" I've added implementation notes to memcache and memcached recommending that dedicated memcached servers get used for Moodle caching. Mongo does not suffer from this same fallback. I've tried to further clarify Primary...Final mappings here http://docs.moodle.org/27/en/Caching#Mapping_a_cache_to_a_store_instance . Could you please read through that section and see if it is sufficient in your eyes Howard? If not I will seek help writing it as perhaps I am too close to trees to see the forrest. I've added a troubleshooting section to the caching doc. At present there is nothing in it. I will endeavour to look at the issue you noted Howard but at a glance it looks like a more informative message, or additional output may help. I've amended the start of the cache definitions document to try to better explain why you would be reading this document. Noting a couple of things: I don't think there is much point in noting whether a cache is read/write heavy. There should always be more reading than writing. I think the priority thing should take this into account in some ways. A cache that is hit often is read often. Absolutely I agree that the cache UI could be showing more. Time is the issue really. Writing this is got me thinking about how to improve the interfaces and I'll create an issue for that shortly. Really I think the wiki is still important, but having a bit more information in the caching UI would also be extremely useful, so both serve there purpose. I hope that covers the points you have raised so far. I'm going to copy this document back to the 2.6 docs as nothing has changed in the interfaces between 26 and 27. If there is anything more you think should be added to the doc please feel free to add it yourself or ask me and I'll see if I can add it in. Thanks Sam
            Show
            Sam Hemelryk added a comment - OK changes have being backported to 2.6 docs. We've got: http://docs.moodle.org/27/en/Caching http://docs.moodle.org/27/en/Cache_definitions http://docs.moodle.org/26/en/Caching http://docs.moodle.org/26/en/Cache_definitions
            Hide
            Sam Hemelryk added a comment -

            I feel the docs are up to standard now. Any objections to me closing this issue now?

            Show
            Sam Hemelryk added a comment - I feel the docs are up to standard now. Any objections to me closing this issue now?
            Hide
            Mary Cooch added a comment -

            Thanks for these; it's much appreciated!

            Show
            Mary Cooch added a comment - Thanks for these; it's much appreciated!
            Hide
            Matteo Scaramuccia added a comment -

            Great work Sam!

            Show
            Matteo Scaramuccia added a comment - Great work Sam!
            Hide
            Howard Miller added a comment -

            This is looking really good. Just a couple of thoughts (sorry to keep piling it on)...

            • I'm still concerned about how the $CFG->... settings (in config-dist.php) for storing sessions in memcached or memcache either fit in or clash. Do these need to be set as well or instead of or something else if memcached/memcache are used?
            • it would be nice to have some practical "starting point" recommendations. There are only really three setups for Moodle that cover about 98% of configurations - 1. Everything on the same box, 2. separate web server and database server, 3. simple load-balanced with multiple web servers and single (or clustered) db - almost certainly with NFS. I do take the point that load-testing and such is important but I think it would be useful to have a starting place that might at least "work".

            Cheers

            Show
            Howard Miller added a comment - This is looking really good. Just a couple of thoughts (sorry to keep piling it on)... I'm still concerned about how the $CFG->... settings (in config-dist.php) for storing sessions in memcached or memcache either fit in or clash. Do these need to be set as well or instead of or something else if memcached/memcache are used? it would be nice to have some practical "starting point" recommendations. There are only really three setups for Moodle that cover about 98% of configurations - 1. Everything on the same box, 2. separate web server and database server, 3. simple load-balanced with multiple web servers and single (or clustered) db - almost certainly with NFS. I do take the point that load-testing and such is important but I think it would be useful to have a starting place that might at least "work". Cheers
            Hide
            Ankit Agarwal added a comment -

            Thanks for the work Sam, this is looking really great.

            Show
            Ankit Agarwal added a comment - Thanks for the work Sam, this is looking really great.
            Hide
            Sam Hemelryk added a comment -

            Alrighty I am putting up for integration review a couple of small, text only changes to config-dist.php and cache/README.md to further note the memcached issues.

            I've created MDL-46096 to improve documentation and get something down as a starting point as you suggested Howard.
            I think that's a worthwhile task but I am out of time and must move onto other tasks.

            Sending this to integration review without a peer-review as its purely text based changes.

            Many thanks
            Sam

            Show
            Sam Hemelryk added a comment - Alrighty I am putting up for integration review a couple of small, text only changes to config-dist.php and cache/README.md to further note the memcached issues. I've created MDL-46096 to improve documentation and get something down as a starting point as you suggested Howard. I think that's a worthwhile task but I am out of time and must move onto other tasks. Sending this to integration review without a peer-review as its purely text based changes. Many thanks Sam
            Hide
            CiBoT added a comment -

            Moving this issue to current integration cycle, will be reviewed soon. Thanks for the hard work!

            Show
            CiBoT added a comment - Moving this issue to current integration cycle, will be reviewed soon. Thanks for the hard work!
            Hide
            Damyon Wiese added a comment -

            Thanks Sam,

            Integrated to 26, 27 and master.

            Show
            Damyon Wiese added a comment - Thanks Sam, Integrated to 26, 27 and master.
            Hide
            Andrew Davis added a comment -

            Notes/docs appear quite helpful. Passing.

            Note that the diff URLs are all 404'ing.

            Show
            Andrew Davis added a comment - Notes/docs appear quite helpful. Passing. Note that the diff URLs are all 404'ing.
            Hide
            Eloy Lafuente (stronk7) added a comment -

            It's always a pleasure to close these issues. Their fixes are now upstream. Great work!

            Ciao

            Show
            Eloy Lafuente (stronk7) added a comment - It's always a pleasure to close these issues. Their fixes are now upstream. Great work! Ciao

              People

              • Votes:
                10 Vote for this issue
                Watchers:
                13 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved:

                  Agile