From 2b6bb8b5ba56c76f07982667022797bebcc8fe20 Mon Sep 17 00:00:00 2001 From: gordon chung Date: Mon, 16 Feb 2015 18:07:48 -0500 Subject: [PATCH] create a developer section and refactor - remove contributing folder contents - move plugins into first level - keep testing info from 'working with source' and move to first level - keep a generic contributing page to point to gerrit workflow and standard links (git repo, launchpad, etc...) - delete everything else - split TOC into: - overview - general stuff - developer - dev related stuff - appendix - random stuff Change-Id: I8c460a655427141eb8bb8db9d4c2ecd253eb6cb1 --- doc/source/configuration.rst | 2 +- .../resources.rst => contributing.rst} | 22 ++-- doc/source/contributing/areas.rst | 111 ------------------ doc/source/contributing/index.rst | 26 ---- doc/source/contributing/user.rst | 48 -------- doc/source/index.rst | 25 +++- doc/source/install/development.rst | 45 +++---- doc/source/install/index.rst | 14 --- doc/source/{contributing => }/plugins.rst | 27 +++++ .../{contributing/source.rst => testing.rst} | 42 +------ 10 files changed, 86 insertions(+), 276 deletions(-) rename doc/source/{contributing/resources.rst => contributing.rst} (73%) delete mode 100644 doc/source/contributing/areas.rst delete mode 100644 doc/source/contributing/index.rst delete mode 100644 doc/source/contributing/user.rst rename doc/source/{contributing => }/plugins.rst (83%) rename doc/source/{contributing/source.rst => testing.rst} (70%) diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst index 6e916fb7..f922b093 100644 --- a/doc/source/configuration.rst +++ b/doc/source/configuration.rst @@ -92,7 +92,7 @@ data. A source is a producer of samples, in effect a set of pollsters and/or notification handlers emitting samples for a set of matching meters. -See :doc:`contributing/plugins` and :ref:`plugins-and-containers` for +See :doc:`plugins` and :ref:`plugins-and-containers` for details on how to write and plug in your plugins. Each source configuration encapsulates meter name matching, polling diff --git a/doc/source/contributing/resources.rst b/doc/source/contributing.rst similarity index 73% rename from doc/source/contributing/resources.rst rename to doc/source/contributing.rst index 022eacd9..31195ec2 100644 --- a/doc/source/contributing/resources.rst +++ b/doc/source/contributing.rst @@ -1,5 +1,4 @@ .. - Copyright 2012 New Dream Network, LLC (DreamHost) 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 @@ -13,18 +12,23 @@ License for the specific language governing permissions and limitations under the License. -.. _resources: +.. _contributing: -========================= - Project Hosting Details -========================= +============================ + Contributing to Ceilometer +============================ + +Ceilometer follows the same workflow as other OpenStack projects. To start +contributing to Ceilometer, please follow the workflow found here_. + +.. _here: https://wiki.openstack.org/wiki/Gerrit_Workflow + + +Project Hosting Details +======================= :Bug tracker: http://launchpad.net/ceilometer :Mailing list: http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev (prefix subjects with ``[Ceilometer]`` for faster responses) :Wiki: http://wiki.openstack.org/wiki/Ceilometer :Code Hosting: https://git.openstack.org/cgit/openstack/ceilometer/ :Code Review: https://review.openstack.org/#/q/status:open+project:openstack/ceilometer,n,z - -.. seealso:: - - * :ref:`user` diff --git a/doc/source/contributing/areas.rst b/doc/source/contributing/areas.rst deleted file mode 100644 index 56e1df08..00000000 --- a/doc/source/contributing/areas.rst +++ /dev/null @@ -1,111 +0,0 @@ -.. - Copyright 2012 New Dream Network, LLC (DreamHost) - - 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. - -===================== - Areas to Contribute -===================== - -The Ceilometer project maintains a list of things that need to be worked on at: -https://wiki.openstack.org/wiki/Ceilometer/RoadMap but feel free to work on -something else. - -.. _plugins-and-containers: - -Plugins -======= - -.. index:: - double: plugins; architecture - single: plugins; setuptools - single: plugins; entry points - -Ceilometer's architecture is based heavily on the use of plugins to -make it easy to extend to collect new sorts of data or store them in -different databases. - -Although we have described a list of the metrics Ceilometer should -collect, we cannot predict all of the ways deployers will want to -measure the resources their customers use. This means that Ceilometer -needs to be easy to extend and configure so it can be tuned for each -installation. A plugin system based on `setuptools entry points`_ -makes it easy to add new monitors in the collector or subagents for -polling. In particular, Ceilometer now uses Stevedore_, and you -should put your entry point definitions in the ``entry_points.txt`` -file of your Ceilometer egg. - -.. _setuptools entry points: http://pythonhosted.org/setuptools/setuptools.html#dynamic-discovery-of-services-and-plugins - -.. _Stevedore: http://stevedore.readthedocs.org - -Each daemon provides basic essential services in a framework to be -shared by the plugins, and the plugins do the specialized work. As a -general rule, the plugins are asked to do as little work as -possible. This makes them more efficient as greenlets, maximizes code -reuse, and makes them simpler to implement. - -Installing a plugin automatically activates it the next time the -ceilometer daemon starts. A global configuration option can be used to -disable installed plugins (for example, one or more of the "default" -set of plugins provided as part of the ceilometer package). - -Plugins may require configuration options, so when the plugin is -loaded it is asked to add options to the global flags object, and the -results are made available to the plugin before it is asked to do any -work. - -Rather than running and reporting errors or simply consuming cycles -for no-ops, plugins may disable themselves at runtime based on -configuration settings defined by other components (for example, the -plugin for polling libvirt does not run if it sees that the system is -configured using some other virtualization tool). The plugin is -asked once at startup, after it has been loaded and given the -configuration settings, if it should be enabled. Plugins should not -define their own flags for enabling or disabling themselves. - -Each plugin API is defined by the namespace and an abstract base class -for the plugin instances. Plugins are not required to subclass from -the API definition class, but it is encouraged as a way to discover -API changes. - -.. seealso:: - - * :ref:`architecture` - * :doc:`plugins` - -Core -==== - -The core parts of ceilometer, not separated into a plugin, are fairly -simple but depend on code that is part of ``nova`` right now. One -project goal is to move the rest of those dependencies out of ``nova`` -and into ``oslo``. Logging and RPC are already done, but -the service and manager base classes still need to move. - -.. seealso:: - - * https://launchpad.net/nova - * https://launchpad.net/oslo - -Testing -======= - -The first version of ceilometer has extensive unit tests, but -has not seen much run-time in real environments. Setting up a copy of -ceilometer to monitor a real OpenStack installation or to perform some -load testing would be especially helpful. - -.. seealso:: - - * :ref:`install` diff --git a/doc/source/contributing/index.rst b/doc/source/contributing/index.rst deleted file mode 100644 index d570eaaf..00000000 --- a/doc/source/contributing/index.rst +++ /dev/null @@ -1,26 +0,0 @@ -.. - Copyright 2012 New Dream Network, LLC (DreamHost) - - 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. - -============================ - Contributing to Ceilometer -============================ - -.. toctree:: - - user - resources - areas - source - plugins diff --git a/doc/source/contributing/user.rst b/doc/source/contributing/user.rst deleted file mode 100644 index 693e21ab..00000000 --- a/doc/source/contributing/user.rst +++ /dev/null @@ -1,48 +0,0 @@ -.. - Copyright 2012 New Dream Network, LLC (DreamHost) - - 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. - -.. _user: - -===================== - Joining the Project -===================== - -Contributor License Agreement -============================= - -.. index:: - single: license; agreement - -In order to contribute to the ceilometer project, you need to have -signed OpenStack's contributor's agreement. - -.. seealso:: - - * http://docs.openstack.org/infra/manual/developers.html - * http://wiki.openstack.org/CLA - -LaunchPad Project -================= - -Most of the tools used for OpenStack depend on a launchpad.net ID for -authentication. After signing up for a launchpad account, join the -"openstack" team to have access to the mailing list and receive -notifications of important events. - -.. seealso:: - - * http://launchpad.net - * http://launchpad.net/ceilometer - * http://launchpad.net/~openstack diff --git a/doc/source/index.rst b/doc/source/index.rst index fd576439..e945925b 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -40,8 +40,8 @@ What is the purpose of the project and vision for it? This documentation offers information on how Ceilometer works and how to contribute to the project. -Table of contents -================= +Overview +======== .. toctree:: :maxdepth: 2 @@ -50,14 +50,31 @@ Table of contents architecture measurements events + webapi/index + +Developer Documentation +======================= + +.. toctree:: + :maxdepth: 2 + install/index configuration - webapi/index - contributing/index + plugins + testing + contributing + +Appendix +======== + +.. toctree:: + :maxdepth: 1 + releasenotes/index glossary sourcecode/autoindex + .. update index Indices and tables diff --git a/doc/source/install/development.rst b/doc/source/install/development.rst index 6cf1157e..c2563cdc 100644 --- a/doc/source/install/development.rst +++ b/doc/source/install/development.rst @@ -14,9 +14,9 @@ License for the specific language governing permissions and limitations under the License. -================================================ - Installing and Running the Development Version -================================================ +================================ + Installing Development Sandbox +================================ Ceilometer has several daemons. The basic are: :term:`polling agent` running either on the Nova compute node(s) or :term:`polling agent` running on the @@ -34,15 +34,15 @@ of the instructions below are duplicated. Skip the steps you have already done. behaviour using namespaces option passed to polling agent, which will be maintained for a transitional period. -.. _devstack: http://www.devstack.org/ - Configuring Devstack ==================== .. index:: double: installing; devstack -1. Create a ``local.conf`` file as input to devstack. +1. Download devstack_. + +2. Create a ``local.conf`` file as input to devstack. .. note:: @@ -52,20 +52,11 @@ Configuring Devstack `_ or `devstack configuration `_. -2. Ceilometer makes extensive use of the messaging bus, but has not +3. Ceilometer makes extensive use of the messaging bus, but has not yet been tested with ZeroMQ. We recommend using Rabbit or qpid for - now. + now. By default, RabbitMQ will be used by devstack. -3. Nova does not generate the periodic notifications for all known - instances by default. To enable these auditing events, set - ``instance_usage_audit`` to true in the nova configuration file. - -4. Cinder does not generate notifications by default. To enable - these auditing events, set the following in the cinder configuration file:: - - notification_driver=cinder.openstack.common.notifier.rpc_notifier - -5. The ceilometer services are not enabled by default, so they must be +4. The ceilometer services are not enabled by default, so they must be enabled in ``local.conf`` before running ``stack.sh``. This example ``local.conf`` file shows all of the settings required for @@ -82,8 +73,18 @@ Configuring Devstack # Enable the ceilometer api services enable_service ceilometer-api -The first group of daemons are necessary for core ceilometer functionality: -polling, event listening, and data collection. + The first group of daemons are necessary for core ceilometer functionality: + polling, event listening, and data collection. -6. If you use Data Processing (Sahara) service at your DevStack, it will - generate notifications by default. +5. Nova does not generate the periodic notifications for all known + instances by default. To enable these auditing events, set + ``instance_usage_audit`` to true in the nova configuration file and restart + the service. + +6. Cinder does not generate notifications by default. To enable + these auditing events, set the following in the cinder configuration file + and restart the service:: + + notification_driver=messagingv2 + +.. _devstack: http://www.devstack.org/ diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst index 727da2c1..f57cb695 100644 --- a/doc/source/install/index.rst +++ b/doc/source/install/index.rst @@ -19,19 +19,6 @@ Installing Ceilometer ======================= -.. note:: - - The ceilometer team has limited capacity to provide support for - older versions of the project. Because the project graduated from - incubation around the time of the grizzly release, that is the - first version for which we will provide regular ongoing support - following `the standard deprecation cycle for OpenStack - `__. The grizzly - version of ceilometer cannot be installed on the same server - with earlier versions of OpenStack because of conflicting package - requirements, but is API compatible with the folsom release if - installed separately. - .. toctree:: :maxdepth: 2 @@ -39,4 +26,3 @@ development manual mod_wsgi - diff --git a/doc/source/contributing/plugins.rst b/doc/source/plugins.rst similarity index 83% rename from doc/source/contributing/plugins.rst rename to doc/source/plugins.rst index fc27e47d..83e4733d 100644 --- a/doc/source/contributing/plugins.rst +++ b/doc/source/plugins.rst @@ -13,6 +13,8 @@ License for the specific language governing permissions and limitations under the License. +.. _plugins-and-containers: + ======================= Writing Agent Plugins ======================= @@ -131,6 +133,31 @@ using the ``get_event_type`` method and subsequently the method ``process_notification`` will be invoked each time such events are happening which generates the appropriate sample objects to be sent to the collector. +Adding new plugins +------------------ + +Although we have described a list of the metrics Ceilometer should +collect, we cannot predict all of the ways deployers will want to +measure the resources their customers use. This means that Ceilometer +needs to be easy to extend and configure so it can be tuned for each +installation. A plugin system based on `setuptools entry points`_ +makes it easy to add new monitors in the agents. In particular, +Ceilometer now uses Stevedore_, and you should put your entry point +definitions in the ``entry_points.txt`` file of your Ceilometer egg. + +.. _setuptools entry points: http://pythonhosted.org/setuptools/setuptools.html#dynamic-discovery-of-services-and-plugins + +.. _Stevedore: http://stevedore.readthedocs.org + +Installing a plugin automatically activates it the next time the +ceilometer daemon starts. Rather than running and reporting errors or +simply consuming cycles for no-ops, plugins may disable themselves at +runtime based on configuration settings defined by other components (for example, the +plugin for polling libvirt does not run if it sees that the system is +configured using some other virtualization tool). Additionally, if no +valid resources can be discovered the plugin will be disabled. + + Tests ===== Any new plugin or agent contribution will only be accepted into the project if diff --git a/doc/source/contributing/source.rst b/doc/source/testing.rst similarity index 70% rename from doc/source/contributing/source.rst rename to doc/source/testing.rst index 35e0650d..a87cd38c 100644 --- a/doc/source/contributing/source.rst +++ b/doc/source/testing.rst @@ -13,33 +13,7 @@ License for the specific language governing permissions and limitations under the License. -========================= - Working with the Source -========================= - -Setting up a Development Sandbox -================================ - -1. Set up a server or virtual machine to run OpenStack using - devstack_. - -.. _devstack: http://www.devstack.org/ - -2. Clone the ceilometer project to the machine:: - - $ cd /opt/stack - $ git clone https://git.openstack.org/openstack/ceilometer - $ cd ./ceilometer - -3. Once this is done, you need to setup the review process:: - - $ git remote add gerrit ssh://@review.openstack.org:29418/openstack/ceilometer.git - -4. If you are preparing a patch, create a topic branch and switch to - it before making any changes:: - - $ git checkout -b TOPIC-BRANCH - +================= Running the Tests ================= @@ -106,17 +80,3 @@ run through tox_. * tox_ .. _tox: http://tox.testrun.org/latest/ - -Code Reviews -============ - -Ceilometer uses the OpenStack review process for all code and -developer documentation contributions. Code reviews are managed -through gerrit. - -.. seealso:: - - * http://docs.openstack.org/infra/manual/developers.html#development-workflow - * `OpenStack Gerrit instance`_. - -.. _OpenStack Gerrit instance: https://review.openstack.org/#/q/status:open+project:openstack/ceilometer,n,z