diff --git a/doc/dev/agent/writing_agent_plugin.rst b/doc/dev/agent/writing_agent_plugin.rst new file mode 100644 index 000000000..9b7fa73e9 --- /dev/null +++ b/doc/dev/agent/writing_agent_plugin.rst @@ -0,0 +1,99 @@ +.. + 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. + +This documentation has for objective to give 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. + +Agent +===== +There is currently only one agent defined for Ceilometer which can be found at: ``ceilometer/agent/`` +As you will see in the ``manager.py`` file, this agent will automatically load any +plugin defined in the namesace ``ceilometer.poll.compute``. + +Agents are added by implementing a new nova.manager.Manager class, in the same +way it was done for the AgentManager for the compute agent in the file +``ceilometer/agent/manager.py``. + +Plugins +======= +An agent can support multiple plugins to retrieve different information and +send them to the collector. As stated above, an agent will automatically +activate all plugins of a given class. For example, the compute agent will +load all plugins of class ``ceilometer.poll.compute``. This will load, among +others, the ceilometer.compute.libvirt.CPUPollster, which is defined in the +file ``ceilometer/compute/libvirt.py`` as well as the ceilometer.compute.notifications.InstanceNotifications plugin +which is defined in the file ``ceilometer/compute/notifications.py`` + +We are using these two existing plugins as examples as the first one provides +an example of how to interact when you need to retrieve information from an +external system (pollster) and the second one is an example of how to forward +an existing event notification on the standard OpenStack queue to ceilometer. + +Pollster +-------- +Pollsters are defined as subclasses of the ``ceilometer.plugin.PollsterBase`` meta +class as defined in the ``ceilometer/plugin.py`` file. Pollsters must implement +one method: ``get_counters(self, manager, context)``, which returns a +a sequence of ``Counter`` objects as defined in the ``ceilometer/counter.py`` file. + +In the ``CPUPollster`` plugin, the ``get_counters`` method is implemented as a loop +which, for each instances running on the local host, retrieves the cpu_time +from libvirt and send back two ``Counter`` objects. The first one, named +"cpu", is of type "cumulative", meaning that between two polls, its value is +not reset, or in other word that the cpu value is always provided as a duration +that continuously increases since the creation of the instance. The second one, +named "instance", is of type "delta", meaning that it's value is just the +volume since the last poll. Here, the instance counter is only used as a way +to tell the system that the instance is still running, hence the hard coded +value of 1. + +Note that the ``LOG`` method is only used as a debugging tool and does not +participate in the actual metering activity. + +Notification +------------ +Notifiications are defined as subclass of the ``ceilometer.plugin.NotificationBase`` +meta class as defined in the ``ceilometer/plugin.py`` file. Notifications must +implement two methods: + + ``get_event_types(self)`` which should return a sequence of strings defining the event types to be given to the plugin and + + ``process_notification(self, message)`` which receives an event message from the list provided to get_event_types and returns a sequence of Counter objects as defined in the ``ceilometer/counter.py`` file. + +In the ``InstanceNotifications`` plugin, it listens to three events: + +* compute.instance.create.end + +* compute.instance.exists + +* compute.instance.delete.start + +using the ``get_event_type`` method and subsequently the method +``process_notification`` will be invoked each time such events are happening which +generates the appropriate counter objects to be sent to the collector. + +Tests +===== +Any new plugin or agent contribution will only be accepted into the project if +provided together with unit tests. Those are defined for the compute agent +plugins in the directory ``tests/compute`` and for the agent itself in ``test/agent``. +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 + + diff --git a/doc/dev/index.rst b/doc/dev/index.rst new file mode 100644 index 000000000..fb5180fee --- /dev/null +++ b/doc/dev/index.rst @@ -0,0 +1,48 @@ +.. + 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. + +================================================== +Welcome to the Ceilometer developer documentation! +================================================== + +The ceilometer project aims to deliver a unique point of contact for billing systems to aquire all meters they need to establish customer billing, accross all current and future OpenStack core 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) + +This documentation has for objective to give you some clues on how to contribute code to ceilometer. + +Table of content +================ + +.. toctree:: + :maxdepth: 1 + + initial_setup + agent/writing_plugin_agent + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/doc/dev/initial_setup.rst b/doc/dev/initial_setup.rst new file mode 100644 index 000000000..3cb58ed6e --- /dev/null +++ b/doc/dev/initial_setup.rst @@ -0,0 +1,44 @@ +.. + 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 reading +=============== + +If you are not yet familiar with ceilometer's architecture, it would be +advisable that you start by reading the blueprint: + http://wiki.openstack.org/EfficientMetering +and more specifically the architecture which has been agreed on: + 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 + http://wiki.openstack.org/CLA + +2. Be familiar with git and the OpenStack gerrit review process + http://wiki.openstack.org/GerritWorkflow + +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 +