First draft of plugin/agent documentation. Fixes bug 1018311.
Change-Id: I5723ab7cdf3f552b23927380a764c53f7beb4f10
This commit is contained in:
Nicolas Barcet (nijaba)
parent
d179cbf4ef
commit
1b7b651d86
|
|
@ -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
|
||||
|
||||
|
||||
|
|
@ -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`
|
||||
|
|
@ -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