diff options
author | Tommi Virtanen <tommi.virtanen@dreamhost.com> | 2011-09-01 12:42:56 -0700 |
---|---|---|
committer | Tommi Virtanen <tommi.virtanen@dreamhost.com> | 2011-09-01 13:28:12 -0700 |
commit | 66ee58f69197d977421273f54b43d8e941395275 (patch) | |
tree | ffc484427eabaf9025dbecac2a192623048ee6b7 | |
parent | c8c205fa73078c1ee46152ed860084a272867f5e (diff) | |
download | ceph-66ee58f69197d977421273f54b43d8e941395275.tar.gz |
doc: Move internals into a new section, /dev.
Most of the doc is user-oriented, let's isolate internals more.
Split into multiple files. Clean up RST.
Use Sphinx's graphviz plugin for graphs.
Signed-off-by: Tommi Virtanen <tommi.virtanen@dreamhost.com>
-rwxr-xr-x | admin/build-doc | 1 | ||||
-rw-r--r-- | doc/architecture.rst | 150 | ||||
-rw-r--r-- | doc/conf.py | 1 | ||||
-rw-r--r-- | doc/dev/config.rst | 77 | ||||
-rw-r--r-- | doc/dev/context.rst | 20 | ||||
-rw-r--r-- | doc/dev/index.rst | 11 | ||||
-rw-r--r-- | doc/dev/libs.rst | 18 | ||||
-rw-r--r-- | doc/dev/logs.rst | 31 | ||||
-rw-r--r-- | doc/dev/object-store.rst | 67 | ||||
-rw-r--r-- | doc/index.rst | 1 | ||||
-rw-r--r-- | doc/object_store.dot | 61 |
11 files changed, 227 insertions, 211 deletions
diff --git a/admin/build-doc b/admin/build-doc index 347e7cbb1f4..622d7c84031 100755 --- a/admin/build-doc +++ b/admin/build-doc @@ -10,7 +10,6 @@ if [ ! -e build-doc/doxygen/xml ]; then fi dia --filter=png-libart --export=doc/overview.png.tmp doc/overview.dia -dot -Tpng < doc/object_store.dot > doc/object_store.png mv -- doc/overview.png.tmp doc/overview.png diff --git a/doc/architecture.rst b/doc/architecture.rst index fb7a1ea15ee..cf67f6be505 100644 --- a/doc/architecture.rst +++ b/doc/architecture.rst @@ -23,153 +23,5 @@ - Discussion of MDS terminology, daemon types (active, standby, standby-replay) -.. todo:: write me - -==================================== - Object Store Architecture Overview -==================================== -.. image:: object_store.png - -.. todo:: write more here - -================================= - Library architecture -================================= -Ceph is structured into libraries which are built and then combined together to -make executables and other libraries. - -- libcommon: a collection of utilities which are available to nearly every ceph - library and executable. In general, libcommon should not contain global - variables, because it is intended to be linked into libraries such as - libceph.so. - -- libglobal: a collection of utilities focused on the needs of Ceph daemon - programs. In here you will find pidfile management functions, signal - handlers, and so forth. - -.. todo:: document other libraries - -================================= - Configuration Management System -================================= -The configuration management system exists to provide every daemon with the -proper configuration information. The configuration can be viewed as a set of -key-value pairs. - -How can the configuration be set? Well, there are several sources: - - the ceph configuration file, usually named ceph.conf - - command line arguments:: - --debug-ms=1 - --debug-pg=10 - etc. - - arguments injected at runtime by using injectargs - -====================================================== - The Configuration File -====================================================== -Most configuration settings originate in the Ceph configuration file. - -How do we find the configuration file? Well, in order, we check: - - the default locations - - the environment variable CEPH_CONF - - the command line argument -c - -Each stanza of the configuration file describes the key-value pairs that will be in -effect for a particular subset of the daemons. The "global" stanza applies to -everything. The "mon", "osd", and "mds" stanzas specify settings to take effect -for all monitors, all osds, and all mds servers, respectively. A stanza of the -form mon.$name, osd.$name, or mds.$name gives settings for the monitor, OSD, or -MDS of that name, respectively. Configuration values that appear later in the -file win over earlier ones. - -A sample configuration file can be found in src/sample.ceph.conf. - -====================================================== - Metavariables -====================================================== -The configuration system supports certain "metavariables." If these occur -inside a configuration value, they are expanded into something else-- similar to -how bash shell expansion works. - -There are a few different metavariables: - - $host: expands to the current hostname - - $type: expands to one of "mds", "osd", or "mon" - - $id: expands to the daemon identifier. For osd.0, this would be "0"; for mds.a, it would be "a" - - $num: same as $id - - $name: expands to $type.$id - -====================================================== - Interfacing with the Configuration Management System -====================================================== -There are two ways for Ceph code to get configuration values. One way is to -read it directly from a variable named "g_conf," or equivalently, -"g_ceph_ctx->_conf." The other is to register an observer that will called -every time the relevant configuration values changes. This observer will be -called soon after the initial configuration is read, and every time after that -when one of the relevant values changes. Each observer tracks a set of keys -and is invoked only when one of the relevant keys changes. -The interface to implement is found in common/config_obs.h. - -The observer method should be preferred in new code because - - It is more flexible, allowing the code to do whatever reinitialization needs - to be done to implement the new configuration value. - - It is the only way to create a std::string configuration variable that can - be changed by injectargs. - - Even for int-valued configuration options, changing the values in one thread - while another thread is reading them can lead to subtle and - impossible-to-diagnose bugs. - -For these reasons, reading directly from g_conf should be considered deprecated -and not done in new code. Do not ever alter g_conf. - -================================= - Debug Logs -================================= -The main debugging tool for Ceph is the dout and derr logging functions. -Collectively, these are referred to as "dout logging." - -Dout has several log faculties, which can be set at various log -levels using the configuration management system. So it is possible to enable -debugging just for the messenger, by setting debug_ms to 10, for example. - -Dout is implemented mainly in common/DoutStreambuf.cc - -The dout macro avoids even generating log messages which are not going to be -used, by enclosing them in an "if" statement. What this means is that if you -have the debug level set at 0, and you run this code - -``dout(20) << "myfoo() = " << myfoo() << dendl;`` - - -myfoo() will not be called here. - -Unfortunately, the performance of debug logging is relatively low. This is -because there is a single, process-wide mutex which every debug output -statement takes, and every debug output statement leads to a write() system -call or a call to syslog(). There is also a computational overhead to using C++ -streams to consider. So you will need to be parsimonius in your logging to get -the best performance. - -Sometimes, enabling logging can hide race conditions and other bugs by changing -the timing of events. Keep this in mind when debugging. - -================================= - CephContext -================================= -A CephContext represents a single view of the Ceph cluster. It comes complete -with a configuration, a set of performance counters (PerfCounters), and a -heartbeat map. You can find more information about CephContext in -src/common/ceph_context.h. - -Generally, you will have only one CephContext in your application, called -g_ceph_context. However, in library code, it is possible that the library user -will initialize multiple CephContexts. For example, this would happen if he -called rados_create more than once. - -A ceph context is required to issue log messages. Why is this? Well, without -the CephContext, we would not know which log messages were disabled and which -were enabled. The dout() macro implicitly references g_ceph_context, so it -can't be used in library code. It is fine to use dout and derr in daemons, but -in library code, you must use ldout and lderr, and pass in your own CephContext -object. The compiler will enforce this restriction. +.. todo:: write me diff --git a/doc/conf.py b/doc/conf.py index b74229608a1..afac33f816a 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -22,6 +22,7 @@ html_sidebars = { # ugly kludge until breathe is distutils-friendly import sys; sys.path.append('../build-doc/breathe') extensions = [ + 'sphinx.ext.graphviz', 'sphinx.ext.todo', 'breathe', ] diff --git a/doc/dev/config.rst b/doc/dev/config.rst new file mode 100644 index 00000000000..59f1b92989c --- /dev/null +++ b/doc/dev/config.rst @@ -0,0 +1,77 @@ +================================= + Configuration Management System +================================= + +The configuration management system exists to provide every daemon with the +proper configuration information. The configuration can be viewed as a set of +key-value pairs. + +How can the configuration be set? Well, there are several sources: + - the ceph configuration file, usually named ceph.conf + - command line arguments:: + --debug-ms=1 + --debug-pg=10 + etc. + - arguments injected at runtime by using injectargs + + +The Configuration File +====================== + +Most configuration settings originate in the Ceph configuration file. + +How do we find the configuration file? Well, in order, we check: + - the default locations + - the environment variable CEPH_CONF + - the command line argument -c + +Each stanza of the configuration file describes the key-value pairs that will be in +effect for a particular subset of the daemons. The "global" stanza applies to +everything. The "mon", "osd", and "mds" stanzas specify settings to take effect +for all monitors, all osds, and all mds servers, respectively. A stanza of the +form mon.$name, osd.$name, or mds.$name gives settings for the monitor, OSD, or +MDS of that name, respectively. Configuration values that appear later in the +file win over earlier ones. + +A sample configuration file can be found in src/sample.ceph.conf. + + +Metavariables +============= + +The configuration system supports certain "metavariables." If these occur +inside a configuration value, they are expanded into something else-- similar to +how bash shell expansion works. + +There are a few different metavariables: + - $host: expands to the current hostname + - $type: expands to one of "mds", "osd", or "mon" + - $id: expands to the daemon identifier. For osd.0, this would be "0"; for mds.a, it would be "a" + - $num: same as $id + - $name: expands to $type.$id + + +Interfacing with the Configuration Management System +==================================================== + +There are two ways for Ceph code to get configuration values. One way is to +read it directly from a variable named "g_conf," or equivalently, +"g_ceph_ctx->_conf." The other is to register an observer that will called +every time the relevant configuration values changes. This observer will be +called soon after the initial configuration is read, and every time after that +when one of the relevant values changes. Each observer tracks a set of keys +and is invoked only when one of the relevant keys changes. + +The interface to implement is found in common/config_obs.h. + +The observer method should be preferred in new code because + - It is more flexible, allowing the code to do whatever reinitialization needs + to be done to implement the new configuration value. + - It is the only way to create a std::string configuration variable that can + be changed by injectargs. + - Even for int-valued configuration options, changing the values in one thread + while another thread is reading them can lead to subtle and + impossible-to-diagnose bugs. + +For these reasons, reading directly from g_conf should be considered deprecated +and not done in new code. Do not ever alter g_conf. diff --git a/doc/dev/context.rst b/doc/dev/context.rst new file mode 100644 index 00000000000..1a2b2cbfb00 --- /dev/null +++ b/doc/dev/context.rst @@ -0,0 +1,20 @@ +============= + CephContext +============= + +A CephContext represents a single view of the Ceph cluster. It comes complete +with a configuration, a set of performance counters (PerfCounters), and a +heartbeat map. You can find more information about CephContext in +src/common/ceph_context.h. + +Generally, you will have only one CephContext in your application, called +g_ceph_context. However, in library code, it is possible that the library user +will initialize multiple CephContexts. For example, this would happen if he +called rados_create more than once. + +A ceph context is required to issue log messages. Why is this? Well, without +the CephContext, we would not know which log messages were disabled and which +were enabled. The dout() macro implicitly references g_ceph_context, so it +can't be used in library code. It is fine to use dout and derr in daemons, but +in library code, you must use ldout and lderr, and pass in your own CephContext +object. The compiler will enforce this restriction. diff --git a/doc/dev/index.rst b/doc/dev/index.rst new file mode 100644 index 00000000000..833545049a2 --- /dev/null +++ b/doc/dev/index.rst @@ -0,0 +1,11 @@ +================================== + Internal developer documentation +================================== + +.. note:: If you're looking for how to use Ceph as a library from your + own software, please see :doc:`/api/index`. + +.. toctree:: + :glob: + + * diff --git a/doc/dev/libs.rst b/doc/dev/libs.rst new file mode 100644 index 00000000000..bdebdb3b000 --- /dev/null +++ b/doc/dev/libs.rst @@ -0,0 +1,18 @@ +====================== + Library architecture +====================== + +Ceph is structured into libraries which are built and then combined together to +make executables and other libraries. + +- libcommon: a collection of utilities which are available to nearly every ceph + library and executable. In general, libcommon should not contain global + variables, because it is intended to be linked into libraries such as + libceph.so. + +- libglobal: a collection of utilities focused on the needs of Ceph daemon + programs. In here you will find pidfile management functions, signal + handlers, and so forth. + +.. todo:: document other libraries + diff --git a/doc/dev/logs.rst b/doc/dev/logs.rst new file mode 100644 index 00000000000..f4bef84c2ca --- /dev/null +++ b/doc/dev/logs.rst @@ -0,0 +1,31 @@ +============ + Debug Logs +============ + +The main debugging tool for Ceph is the dout and derr logging functions. +Collectively, these are referred to as "dout logging." + +Dout has several log faculties, which can be set at various log +levels using the configuration management system. So it is possible to enable +debugging just for the messenger, by setting debug_ms to 10, for example. + +Dout is implemented mainly in common/DoutStreambuf.cc + +The dout macro avoids even generating log messages which are not going to be +used, by enclosing them in an "if" statement. What this means is that if you +have the debug level set at 0, and you run this code + +``dout(20) << "myfoo() = " << myfoo() << dendl;`` + + +myfoo() will not be called here. + +Unfortunately, the performance of debug logging is relatively low. This is +because there is a single, process-wide mutex which every debug output +statement takes, and every debug output statement leads to a write() system +call or a call to syslog(). There is also a computational overhead to using C++ +streams to consider. So you will need to be parsimonius in your logging to get +the best performance. + +Sometimes, enabling logging can hide race conditions and other bugs by changing +the timing of events. Keep this in mind when debugging. diff --git a/doc/dev/object-store.rst b/doc/dev/object-store.rst new file mode 100644 index 00000000000..77d62e4b6b6 --- /dev/null +++ b/doc/dev/object-store.rst @@ -0,0 +1,67 @@ +==================================== + Object Store Architecture Overview +==================================== + +.. graphviz:: + + /* + * Rough outline of object store module dependencies + */ + + digraph object_store { + size="10,10"; + node [color=lightblue2, style=filled, fontname="Serif"]; + + "testrados" -> "librados" + "testradospp" -> "librados" + + "rbd" -> "librados" + + "radostool" -> "librados" + + "radosgw_admin" -> "rgw" + + "rgw" -> "librados" + + "radosacl" -> "librados" + + "librados" -> "objecter" + + "ObjectCacher" -> "Filer" + + "dumpjournal" -> "Journaler" + + "Journaler" -> "Filer" + + "SyntheticClient" -> "Filer" + "SyntheticClient" -> "objecter" + + "Filer" -> "objecter" + + "objecter" -> "OSDMap" + + "cosd" -> "PG" + "cosd" -> "ObjectStore" + + "crushtool" -> "CrushWrapper" + + "OSDMap" -> "CrushWrapper" + + "OSDMapTool" -> "OSDMap" + + "PG" -> "ReplicatedPG" + "PG" -> "ObjectStore" + "PG" -> "OSDMap" + + "ReplicatedPG" -> "ObjectStore" + "ReplicatedPG" -> "OSDMap" + + "ObjectStore" -> "FileStore" + + "FileStore" -> "ext3" + "FileStore" -> "ext4" + "FileStore" -> "btrfs" + } + + +.. todo:: write more here diff --git a/doc/index.rst b/doc/index.rst index c108dffeeb4..195c74993bb 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -90,6 +90,7 @@ Table of Contents architecture ops/index api/index + Internals <dev/index> man/index papers glossary diff --git a/doc/object_store.dot b/doc/object_store.dot deleted file mode 100644 index eda3eb68f23..00000000000 --- a/doc/object_store.dot +++ /dev/null @@ -1,61 +0,0 @@ -/* - * Rough outline of object store module dependencies - * - * build with - * dot -Tpng < ./object_store.dot > object_store.png - */ - -digraph object_store { - size="16,16"; - node [color=lightblue2, style=filled, fontname="Serif"]; - - "testrados" -> "librados" - "testradospp" -> "librados" - - "rbd" -> "librados" - - "radostool" -> "librados" - - "radosgw_admin" -> "rgw" - - "rgw" -> "librados" - - "radosacl" -> "librados" - - "librados" -> "objecter" - - "ObjectCacher" -> "Filer" - - "dumpjournal" -> "Journaler" - - "Journaler" -> "Filer" - - "SyntheticClient" -> "Filer" - "SyntheticClient" -> "objecter" - - "Filer" -> "objecter" - - "objecter" -> "OSDMap" - - "cosd" -> "PG" - "cosd" -> "ObjectStore" - - "crushtool" -> "CrushWrapper" - - "OSDMap" -> "CrushWrapper" - - "OSDMapTool" -> "OSDMap" - - "PG" -> "ReplicatedPG" - "PG" -> "ObjectStore" - "PG" -> "OSDMap" - - "ReplicatedPG" -> "ObjectStore" - "ReplicatedPG" -> "OSDMap" - - "ObjectStore" -> "FileStore" - - "FileStore" -> "ext3" - "FileStore" -> "ext4" - "FileStore" -> "btrfs" -} |