doc/mgr: add docs for missing functions

Some functions had docstrings but were
not linked into plugins.rst, some needed
more text added.

Signed-off-by: John Spray <john.spray@redhat.com>

diff --git a/doc/mgr/plugins.rst b/doc/mgr/plugins.rst
index 8e67819e010d69afcc5ed2f34288b302d821c56c..bc8b5d69b17138f79ac1b263bd4529f3585d96e8 100644 (file)
--- a/doc/mgr/plugins.rst
+++ b/doc/mgr/plugins.rst
@@ -71,6 +71,13 @@ EPERM, or 0 for no error), ``stdout`` is a string containing any
 non-error output, and ``stderr`` is a string containing any progress or
 error explanation output.  Either or both of the two strings may be empty.
 
+Implement the ``handle_command`` function to respond to the commands
+when they are sent:
+
+
+.. py:currentmodule:: mgr_module
+.. automethod:: MgrModule.handle_command
+
 Configuration options
 ---------------------
 
@@ -125,7 +132,6 @@ Hints for using config options:
 * To delete a config value (i.e. revert to default), just pass ``None`` to
   set_config.
 
-.. py:currentmodule:: mgr_module
 .. automethod:: MgrModule.get_config
 .. automethod:: MgrModule.set_config
 .. automethod:: MgrModule.get_localized_config
@@ -187,7 +193,23 @@ function. This will result in a circular locking exception.
 .. automethod:: MgrModule.get_server
 .. automethod:: MgrModule.list_servers
 .. automethod:: MgrModule.get_metadata
+.. automethod:: MgrModule.get_daemon_status
+.. automethod:: MgrModule.get_perf_schema
 .. automethod:: MgrModule.get_counter
+.. automethod:: MgrModule.get_mgr_id
+
+Exposing health checks
+----------------------
+
+Modules can raise first class Ceph health checks, which will be reported
+in the output of ``ceph status`` and in other places that report on the
+cluster's health.
+
+If you use ``set_health_checks`` to report a problem, be sure to call
+it again with an empty dict to clear your health check when the problem
+goes away.
+
+.. automethod:: MgrModule.set_health_checks
 
 What if the mons are down?
 --------------------------
@@ -227,6 +249,40 @@ to the cluster.
 
 .. automethod:: MgrModule.send_command
 
+Receiving notifications
+-----------------------
+
+The manager daemon calls the ``notify`` function on all active modules
+when certain important pieces of cluster state are updated, such as the
+cluster maps.
+
+The actual data is not passed into this function, rather it is a cue for
+the module to go and read the relevant structure if it is interested.  Most
+modules ignore most types of notification: to ignore a notification
+simply return from this function without doing anything.
+
+.. automethod:: MgrModule.notify
+
+Accessing RADOS or CephFS
+-------------------------
+
+If you want to use the librados python API to access data stored in
+the Ceph cluster, you can access the ``rados`` attribute of your
+``MgrModule`` instance.  This is an instance of ``rados.Rados`` which
+has been constructed for you using the existing Ceph context (an internal
+detail of the C++ Ceph code) of the mgr daemon.
+
+Always use this specially constructed librados instance instead of
+constructing one by hand.
+
+Similarly, if you are using libcephfs to access the filesystem, then
+use the libcephfs ``create_with_rados`` to construct it from the
+``MgrModule.rados`` librados instance, and thereby inherit the correct context.
+
+Remember that your module may be running while other parts of the cluster
+are down: do not assume that librados or libcephfs calls will return
+promptly -- consider whether to use timeouts or to block if the rest of
+the cluster is not fully available.
 
 Implementing standby mode
 -------------------------

diff --git a/src/pybind/mgr/mgr_module.py b/src/pybind/mgr/mgr_module.py
index c6ac24ce52d9597e94b8dfffcf73ff6660f058cb..2c27ee2a93911a643d63b8aef63d0055f0742a8b 100644 (file)
--- a/src/pybind/mgr/mgr_module.py
+++ b/src/pybind/mgr/mgr_module.py
@@ -282,6 +282,14 @@ class MgrModule(ceph_module.BaseMgrModule):
         """
         Called by the ceph-mgr service to notify the Python plugin
         that new state is available.
+
+        :param notify_type: string indicating what kind of notification,
+                            such as osd_map, mon_map, fs_map, mon_status,
+                            health, pg_summary, command, service_map
+        :param notify_id:  string (may be empty) that optionally specifies
+                            which entity is being notified about.  With
+                            "command" notifications this is set to the tag
+                            ``from send_command``.
         """
         pass
 
@@ -502,11 +510,11 @@ class MgrModule(ceph_module.BaseMgrModule):
 
     def set_health_checks(self, checks):
         """
-        Set module's health checks
-
         Set the module's current map of health checks.  Argument is a
         dict of check names to info, in this form:
 
+        ::
+
            {
              'CHECK_FOO': {
                'severity': 'warning',           # or 'error'
@@ -545,7 +553,8 @@ class MgrModule(ceph_module.BaseMgrModule):
 
     def get_mgr_id(self):
         """
-        Retrieve the mgr id.
+        Retrieve the name of the manager daemon where this plugin
+        is currently being executed (i.e. the active manager).
 
         :return: str
         """