From 3322bf38fa6a7ce54e4ca20f829942f1a0cb2b79 Mon Sep 17 00:00:00 2001 From: Zac Dover Date: Fri, 23 May 2025 20:24:01 +1000 Subject: [PATCH] doc/mgr: edit modules.rst. Edit doc/mgr/modules.rst. Improve some of the English. This is part of a project to separate out the twenty-five files that were committed to https://github.com/ceph/ceph/pull/62782. This commit and the PR of which it is a part includes the changes made in https://github.com/ceph/ceph/pull/62782 and some corrections to glaring grammatical errors. However, this file could use a careful grammar pass. As it currently stands, it contains run-on sentences and English that is acceptable in conversation but not acceptable in written communication. Signed-off-by: Zac Dover (cherry picked from commit 1818e48abbb6853817c626fac4a32cace1b5ebc0) --- doc/mgr/modules.rst | 87 +++++++++++++++++++++++++-------------------- 1 file changed, 49 insertions(+), 38 deletions(-) diff --git a/doc/mgr/modules.rst b/doc/mgr/modules.rst index 667664139739f..205f4bb0142e9 100644 --- a/doc/mgr/modules.rst +++ b/doc/mgr/modules.rst @@ -1,5 +1,3 @@ - - .. _mgr-module-dev: ceph-mgr module developer's guide @@ -8,14 +6,14 @@ 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: @@ -36,11 +34,13 @@ creating these modules. 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 @@ -57,11 +57,14 @@ import the ``logging`` package and get a logger instance with the 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//log_level - ceph config set mgr mgr//log_level +.. prompt:: bash # + + ceph config get mgr mgr//log_level + ceph config set mgr mgr//log_level 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 @@ -74,29 +77,35 @@ level is mapped to the module python logging level as follows: * <= +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//log_level '' + ceph config set mgr mgr//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:: ..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//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//log_to_file ceph config set mgr mgr//log_to_file false @@ -108,9 +117,10 @@ following commands:: 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 @@ -411,34 +421,35 @@ You must declare your available configuration options in the 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//