extend developer documentation
- Add information about the system architecture (modified from the wiki to reflect what was implemented). - Add information about where we want contributions. - Add information about how to sign up to participate in the project and how to be a part of the community. - Add more detailed instructions for installing the development version from git. - Add a placeholder for documenting the configuration options. - Add instructions for running the tests after getting the source code. - Add a glossary and index. tags: DocImpact bug 1006366 Change-Id: I8927c55e77cdd31804249d101575f9e174e6232d Signed-off-by: Doug Hellmann <doug.hellmann@dreamhost.com>
This commit is contained in:
Doug Hellmann
parent
fec72610ab
commit
1f9bce2609
215
doc/source/architecture.rst
Normal file
215
doc/source/architecture.rst
Normal file
@ -0,0 +1,215 @@
|
|||||||
|
.. _architecture:
|
||||||
|
|
||||||
|
=====================
|
||||||
|
System Architecture
|
||||||
|
=====================
|
||||||
|
|
||||||
|
High Level Description
|
||||||
|
======================
|
||||||
|
|
||||||
|
.. index::
|
||||||
|
single: agent; architecture
|
||||||
|
double: compute agent; architecture
|
||||||
|
double: collector; architecture
|
||||||
|
double: data store; architecture
|
||||||
|
double: database; architecture
|
||||||
|
double: API; architecture
|
||||||
|
|
||||||
|
There are 4 basic components to the system:
|
||||||
|
|
||||||
|
1. An :term:`agent` runs on each compute node and polls for resource
|
||||||
|
utilization statistics. There may be other types of agents in the
|
||||||
|
future, but for now we will focus on creating the compute agent.
|
||||||
|
|
||||||
|
2. The :term:`collector` runs on one or more central management
|
||||||
|
servers to monitor the message queues (for notifications and for
|
||||||
|
metering data coming from the agent). Notification messages are
|
||||||
|
processed and turned into metering messages and sent back out onto
|
||||||
|
the message bus using the appropriate topic. Metering messages are
|
||||||
|
written to the data store without modification.
|
||||||
|
|
||||||
|
3. The :term:`data store` is a database capable of handling concurrent
|
||||||
|
writes (from one or more collector instances) and reads (from the
|
||||||
|
API server).
|
||||||
|
|
||||||
|
4. The :term:`API server` runs on one or more central management
|
||||||
|
servers to provide access to the data from the data store. See
|
||||||
|
EfficientMetering#API for details.
|
||||||
|
|
||||||
|
These services communicate using the standard OpenStack messaging
|
||||||
|
bus. Only the collector and API server have access to the data store.
|
||||||
|
|
||||||
|
Detailed Description
|
||||||
|
====================
|
||||||
|
|
||||||
|
.. warning::
|
||||||
|
|
||||||
|
These details cover only the compute agent and collector, as well
|
||||||
|
as their communication via the messaging bus. More work is needed
|
||||||
|
before the data store and API server designs can be documented.
|
||||||
|
|
||||||
|
Plugins
|
||||||
|
-------
|
||||||
|
|
||||||
|
.. index::
|
||||||
|
double: plugins; architecture
|
||||||
|
single: plugins; setuptools
|
||||||
|
single: plugins; entry points
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
.. _setuptools entry points: http://packages.python.org/distribute/setuptools.html#dynamic-discovery-of-services-and-plugins
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
.. warning:: Plugin self-deactivation is not implemented, yet.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
There is ongoing work to add a generic plugin system to Nova. If
|
||||||
|
that is implemented as part of the common library, ceilometer may
|
||||||
|
use it (or adapt it as necessary for our use). If it remains part
|
||||||
|
of Nova for Folsom we should probably not depend on it because
|
||||||
|
loading plugins is trivial with setuptools.
|
||||||
|
|
||||||
|
Polling
|
||||||
|
-------
|
||||||
|
|
||||||
|
.. index::
|
||||||
|
double: polling; architecture
|
||||||
|
|
||||||
|
Metering data comes from two sources: through notifications built into
|
||||||
|
the existing OpenStack components and by polling the infrastructure
|
||||||
|
(such as via libvirt). Polling for compute resources is handled by an
|
||||||
|
agent running on the compute node (where communication with the
|
||||||
|
hypervisor is more efficient).
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
We only poll compute resources for now, but when other types of
|
||||||
|
polling are implemented the pollsters are likely to run somewhere
|
||||||
|
other than the compute node.
|
||||||
|
|
||||||
|
The agent daemon is configured to run one or more *pollster*
|
||||||
|
plugins using the ``ceilometer.poll.compute`` namespace. The agent
|
||||||
|
periodically asks each pollster for instances of ``Counter``
|
||||||
|
objects. The agent framework converts the Counters to metering
|
||||||
|
messages, which it then signs and transmits on the metering message
|
||||||
|
bus.
|
||||||
|
|
||||||
|
The pollster plugins do not communicate with the message bus directly,
|
||||||
|
unless it is necessary to do so in order to collect the information
|
||||||
|
for which they are polling.
|
||||||
|
|
||||||
|
All polling happens with the same frequency, controlled by a global
|
||||||
|
setting for the agent.
|
||||||
|
|
||||||
|
Handling Notifications
|
||||||
|
----------------------
|
||||||
|
|
||||||
|
.. index::
|
||||||
|
double: notifications; architecture
|
||||||
|
|
||||||
|
The heart of the system is the collector, which monitors the message
|
||||||
|
bus for data being provided by the pollsters via the agent as well as
|
||||||
|
notification messages from other OpenStack components such as nova,
|
||||||
|
glance, quantum, and swift.
|
||||||
|
|
||||||
|
The collector loads one or more *listener* plugins, using a namespace
|
||||||
|
under ``ceilometer.collector``. The namespace controls the exchange
|
||||||
|
and topic where the listener is subscribed. For example,
|
||||||
|
``ceilometer.collector.compute`` listens on the ``nova`` exchange to
|
||||||
|
the ``notifications.info`` topic while ``ceilometer.collector.image``
|
||||||
|
listens on the ``glance`` exchange for ``notifications.info``.
|
||||||
|
|
||||||
|
The plugin provides a method to list the event types it wants and a
|
||||||
|
callback for processing incoming messages. The registered name of the
|
||||||
|
callback is used to enable or disable it using the global
|
||||||
|
configuration option of the collector daemon. The incoming messages
|
||||||
|
are filtered based on their event type value before being passed to
|
||||||
|
the callback so the plugin only receives events it has expressed an
|
||||||
|
interest in seeing. For example, a callback asking for
|
||||||
|
``compute.instance.create.end`` events under
|
||||||
|
``ceilometer.collector.compute`` would be invoked for those
|
||||||
|
notification events on the ``nova`` exchange using the
|
||||||
|
``notifications.info`` topic.
|
||||||
|
|
||||||
|
The listener plugin returns an iterable with zero or more Counter
|
||||||
|
instances based on the data in the incoming message. The collector
|
||||||
|
framework code converts the Counter instances to metering messages and
|
||||||
|
publishes them on the metering message bus. Although ceilomter
|
||||||
|
includes a default storage solution to work with the API service, by
|
||||||
|
republishing on the metering message bus we can support installations
|
||||||
|
that want to handle their own data storage.
|
||||||
|
|
||||||
|
Handling Metering Messages
|
||||||
|
--------------------------
|
||||||
|
|
||||||
|
The listener for metering messages also runs in the collector
|
||||||
|
daemon. It validates the incoming data and (if the signature is valid)
|
||||||
|
then writes the messages to the data store.
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
Because this listener uses ``openstack.common.rpc`` instead of
|
||||||
|
notifications, it is implemented directly in the collector code
|
||||||
|
instead of as a plugin.
|
||||||
|
|
||||||
|
Metering messages are signed using the hmac_ module in Python's
|
||||||
|
standard library. A shared secret value can be provided in the
|
||||||
|
ceilometer configuration settings. The messages are signed by feeding
|
||||||
|
the message key names and values into the signature generator in
|
||||||
|
sorted order. Non-string values are converted to unicode and then
|
||||||
|
encoded as UTF-8. The message signature is included in the message for
|
||||||
|
verification by the collector, and stored in the database for future
|
||||||
|
verification by consumers who access the data via the API.
|
||||||
|
|
||||||
|
.. _hmac: http://docs.python.org/library/hmac.html
|
||||||
|
|
||||||
|
RPC
|
||||||
|
---
|
||||||
|
|
||||||
|
Ceilomter uses ``openstack.common.rpc`` to cast messages from the
|
||||||
|
agent to the collector.
|
||||||
|
|
||||||
|
.. seealso::
|
||||||
|
|
||||||
|
* http://wiki.openstack.org/EfficientMetering/ArchitectureProposalV1
|
||||||
|
* http://wiki.openstack.org/EfficientMetering#Architecture
|
||||||
|
* `Bug 1010037`_ : allow different polling interval for each pollster
|
||||||
|
|
||||||
|
.. _Bug 1010037: https://bugs.launchpad.net/ceilometer/+bug/1010037
|
||||||
@ -27,6 +27,8 @@ import sys, os
|
|||||||
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
|
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
|
||||||
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo']
|
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo']
|
||||||
|
|
||||||
|
todo_include_todos = True
|
||||||
|
|
||||||
# Add any paths that contain templates here, relative to this directory.
|
# Add any paths that contain templates here, relative to this directory.
|
||||||
templates_path = ['_templates']
|
templates_path = ['_templates']
|
||||||
|
|
||||||
|
|||||||
20
doc/source/configuration.rst
Normal file
20
doc/source/configuration.rst
Normal file
@ -0,0 +1,20 @@
|
|||||||
|
..
|
||||||
|
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.
|
||||||
|
|
||||||
|
=======================
|
||||||
|
Configuration Options
|
||||||
|
=======================
|
||||||
|
|
||||||
|
.. todo:: Document the configuration options.
|
||||||
56
doc/source/contributing/areas.rst
Normal file
56
doc/source/contributing/areas.rst
Normal file
@ -0,0 +1,56 @@
|
|||||||
|
..
|
||||||
|
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
|
||||||
|
=====================
|
||||||
|
|
||||||
|
Plugins
|
||||||
|
=======
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
.. 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 ``openstack-common``. Logging and RPC are already done, but
|
||||||
|
the service and manager base classes still need to move.
|
||||||
|
|
||||||
|
.. seealso::
|
||||||
|
|
||||||
|
* https://launchpad.net/openstack-nova
|
||||||
|
* https://launchpad.net/openstack-common
|
||||||
|
|
||||||
|
Testing
|
||||||
|
=======
|
||||||
|
|
||||||
|
The pre-release 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
Normal file
26
doc/source/contributing/index.rst
Normal file
@ -0,0 +1,26 @@
|
|||||||
|
..
|
||||||
|
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
|
||||||
@ -13,6 +13,10 @@
|
|||||||
License for the specific language governing permissions and limitations
|
License for the specific language governing permissions and limitations
|
||||||
under the License.
|
under the License.
|
||||||
|
|
||||||
|
=======================
|
||||||
|
Writing Agent Plugins
|
||||||
|
=======================
|
||||||
|
|
||||||
This documentation gives you some clues on how to write a
|
This documentation gives you some clues on how to write a
|
||||||
new agent or plugin for Ceilometer a to use if you wish to instrument a
|
new agent or plugin for Ceilometer a to use if you wish to instrument a
|
||||||
functionality which has not yet been covered by an existing one.
|
functionality which has not yet been covered by an existing one.
|
||||||
@ -99,4 +103,4 @@ Unit tests are run in a continuous integration process for each commit made to
|
|||||||
the project, thus ensuring as best as possible that a given patch has no side
|
the project, thus ensuring as best as possible that a given patch has no side
|
||||||
effect to the rest of the project.
|
effect to the rest of the project.
|
||||||
|
|
||||||
### FIXME: could not find a unit test for CPUPollster
|
.. todo:: FIXME: could not find a unit test for CPUPollster
|
||||||
30
doc/source/contributing/resources.rst
Normal file
30
doc/source/contributing/resources.rst
Normal file
@ -0,0 +1,30 @@
|
|||||||
|
..
|
||||||
|
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.
|
||||||
|
|
||||||
|
.. _resources:
|
||||||
|
|
||||||
|
=========================
|
||||||
|
Project Hosting Details
|
||||||
|
=========================
|
||||||
|
|
||||||
|
:Bug tracker: http://launchpad.net/ceilometer
|
||||||
|
:Mailing list: http://lists.launchpad.net/openstack (prefix subjects with ``[metering]`` for faster responses)
|
||||||
|
:Wiki: http://wiki.openstack.org/EfficientMetering
|
||||||
|
:Code Hosting: https://github.com/stackforge/ceilometer
|
||||||
|
:Code Review: https://review.openstack.org/#/q/status:open+project:stackforge/ceilometer,n,z
|
||||||
|
|
||||||
|
.. seealso::
|
||||||
|
|
||||||
|
* :ref:`user`
|
||||||
80
doc/source/contributing/source.rst
Normal file
80
doc/source/contributing/source.rst
Normal file
@ -0,0 +1,80 @@
|
|||||||
|
..
|
||||||
|
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.
|
||||||
|
|
||||||
|
=========================
|
||||||
|
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://github.com/stackforge/ceilometer.git
|
||||||
|
$ cd ./ceilometer
|
||||||
|
|
||||||
|
2. Once this is done, you need to setup the review process::
|
||||||
|
|
||||||
|
$ git remote add gerrit ssh://<username>@review.stackforge.org:29418/stackforge/ceilometer.git
|
||||||
|
|
||||||
|
3. 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
|
||||||
|
=================
|
||||||
|
|
||||||
|
Ceiloemter includes an extensive set of automated unit tests which are
|
||||||
|
run through tox_.
|
||||||
|
|
||||||
|
1. Install ``tox``::
|
||||||
|
|
||||||
|
$ sudo pip install tox
|
||||||
|
|
||||||
|
2. Install the test dependencies::
|
||||||
|
|
||||||
|
$ sudo pip install -r /opt/stack/ceilometer/tools/test-requires
|
||||||
|
|
||||||
|
3. Run the unit and code-style tests::
|
||||||
|
|
||||||
|
$ cd /opt/stack/ceilometer
|
||||||
|
$ tox -e py27,pep8
|
||||||
|
|
||||||
|
.. seealso::
|
||||||
|
|
||||||
|
* 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://wiki.openstack.org/GerritWorkflow
|
||||||
|
* `OpenStack Gerrit instance`_.
|
||||||
|
|
||||||
|
.. _OpenStack Gerrit instance: https://review.openstack.org/#/q/status:open+project:stackforge/ceilometer,n,z
|
||||||
48
doc/source/contributing/user.rst
Normal file
48
doc/source/contributing/user.rst
Normal file
@ -0,0 +1,48 @@
|
|||||||
|
..
|
||||||
|
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://wiki.openstack.org/HowToContribute
|
||||||
|
* 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
|
||||||
55
doc/source/glossary.rst
Normal file
55
doc/source/glossary.rst
Normal file
@ -0,0 +1,55 @@
|
|||||||
|
..
|
||||||
|
Copyright 2012 New Dream Network (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.
|
||||||
|
|
||||||
|
==========
|
||||||
|
Glossary
|
||||||
|
==========
|
||||||
|
|
||||||
|
.. glossary::
|
||||||
|
|
||||||
|
agent
|
||||||
|
Software service running on the OpenStack infrastructure
|
||||||
|
measuring usage and sending the results to the :term:`collector`.
|
||||||
|
|
||||||
|
API server
|
||||||
|
HTTP REST API service for ceilometer.
|
||||||
|
|
||||||
|
ceilometer
|
||||||
|
From WikiPedia [#]_:
|
||||||
|
|
||||||
|
A ceilometer is a device that uses a laser or other light
|
||||||
|
source to determine the height of a cloud base.
|
||||||
|
|
||||||
|
collector
|
||||||
|
Software service running on the OpenStack infrastructure
|
||||||
|
monitoring notifications from other OpenStack components and
|
||||||
|
meter events from the ceilometer agent and recording the results
|
||||||
|
in the database.
|
||||||
|
|
||||||
|
data store
|
||||||
|
Storage system for recording data collected by ceilometer.
|
||||||
|
|
||||||
|
non-repudiable
|
||||||
|
From WikiPedia [#]_:
|
||||||
|
|
||||||
|
Non-repudiation refers to a state of affairs where the purported
|
||||||
|
maker of a statement will not be able to successfully challenge
|
||||||
|
the validity of the statement or contract. The term is often
|
||||||
|
seen in a legal setting wherein the authenticity of a signature
|
||||||
|
is being challenged. In such an instance, the authenticity is
|
||||||
|
being "repudiated".
|
||||||
|
|
||||||
|
.. [#] http://en.wikipedia.org/wiki/Ceilometer
|
||||||
|
.. [#] http://en.wikipedia.org/wiki/Non-repudiation
|
||||||
@ -17,37 +17,63 @@
|
|||||||
Welcome to the Ceilometer developer documentation!
|
Welcome to the Ceilometer developer documentation!
|
||||||
==================================================
|
==================================================
|
||||||
|
|
||||||
The ceilometer project aims to deliver a unique point of contact for billing
|
The :term:`ceilometer` project aims to deliver a unique point of
|
||||||
systems to acquire all meters they need to establish customer billing, across
|
contact for billing systems to acquire all of the measurements they
|
||||||
all current OpenStack core components with work underway to support future
|
need to establish customer billing, across all current OpenStack core
|
||||||
OpenStack components through plugin agents.
|
components with work underway to support future OpenStack components.
|
||||||
|
|
||||||
A list of the current usage data that ceilometer will (eventually) listen for
|
|
||||||
can be found at http://wiki.openstack.org/SystemUsageData. For a list of the
|
|
||||||
planned meters, refer to http://wiki.openstack.org/EfficientMetering#Meters.
|
|
||||||
|
|
||||||
A list of the additional usage data is tracked in the bug tracker at https://bugs.launchpad.net/ceilometer.
|
|
||||||
|
|
||||||
What is the purpose of the project and vision for it?
|
What is the purpose of the project and vision for it?
|
||||||
=====================================================
|
=====================================================
|
||||||
|
|
||||||
* Provide efficient collection of metering data, in terms of CPU and network costs.
|
* Provide efficient collection of metering data, in terms of CPU and
|
||||||
* Allow deployers to integrate with the metering system directly or by replacing components.
|
network costs.
|
||||||
* Data may be collected by monitoring notifications sent from existing services or by polling the infrastructure.
|
* Allow deployers to integrate with the metering system directly or by
|
||||||
* Allow deployers to configure the type of data collected to meet their operating requirements.
|
replacing components.
|
||||||
* The data collected by the metering system is made visible to some users through a REST API.
|
* Data may be collected by monitoring notifications sent from existing
|
||||||
* The metering messages are signed and non-repudiable. (http://en.wikipedia.org/wiki/Non-repudiation)
|
services or by polling the infrastructure.
|
||||||
|
* Allow deployers to configure the type of data collected to meet
|
||||||
|
their operating requirements.
|
||||||
|
* The data collected by the metering system is made visible to some
|
||||||
|
users through a REST API.
|
||||||
|
* The metering messages are signed and :term:`non-repudiable`.
|
||||||
|
|
||||||
This documentation offers information on how to contribute code to ceilometer.
|
This documentation offers information on ceilometer works and how to
|
||||||
|
contribute to the project.
|
||||||
|
|
||||||
Table of contents
|
Table of contents
|
||||||
=================
|
=================
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 1
|
:maxdepth: 2
|
||||||
|
|
||||||
initial_setup
|
architecture
|
||||||
agent/writing_agent_plugin
|
measurements
|
||||||
|
install
|
||||||
|
configuration
|
||||||
|
contributing/index
|
||||||
|
glossary
|
||||||
|
|
||||||
|
.. - installation
|
||||||
|
.. - devstack
|
||||||
|
.. - take content from "initial setup"
|
||||||
|
.. - configuration
|
||||||
|
.. - talk about copying nova config file
|
||||||
|
.. - running the services
|
||||||
|
.. - agent on compute node
|
||||||
|
.. - collector on controller (non-compute) node
|
||||||
|
.. - contributing
|
||||||
|
.. - joining the project (take this from another set of docs?)
|
||||||
|
.. - reporting bugs
|
||||||
|
.. - running tests
|
||||||
|
.. - submitting patches for review
|
||||||
|
.. - writing plugins
|
||||||
|
.. - general plugin-based architecture information
|
||||||
|
.. - reference to setuptools entry points docs
|
||||||
|
.. - pollsters
|
||||||
|
.. - notifications
|
||||||
|
.. - database engine
|
||||||
|
|
||||||
|
.. update index
|
||||||
|
|
||||||
Indices and tables
|
Indices and tables
|
||||||
==================
|
==================
|
||||||
@ -55,3 +81,8 @@ Indices and tables
|
|||||||
* :ref:`genindex`
|
* :ref:`genindex`
|
||||||
* :ref:`modindex`
|
* :ref:`modindex`
|
||||||
* :ref:`search`
|
* :ref:`search`
|
||||||
|
|
||||||
|
To Do
|
||||||
|
=====
|
||||||
|
|
||||||
|
.. todolist::
|
||||||
|
|||||||
@ -1,47 +0,0 @@
|
|||||||
..
|
|
||||||
Copyright 2012 Nicolas Barcet for Canonical
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
Initial setup
|
|
||||||
=============
|
|
||||||
|
|
||||||
If you are not yet familiar with ceilometer's architecture, it would be
|
|
||||||
advisable that you start by reading the blueprint at http://wiki.openstack.org/EfficientMetering, and more specifically the architecture which has been agreed on
|
|
||||||
at: http://wiki.openstack.org/EfficientMetering/ArchitectureProposalV1.
|
|
||||||
|
|
||||||
In order to contribute to the ceilometer project, you will also need to:
|
|
||||||
|
|
||||||
1. Have signed OpenStack's contributor's agreement. Refer to http://wiki.openstack.org/CLA for more information.
|
|
||||||
|
|
||||||
2. Be familiar with git and the OpenStack Gerrit review process, see http://wiki.openstack.org/GerritWorkflow.
|
|
||||||
|
|
||||||
.. note::
|
|
||||||
|
|
||||||
Currently the ceilometer project is using StackForge, a
|
|
||||||
system for code reviews identical to the OpenStack contribution infrastructure.
|
|
||||||
|
|
||||||
Setting up the project
|
|
||||||
======================
|
|
||||||
|
|
||||||
1. The first thing you will need to do is to clone the ceilometer project on your local machine::
|
|
||||||
|
|
||||||
git clone https://github.com/stackforge/ceilometer.git
|
|
||||||
|
|
||||||
2. Once this is done, you need to setup the review process::
|
|
||||||
|
|
||||||
git remote add gerrit ssh://<username>@review.stackforge.org:29418/stackforge/ceilometer.git
|
|
||||||
|
|
||||||
3. Create a topic branch and switch to it::
|
|
||||||
|
|
||||||
git checkout -b TOPIC-BRANCH
|
|
||||||
147
doc/source/install.rst
Normal file
147
doc/source/install.rst
Normal file
@ -0,0 +1,147 @@
|
|||||||
|
..
|
||||||
|
Copyright 2012 Nicolas Barcet for Canonical
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
.. _install:
|
||||||
|
|
||||||
|
================================================
|
||||||
|
Installing and Running the Development Version
|
||||||
|
================================================
|
||||||
|
|
||||||
|
Ceilometer has two daemons. The :term:`agent` runs on the Nova compute
|
||||||
|
node(s) and the :term:`collector` runs on the cloud's management
|
||||||
|
node(s). In a development environment created by devstack_, these two
|
||||||
|
are typically the same server. They do not have to be, though, so some
|
||||||
|
of the instructions below are duplicated. Skip the steps you have
|
||||||
|
already done.
|
||||||
|
|
||||||
|
.. _devstack: http://www.devstack.org/
|
||||||
|
|
||||||
|
Installing the Collector
|
||||||
|
========================
|
||||||
|
|
||||||
|
.. index::
|
||||||
|
double: installing; collector
|
||||||
|
|
||||||
|
1. Install and configure nova.
|
||||||
|
|
||||||
|
The collector daemon imports code from ``nova``, so it needs to be
|
||||||
|
run on a server where nova has already been installed.
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
Ceilometer makes extensive use of the messaging bus, but has not
|
||||||
|
yet been tested with ZeroMQ. We recommend using Rabbit or qpid
|
||||||
|
for now.
|
||||||
|
|
||||||
|
2. Install MongoDB.
|
||||||
|
|
||||||
|
Follow the instructions to install the MongoDB_ package for your
|
||||||
|
operating system, then start the service.
|
||||||
|
|
||||||
|
3. Clone the ceilometer git repository to the management server::
|
||||||
|
|
||||||
|
$ cd /opt/stack
|
||||||
|
$ git clone https://github.com/stackforge/ceilometer.git
|
||||||
|
|
||||||
|
4. As a user with ``root`` permissions or ``sudo`` privileges, run the
|
||||||
|
ceilometer installer::
|
||||||
|
|
||||||
|
$ cd ceilometer
|
||||||
|
$ sudo python setup.py install
|
||||||
|
|
||||||
|
5. Configure ceilometer.
|
||||||
|
|
||||||
|
Ceilometer needs to know about some of the nova configuration
|
||||||
|
options, so the simplest way to start is copying
|
||||||
|
``/etc/nova/nova.conf`` to ``/etc/ceilometer-collector.conf``. Some
|
||||||
|
of the logging settings used in nova break ceilometer, so they need
|
||||||
|
to be removed. For example, as a user with ``root`` permissions::
|
||||||
|
|
||||||
|
$ grep -v format_string /etc/nova/nova.conf > /etc/ceilometer-collector.conf
|
||||||
|
|
||||||
|
Refer to :doc:`configuration` for details about any other options
|
||||||
|
you might want to modify before starting the service.
|
||||||
|
|
||||||
|
6. Start the collector.
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
$ ./bin/ceilometer-collector
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
The default development configuration of the collector logs to
|
||||||
|
stderr, so you may want to run this step using a screen session
|
||||||
|
or other tool for maintaining a long-running program in the
|
||||||
|
background.
|
||||||
|
|
||||||
|
.. _MongoDB: http://www.mongodb.org/
|
||||||
|
|
||||||
|
|
||||||
|
Installing the Compute Agent
|
||||||
|
============================
|
||||||
|
|
||||||
|
.. index::
|
||||||
|
double: installing; compute agent
|
||||||
|
|
||||||
|
.. note:: The compute agent must be installed on each nova compute node.
|
||||||
|
|
||||||
|
1. Install and configure nova.
|
||||||
|
|
||||||
|
The collector daemon imports code from ``nova``, so it needs to be
|
||||||
|
run on a server where nova has already been installed.
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
Ceilometer makes extensive use of the messaging bus, but has not
|
||||||
|
yet been tested with ZeroMQ. We recommend using Rabbit or qpid
|
||||||
|
for now.
|
||||||
|
|
||||||
|
2. Clone the ceilometer git repository to the server::
|
||||||
|
|
||||||
|
$ cd /opt/stack
|
||||||
|
$ git clone https://github.com/stackforge/ceilometer.git
|
||||||
|
|
||||||
|
4. As a user with ``root`` permissions or ``sudo`` privileges, run the
|
||||||
|
ceilometer installer::
|
||||||
|
|
||||||
|
$ cd ceilometer
|
||||||
|
$ sudo python setup.py install
|
||||||
|
|
||||||
|
5. Configure ceilometer.
|
||||||
|
|
||||||
|
Ceilometer needs to know about some of the nova configuration
|
||||||
|
options, so the simplest way to start is copying
|
||||||
|
``/etc/nova/nova.conf`` to ``/etc/ceilometer-agent.conf``. Some
|
||||||
|
of the logging settings used in nova break ceilometer, so they need
|
||||||
|
to be removed. For example, as a user with ``root`` permissions::
|
||||||
|
|
||||||
|
$ grep -v format_string /etc/nova/nova.conf > /etc/ceilometer-agent.conf
|
||||||
|
|
||||||
|
Refer to :doc:`configuration` for details about any other options
|
||||||
|
you might want to modify before starting the service.
|
||||||
|
|
||||||
|
6. Start the agent.
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
$ ./bin/ceilometer-agent
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
The default development configuration of the agent logs to
|
||||||
|
stderr, so you may want to run this step using a screen session
|
||||||
|
or other tool for maintaining a long-running program in the
|
||||||
|
background.
|
||||||
29
doc/source/measurements.rst
Normal file
29
doc/source/measurements.rst
Normal file
@ -0,0 +1,29 @@
|
|||||||
|
..
|
||||||
|
Copyright 2012 New Dream Network (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.
|
||||||
|
|
||||||
|
==============
|
||||||
|
Measurements
|
||||||
|
==============
|
||||||
|
|
||||||
|
A list of the current usage data that ceilometer will (eventually) listen for
|
||||||
|
can be found at:
|
||||||
|
|
||||||
|
http://wiki.openstack.org/SystemUsageData.
|
||||||
|
|
||||||
|
For a list of the planned meters, refer to:
|
||||||
|
|
||||||
|
http://wiki.openstack.org/EfficientMetering#Meters.
|
||||||
|
|
||||||
|
.. todo:: Replicate the list of meters here.
|
||||||
Loading…
x
Reference in New Issue
Block a user