ceph/doc/mgr/plugins.rst

   1
   2 ceph-mgr plugin author guide
   3 ============================
   4
   5 Creating a plugin
   6 -----------------
   7
   8 In pybind/mgr/, create a python module.  Within your module, create a class
   9 named ``Module`` that inherits from ``MgrModule``.
  10
  11 The most important methods to override are:
  12
  13 * a ``serve`` member function for server-type modules.  This
  14   function should block forever.
  15 * a ``notify`` member function if your module needs to
  16   take action when new cluster data is available.
  17 * a ``handle_command`` member function if your module
  18   exposes CLI commands.
  19
  20 Installing a plugin
  21 -------------------
  22
  23 Once your module is present in the location set by the
  24 ``mgr module path`` configuration setting, add its name
  25 to the ``mgr modules`` configuration setting and restart the ceph-mgr
  26 daemon to load it.
  27
  28 If you're working within a Ceph vstart cluster then your module
  29 should be found in the default pybind/mgr location, and you only
  30 have to add it to ``mgr modules`` to get it loaded.
  31
  32 Note that the MgrModule interface is not stable, so any modules maintained
  33 outside of the Ceph tree are liable to break when run against any newer
  34 or older versions of Ceph.
  35
  36 Logging
  37 -------
  38
  39 MgrModule instances have a ``log`` property which is a logger instance that
  40 sends log messages into the Ceph logging layer where they will be recorded
  41 in the mgr daemon's log file.
  42
  43 Use it the same way you would any other python logger.  The python
  44 log levels debug, info, warn, err are mapped into the Ceph
  45 severities 20, 4, 1 and 0 respectively.
  46
  47 Exposing commands
  48 -----------------
  49
  50 Set the ``COMMANDS`` class attribute of your plugin to a list of dicts
  51 like this::
  52
  53     COMMANDS = [
  54         {
  55             "cmd": "foobar name=myarg,type=CephString",
  56             "desc": "Do something awesome",
  57             "perm": "rw"
  58         }
  59     ]
  60
  61 The ``cmd`` part of each entry is parsed in the same way as internal
  62 Ceph mon and admin socket commands (see mon/MonCommands.h in
  63 the Ceph source for examples)
  64
  65 Config settings
  66 ---------------
  67
  68 Modules have access to a simple key/value store (keys and values are
  69 byte strings) for storing configuration.  Don't use this for
  70 storing large amounts of data.
  71
  72 Config values are stored using the mon's config-key commands.
  73
  74 Hints for using these:
  75
  76 * Reads are fast: ceph-mgr keeps a local in-memory copy
  77 * Don't set things by hand with "ceph config-key", the mgr doesn't update
  78   at runtime (only set things from within modules).
  79 * Writes block until the value is persisted, but reads from another
  80   thread will see the new value immediately.
  81
  82 Any config settings you want to expose to users from your module will
  83 need corresponding hooks in ``COMMANDS`` to expose a setter.
  84
  85 Accessing cluster data
  86 ----------------------
  87
  88 Modules have access to the in-memory copies of the Ceph cluster's
  89 state that the mgr maintains.  Accessor functions as exposed
  90 as members of MgrModule.
  91
  92 Calls that access the cluster or daemon state are generally going
  93 from Python into native C++ routines.  There is some overhead to this,
  94 but much less than for example calling into a REST API or calling into
  95 an SQL database.
  96
  97 There are no consistency rules about access to cluster structures or
  98 daemon metadata.  For example, an OSD might exist in OSDMap but
  99 have no metadata, or vice versa.  On a healthy cluster these
 100 will be very rare transient states, but plugins should be written
 101 to cope with the possibility.
 102
 103 ``get(self, data_name)``
 104
 105 Fetch named cluster-wide objects such as the OSDMap.  Valid things
 106 to fetch are osd_crush_map_text, osd_map, osd_map_tree,
 107 osd_map_crush, config, mon_map, fs_map, osd_metadata, pg_summary,
 108 df, osd_stats, health, mon_status.
 109
 110 All these structures have their own JSON representations: experiment
 111 or look at the C++ dump() methods to learn about them.
 112
 113 ``get_server(self, hostname)``
 114
 115 Fetch metadata about a particular hostname.  This is information
 116 that ceph-mgr has gleaned from the daemon metadata reported
 117 by daemons running on a particular server.
 118
 119 ``list_servers(self)``
 120
 121 Like ``get_server``, but gives information about all servers (i.e. all
 122 unique hostnames that have been mentioned in daemon metadata)
 123
 124 ``get_metadata(self, svc_type, svc_id)``
 125
 126 Fetch the daemon metadata for a particular service.  svc_type is one
 127 of osd or mds, and svc_id is a string (convert OSD integer IDs to strings
 128 when calling this).
 129
 130 ``get_counter(self, svc_type, svc_name, path)``
 131
 132 Fetch the latest performance counter data for a particular counter.  The
 133 path is a period-separated concatenation of the subsystem and the counter
 134 name, for example "mds.inodes".
 135
 136 A list of two-tuples of (timestamp, value) is returned.  This may be
 137 empty if no data is available.
 138
 139 Sending commands
 140 ----------------
 141
 142 A non-blocking facility is provided for sending monitor commands
 143 to the cluster.
 144
 145 ``send_command(self, result, command_str, tag)``
 146
 147 The ``result`` parameter should be an instance of the CommandResult
 148 class, defined in the same module as MgrModule.  This acts as a
 149 completion and stores the output of the command.  Use CommandResult.wait()
 150 if you want to block on completion.
 151
 152 The ``command_str`` parameter is a JSON-serialized command.  This
 153 uses the same format as the ceph command line, which is a dictionary
 154 of command arguments, with the extra ``prefix`` key containing the
 155 command name itself.  Consult MonCommands.h for available commands
 156 and their expected arguments.
 157
 158 The ``tag`` parameter is used for nonblocking operation: when
 159 a command completes, the ``notify()`` callback on the MgrModule
 160 instance is triggered, with notify_type set to "command", and
 161 notify_id set to the tag of the command.
 162
 163
 164 Logging
 165 -------
 166
 167 Use your module's ``log`` attribute as your logger.  This is a logger
 168 configured to output via the ceph logging framework, to the local ceph-mgr
 169 log files.
 170
 171 Python log severities are mapped to ceph severities as follows:
 172
 173 * DEBUG is 20
 174 * INFO is 4
 175 * WARN is 1
 176 * ERR is 0
 177
 178 Shutting down cleanly
 179 ---------------------
 180
 181 If a module implements the ``serve()`` method, it should also implement
 182 the ``shutdown()`` method to shutdown cleanly: misbehaving modules
 183 may otherwise prevent clean shutdown of ceph-mgr.
 184
 185 Is something missing?
 186 ---------------------
 187
 188 The ceph-mgr python interface is not set in stone.  If you have a need
 189 that is not satisfied by the current interface, please bring it up
 190 on the ceph-devel mailing list.  While it is desired to avoid bloating
 191 the interface, it is not generally very hard to expose existing data
 192 to the Python code when there is a good reason.
 193