-
-
.. _mgr-module-dev:
ceph-mgr module developer's guide
.. warning::
This is developer documentation, describing Ceph internals that
- are only relevant to people writing ceph-mgr modules.
+ are relevant only to people writing ceph-mgr modules.
Creating a module
-----------------
-In pybind/mgr/, create a python module. Within your module, create a class
+In ``pybind/mgr/``, create a python module. Within your module, create a class
that inherits from ``MgrModule``. For ceph-mgr to detect your module, your
-directory must contain a file called `module.py`.
+directory must contain a file called ``module.py``.
The most important methods to override are:
Installing a module
-------------------
-Once your module is present in the location set by the
-``mgr module path`` configuration setting, you can enable it
-via the ``ceph mgr module enable`` command::
+Once your module is present in the location set by the ``mgr module path``
+configuration setting, you can enable it via the ``ceph mgr module enable``
+command:
- ceph mgr module enable mymodule
+.. prompt:: bash #
+
+ ceph mgr module enable mymodule
Note that the MgrModule interface is not stable, so any modules maintained
outside of the Ceph tree are liable to break when run against any newer
Each module has a ``log_level`` option that specifies the current Python
logging level of the module.
+
To change or query the logging level of the module use the following Ceph
-commands::
+commands:
- ceph config get mgr mgr/<module_name>/log_level
- ceph config set mgr mgr/<module_name>/log_level <info|debug|critical|error|warning|>
+.. prompt:: bash #
+
+ ceph config get mgr mgr/<module_name>/log_level
+ ceph config set mgr mgr/<module_name>/log_level <info|debug|critical|error|warning|>
The logging level used upon the module's start is determined by the current
logging level of the mgr daemon, unless if the ``log_level`` option was
* <= +inf is DEBUG
We can unset the module log level and fallback to the mgr daemon logging level
-by running the following command::
+by running the following command:
+
+.. prompt:: bash #
- ceph config set mgr mgr/<module_name>/log_level ''
+ ceph config set mgr mgr/<module_name>/log_level ''
By default, modules' logging messages are processed by the Ceph logging layer
-where they will be recorded in the mgr daemon's log file.
-But it's also possible to send a module's logging message to it's own file.
+where they will be recorded in the mgr daemon's log file. But it's also
+possible to send a module's logging message to its own file.
-The module's log file will be located in the same directory as the mgr daemon's
+The module's log file is located in the same directory as the Manager daemon's
log file with the following name pattern::
<mgr_daemon_log_file_name>.<module_name>.log
-To enable the file logging on a module use the following command::
+To enable the file logging on a module, use the following command:
+
+.. prompt:: bash #
ceph config set mgr mgr/<module_name>/log_to_file true
-When the module's file logging is enabled, module's logging messages stop
-being written to the mgr daemon's log file and are only written to the
+When the module's file logging is enabled, the module's logging messages stop
+being written to the Manager daemon's log file and are written only to the
module's log file.
It's also possible to check the status and disable the file logging with the
-following commands::
+following commands:
+
+.. prompt:: bash #
ceph config get mgr mgr/<module_name>/log_to_file
ceph config set mgr mgr/<module_name>/log_to_file false
Exposing commands
-----------------
-There are two approaches for exposing a command. The first method involves using
-the ``@CLICommand`` decorator to decorate the methods needed to handle a command.
-The second method uses a ``COMMANDS`` attribute defined for the module class.
+There are two approaches for exposing a command. The first method involves
+using the ``@CLICommand`` decorator to decorate the methods needed to handle a
+command. The second method uses a ``COMMANDS`` attribute defined for the
+module class.
The CLICommand approach
Option(name="my_option")
]
-If you try to use set_module_option or get_module_option on options not declared
-in ``MODULE_OPTIONS``, an exception will be raised.
+If you try to use ``set_module_option`` or ``get_module_option`` on options
+not declared in ``MODULE_OPTIONS``, an exception will be raised.
You may choose to provide setter commands in your module to perform
-high level validation. Users can also modify configuration using
-the normal `ceph config set` command, where the configuration options
-for a mgr module are named like `mgr/<module name>/<option>`.
+high-level validation. Users can also modify configuration using
+the normal ``ceph config set`` command, where the configuration options
+for a Manager module have names of the form ``mgr/<module name>/<option>``.
-If a configuration option is different depending on which node the mgr
+If a configuration option is different, depending on which node the Manager
is running on, then use *localized* configuration (
``get_localized_module_option``, ``set_localized_module_option``).
This may be necessary for options such as what address to listen on.
Localized options may also be set externally with ``ceph config set``,
where they key name is like ``mgr/<module name>/<mgr id>/<option>``
-If you need to load and store data (e.g. something larger, binary, or multiline),
-use the KV store instead of configuration options (see next section).
+If you need to load and store data (e.g. something larger, binary, or
+multiline), use the KV store instead of configuration options (see next
+section).
Hints for using config options:
-* Reads are fast: ceph-mgr keeps a local in-memory copy, so in many cases
- you can just do a get_module_option every time you use a option, rather than
+* Reads are fast: ceph-mgr keeps a local in-memory copy, so in many cases you
+ can just do a ``get_module_option`` every time you use a option, rather than
copying it out into a variable.
* Writes block until the value is persisted (i.e. round trip to the monitor),
but reads from another thread will see the new value immediately.
-* If a user has used `config set` from the command line, then the new
- value will become visible to `get_module_option` immediately, although the
- mon->mgr update is asynchronous, so `config set` will return a fraction
+* If a user has used ``config set`` from the command line, then the new
+ value will become visible to ``get_module_option`` immediately, although the
+ mon->mgr update is asynchronous, so ``config set`` will return a fraction
of a second before the new value is visible on the mgr.
* To delete a config value (i.e. revert to default), just pass ``None`` to
set_module_option.
Following is a sample session, in which the Ceph version is queried by
inputting ``print(mgr.version)`` at the prompt. And later
``timeit`` module is imported to measure the execution time of
-`mgr.get_mgr_id()`.
+``mgr.get_mgr_id()``.
.. code-block:: console
projects / ceph.git / commitdiff