Merge "Introduce Guru Meditation Reports into Ceilometer"

ceilometer/service.py

@@ -21,8 +21,10 @@ import sys
 from oslo_config import cfg
 import oslo_i18n
 from oslo_log import log
+from oslo_reports import guru_meditation_report as gmr
 
 from ceilometer import messaging
+from ceilometer import version
 
 
 OPTS = [
@@ -118,6 +120,12 @@ def prepare_service(argv=None):
     log.set_defaults(default_log_levels=log_levels)
     if argv is None:
         argv = sys.argv
-    cfg.CONF(argv[1:], project='ceilometer', validate_default_values=True)
+    cfg.CONF(argv[1:], project='ceilometer', validate_default_values=True,
+             version=version.version_info.version_string())
     log.setup(cfg.CONF, 'ceilometer')
+    # NOTE(liusheng): guru cannot run with service under apache daemon, so when
+    # ceilometer-api running with mod_wsgi, the argv is [], we don't start
+    # guru.
+    if argv:
+        gmr.TextGuruMeditation.setup_autorun(version)
     messaging.setup()

ceilometer/version.py

@@ -0,0 +1,17 @@
+#
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+
+
+import pbr.version
+
+version_info = pbr.version.VersionInfo('ceilometer')

doc/source/gmr.rst

@@ -0,0 +1,89 @@
+..
+      Copyright (c) 2014 OpenStack Foundation
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+Guru Meditation Reports
+=======================
+
+Ceilometer contains a mechanism whereby developers and system administrators
+can generate a report about the state of a running Ceilometer executable. This
+report is called a *Guru Meditation Report* (*GMR* for short).
+
+Generating a GMR
+----------------
+
+A *GMR* can be generated by sending the *USR1* signal to any Ceilometer process
+with support (see below).  The *GMR* will then be outputted standard error for
+that particular process.
+
+For example, suppose that ``ceilometer-polling`` has process id ``8675``, and
+was run with ``2>/var/log/ceilometer/ceilometer-polling.log``.  Then,
+``kill -USR1 8675`` will trigger the Guru Meditation report to be printed to
+``/var/log/ceilometer/ceilometer-polling.log``.
+
+Structure of a GMR
+------------------
+
+The *GMR* is designed to be extensible; any particular executable may add its
+own sections.  However, the base *GMR* consists of several sections:
+
+Package
+  Shows information about the package to which this process belongs, including
+  version information
+
+Threads
+  Shows stack traces and thread ids for each of the threads within this process
+
+Green Threads
+  Shows stack traces for each of the green threads within this process (green
+  threads don't have thread ids)
+
+Configuration
+  Lists all the configuration options currently accessible via the CONF object
+  for the current process
+
+Adding Support for GMRs to New Executables
+------------------------------------------
+
+Adding support for a *GMR* to a given executable is fairly easy.
+
+First import the module (currently residing in oslo-incubator), as well as the
+Ceilometer version module:
+
+.. code-block:: python
+
+      from oslo_reports import guru_meditation_report as gmr
+      from ceilometer import version
+
+Then, register any additional sections (optional):
+
+.. code-block:: python
+
+      TextGuruMeditation.register_section('Some Special Section',
+                                          some_section_generator)
+
+Finally (under main), before running the "main loop" of the executable (usually
+``service.server(server)`` or something similar), register the *GMR* hook:
+
+.. code-block:: python
+
+      TextGuruMeditation.setup_autorun(version)
+
+Extending the GMR
+-----------------
+
+As mentioned above, additional sections can be added to the GMR for a
+particular executable.  For more information, see the inline documentation
+about oslo.reports:
+`oslo.reports <http://docs.openstack.org/developer/oslo.reports/>`_

doc/source/index.rst

@@ -64,6 +64,7 @@ Developer Documentation
    new_meters
    testing
    contributing
+   gmr
 
 Appendix
 ========

requirements.txt

@@ -18,6 +18,7 @@ oslo.config>=2.1.0 # Apache-2.0
 oslo.i18n>=1.5.0 # Apache-2.0
 oslo.log>=1.8.0 # Apache-2.0
 oslo.policy>=0.5.0 # Apache-2.0
+oslo.reports>=0.1.0  # Apache-2.0
 oslo.rootwrap>=2.0.0 # Apache-2.0
 oslo.service>=0.6.0 # Apache-2.0
 PasteDeploy>=1.5.0