Writing Agent Plugins¶
This documentation gives you some clues on how to write a new agent or plugin for Ceilometer if you wish to instrument a measurement which has not yet been covered by an existing plugin.
Although we have described a list of the meters 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 agents. In particular,
Ceilometer now uses Stevedore, and you should put your entry point
definitions in the
entry_points.txt file of your Ceilometer egg.
Installing a plugin automatically activates it the next time the ceilometer daemon starts. 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). Additionally, if no valid resources can be discovered the plugin will be disabled.
The polling agent is implemented in
you will see in the manager, the agent loads all plugins defined in
ceilometer.builder.poll.* namespaces, then
periodically calls their
Currently we keep separate namespaces -
ceilometer.poll.central for quick separation of what to poll depending
on where is polling agent running. For example, this will load, among others,
All pollsters are subclasses of
ceilometer.polling.plugin_base.PollsterBase class. Pollsters must
implement one method:
get_samples(self, manager, cache, resources), which
returns a sequence of
Sample objects as defined in the
Compute plugins are defined as subclasses of the
ceilometer.compute.pollsters.GenericComputePollster class as defined
For example, in the
CPUPollster plugin, the
get_samples method takes
in a given list of resources representing instances on the local host, loops
through them and retrieves the cpu time details from resource. Similarly,
other metrics are built by pulling the appropriate value from the given list
Notifications in OpenStack are consumed by the notification agent and passed through pipelines to be normalised and re-published to specified targets.
The existing normalisation pipelines are defined in the namespace
Each normalisation pipeline are defined as subclass of
ceilometer.pipeline.base.PipelineManager which interprets and builds
pipelines based on a given configuration file. Pipelines are required to define
Source and Sink permutations to describe how to process notification.
Additionally, it must set
get_main_endpoints which provides endpoints to be
added to the main queue listener in the notification agent. This main queue
and defines which notification priorities to listen, normalises the data,
and redirects the data for pipeline processing.
Notification endpoints should implement:
A sequence of strings defining the event types the endpoint should handle
process_notifications(self, priority, notifications)
Receives an event message from the list provided to
event_typesand returns a sequence of objects. Using the SampleEndpoint, it should yield
Sampleobjects as defined in the
Two pipeline configurations exist and can be found under
ceilometer.pipeline.*. The sample pipeline loads in multiple endpoints
ceilometer.sample.endpoint namespace. Each of the endpoints
normalises a given notification into different samples.