First draft of plugin/agent documentation. Fixes bug 1018311.
Change-Id: I5723ab7cdf3f552b23927380a764c53f7beb4f10
This commit is contained in:
Nicolas Barcet (nijaba)
parent
d179cbf4ef
commit
1b7b651d86
99
doc/dev/agent/writing_agent_plugin.rst
Normal file
99
doc/dev/agent/writing_agent_plugin.rst
Normal file
@ -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
|
||||||
|
|
||||||
|
|
||||||
48
doc/dev/index.rst
Normal file
48
doc/dev/index.rst
Normal file
@ -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`
|
||||||
44
doc/dev/initial_setup.rst
Normal file
44
doc/dev/initial_setup.rst
Normal file
@ -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://<username>@review.stackforge.org:29418/stackforge/ceilometer.git
|
||||||
|
|
||||||
|
3. Create a topic branch and switch to it
|
||||||
|
git checkout -b TOPIC-BRANCH
|
||||||
|
|
||||||
Loading…
Reference in New Issue
Block a user