From 1f9bce260993d714dc17ec24fd484332b783c0ef Mon Sep 17 00:00:00 2001 From: Doug Hellmann Date: Thu, 5 Jul 2012 11:08:01 -0400 Subject: [PATCH] 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 --- doc/source/architecture.rst | 215 ++++++++++++++++++ doc/source/conf.py | 2 + doc/source/configuration.rst | 20 ++ doc/source/contributing/areas.rst | 56 +++++ doc/source/contributing/index.rst | 26 +++ .../plugins.rst} | 6 +- doc/source/contributing/resources.rst | 30 +++ doc/source/contributing/source.rst | 80 +++++++ doc/source/contributing/user.rst | 48 ++++ doc/source/glossary.rst | 55 +++++ doc/source/index.rst | 71 ++++-- doc/source/initial_setup.rst | 47 ---- doc/source/install.rst | 147 ++++++++++++ doc/source/measurements.rst | 29 +++ 14 files changed, 764 insertions(+), 68 deletions(-) create mode 100644 doc/source/architecture.rst create mode 100644 doc/source/configuration.rst create mode 100644 doc/source/contributing/areas.rst create mode 100644 doc/source/contributing/index.rst rename doc/source/{agent/writing_agent_plugin.rst => contributing/plugins.rst} (97%) create mode 100644 doc/source/contributing/resources.rst create mode 100644 doc/source/contributing/source.rst create mode 100644 doc/source/contributing/user.rst create mode 100644 doc/source/glossary.rst delete mode 100644 doc/source/initial_setup.rst create mode 100644 doc/source/install.rst create mode 100644 doc/source/measurements.rst diff --git a/doc/source/architecture.rst b/doc/source/architecture.rst new file mode 100644 index 0000000000..84f90c6d8f --- /dev/null +++ b/doc/source/architecture.rst @@ -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 diff --git a/doc/source/conf.py b/doc/source/conf.py index 87294bd09a..5ff19f1b43 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -27,6 +27,8 @@ import sys, os # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo'] +todo_include_todos = True + # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst new file mode 100644 index 0000000000..09198032a1 --- /dev/null +++ b/doc/source/configuration.rst @@ -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. diff --git a/doc/source/contributing/areas.rst b/doc/source/contributing/areas.rst new file mode 100644 index 0000000000..446ed78264 --- /dev/null +++ b/doc/source/contributing/areas.rst @@ -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` diff --git a/doc/source/contributing/index.rst b/doc/source/contributing/index.rst new file mode 100644 index 0000000000..d570eaaf0b --- /dev/null +++ b/doc/source/contributing/index.rst @@ -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 diff --git a/doc/source/agent/writing_agent_plugin.rst b/doc/source/contributing/plugins.rst similarity index 97% rename from doc/source/agent/writing_agent_plugin.rst rename to doc/source/contributing/plugins.rst index 17b94fb611..edf54b6ffa 100644 --- a/doc/source/agent/writing_agent_plugin.rst +++ b/doc/source/contributing/plugins.rst @@ -13,6 +13,10 @@ License for the specific language governing permissions and limitations under the License. +======================= + Writing Agent Plugins +======================= + 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 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 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 diff --git a/doc/source/contributing/resources.rst b/doc/source/contributing/resources.rst new file mode 100644 index 0000000000..fd1ce5b61e --- /dev/null +++ b/doc/source/contributing/resources.rst @@ -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` diff --git a/doc/source/contributing/source.rst b/doc/source/contributing/source.rst new file mode 100644 index 0000000000..bce295778d --- /dev/null +++ b/doc/source/contributing/source.rst @@ -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://@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 diff --git a/doc/source/contributing/user.rst b/doc/source/contributing/user.rst new file mode 100644 index 0000000000..5598576f47 --- /dev/null +++ b/doc/source/contributing/user.rst @@ -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 diff --git a/doc/source/glossary.rst b/doc/source/glossary.rst new file mode 100644 index 0000000000..c5a2d6e058 --- /dev/null +++ b/doc/source/glossary.rst @@ -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 diff --git a/doc/source/index.rst b/doc/source/index.rst index 1627a2bb96..2187fc8769 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -17,37 +17,63 @@ Welcome to the Ceilometer developer documentation! ================================================== -The ceilometer project aims to deliver a unique point of contact for billing -systems to acquire all meters they need to establish customer billing, across -all current OpenStack core components with work underway to support future -OpenStack components through plugin agents. - -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. +The :term:`ceilometer` project aims to deliver a unique point of +contact for billing systems to acquire all of the measurements they +need to establish customer billing, across all current OpenStack core +components with work underway to support future OpenStack components. What is the purpose of the project and vision for it? ===================================================== -* Provide efficient collection of metering data, in terms of CPU and network costs. -* Allow deployers to integrate with the metering system directly or by replacing components. -* Data may be collected by monitoring notifications sent from existing 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 non-repudiable. (http://en.wikipedia.org/wiki/Non-repudiation) +* Provide efficient collection of metering data, in terms of CPU and + network costs. +* Allow deployers to integrate with the metering system directly or by + replacing components. +* Data may be collected by monitoring notifications sent from existing + 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 ================= .. toctree:: - :maxdepth: 1 + :maxdepth: 2 - initial_setup - agent/writing_agent_plugin + architecture + 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 ================== @@ -55,3 +81,8 @@ Indices and tables * :ref:`genindex` * :ref:`modindex` * :ref:`search` + +To Do +===== + +.. todolist:: diff --git a/doc/source/initial_setup.rst b/doc/source/initial_setup.rst deleted file mode 100644 index 0031e63486..0000000000 --- a/doc/source/initial_setup.rst +++ /dev/null @@ -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://@review.stackforge.org:29418/stackforge/ceilometer.git - -3. Create a topic branch and switch to it:: - - git checkout -b TOPIC-BRANCH diff --git a/doc/source/install.rst b/doc/source/install.rst new file mode 100644 index 0000000000..aeccc6716c --- /dev/null +++ b/doc/source/install.rst @@ -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. diff --git a/doc/source/measurements.rst b/doc/source/measurements.rst new file mode 100644 index 0000000000..125ff5ded8 --- /dev/null +++ b/doc/source/measurements.rst @@ -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.