openstack/deb-ceilometer
Code Issues Proposed changes

create a developer section and refactor

Browse Source 
- 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
This commit is contained in:
gordon chung 2015-02-16 18:07:48 -05:00
parent 372e8070d5
commit 2b6bb8b5ba
10 changed files with 86 additions and 276 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/source/configuration.rst
View File

@ -92,7 +92,7 @@ data.
A source is a producer of samples, in effect a set of pollsters and/or 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. 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. details on how to write and plug in your plugins.
Each source configuration encapsulates meter name matching, polling Each source configuration encapsulates meter name matching, polling

22
doc/source/contributing/resources.rst → doc/source/contributing.rst
View File

@ -1,5 +1,4 @@
.. ..
Copyright 2012 New Dream Network, LLC (DreamHost)
Licensed under the Apache License, Version 2.0 (the "License"); you may 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 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 License for the specific language governing permissions and limitations
under the License. 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 :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) :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 :Wiki: http://wiki.openstack.org/wiki/Ceilometer
:Code Hosting: https://git.openstack.org/cgit/openstack/ceilometer/ :Code Hosting: https://git.openstack.org/cgit/openstack/ceilometer/
:Code Review: https://review.openstack.org/#/q/status:open+project:openstack/ceilometer,n,z :Code Review: https://review.openstack.org/#/q/status:open+project:openstack/ceilometer,n,z
.. seealso::
* :ref:`user`

111
doc/source/contributing/areas.rst
View File

@ -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`

26
doc/source/contributing/index.rst
View File

@ -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

48
doc/source/contributing/user.rst
View File

@ -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

25
doc/source/index.rst
View File

@ -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 This documentation offers information on how Ceilometer works and how to
contribute to the project. contribute to the project.
Table of contents Overview
================= ========
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
@ -50,14 +50,31 @@ Table of contents
architecture architecture
measurements measurements
events events
webapi/index
Developer Documentation
=======================
.. toctree::
:maxdepth: 2
install/index install/index
configuration configuration
webapi/index plugins
contributing/index testing
contributing
Appendix
========
.. toctree::
:maxdepth: 1
releasenotes/index releasenotes/index
glossary glossary
sourcecode/autoindex sourcecode/autoindex
.. update index .. update index
Indices and tables Indices and tables

45
doc/source/install/development.rst
View File

@ -14,9 +14,9 @@
License for the specific language governing permissions and limitations License for the specific language governing permissions and limitations
under the License. under the License.
================================================ ================================
Installing and Running the Development Version Installing Development Sandbox
================================================ ================================
Ceilometer has several daemons. The basic are: :term:`polling agent` running 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 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 behaviour using namespaces option passed to polling agent, which will be
maintained for a transitional period. maintained for a transitional period.
.. _devstack: http://www.devstack.org/
Configuring Devstack Configuring Devstack
==================== ====================
.. index:: .. index::
double: installing; devstack 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:: .. note::
@ -52,20 +52,11 @@ Configuring Devstack
<http://devstack.org/localrc.html>`_ or `devstack configuration <http://devstack.org/localrc.html>`_ or `devstack configuration
<http://devstack.org/configuration.html>`_. <http://devstack.org/configuration.html>`_.
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 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 4. The ceilometer services are not enabled by default, so they must be
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
enabled in ``local.conf`` before running ``stack.sh``. enabled in ``local.conf`` before running ``stack.sh``.
This example ``local.conf`` file shows all of the settings required for This example ``local.conf`` file shows all of the settings required for
@ -82,8 +73,18 @@ Configuring Devstack
# Enable the ceilometer api services # Enable the ceilometer api services
enable_service ceilometer-api enable_service ceilometer-api
The first group of daemons are necessary for core ceilometer functionality: The first group of daemons are necessary for core ceilometer functionality:
polling, event listening, and data collection. polling, event listening, and data collection.
6. If you use Data Processing (Sahara) service at your DevStack, it will 5. Nova does not generate the periodic notifications for all known
generate notifications by default. 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/

14
doc/source/install/index.rst
View File

@ -19,19 +19,6 @@
Installing Ceilometer 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
<https://wiki.openstack.org/wiki/StableBranch>`__. 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:: .. toctree::
:maxdepth: 2 :maxdepth: 2
@ -39,4 +26,3 @@
development development
manual manual
mod_wsgi mod_wsgi

27
doc/source/contributing/plugins.rst → doc/source/plugins.rst
View File

@ -13,6 +13,8 @@
License for the specific language governing permissions and limitations License for the specific language governing permissions and limitations
under the License. under the License.
.. _plugins-and-containers:
======================= =======================
Writing Agent Plugins 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 ``process_notification`` will be invoked each time such events are happening which
generates the appropriate sample objects to be sent to the collector. 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 Tests
===== =====
Any new plugin or agent contribution will only be accepted into the project if Any new plugin or agent contribution will only be accepted into the project if

42
doc/source/contributing/source.rst → doc/source/testing.rst
View File

@ -13,33 +13,7 @@
License for the specific language governing permissions and limitations License for the specific language governing permissions and limitations
under the License. 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://<username>@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 Running the Tests
================= =================
@ -106,17 +80,3 @@ run through tox_.
* tox_ * tox_
.. _tox: http://tox.testrun.org/latest/ .. _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