ceilometer/doc/source/contributor/plugins.rst

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.

Plugin Framework

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.

Polling Agents

The polling agent is implemented in ceilometer/polling/manager.py. As you will see in the manager, the agent loads all plugins defined in the ceilometer.poll.* and ceilometer.builder.poll.* namespaces, then periodically calls their get_samples method.

Currently we keep separate namespaces - ceilometer.poll.compute and ceilometer.poll.central for quick separation of what to poll depending on where is polling agent running. For example, this will load, among others, the ceilometer.compute.pollsters.instance_stats.CPUPollster

Pollster

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 ceilometer/sample.py file.

Compute plugins are defined as subclasses of the ceilometer.compute.pollsters.GenericComputePollster class as defined in the ceilometer/compute/pollsters/__init__.py file.

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 of resources.

Notifications

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 ceilometer.notification.pipeline.

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 endpoint inherits ceilometer.pipeline.base.MainNotificationEndpoint and defines which notification priorities to listen, normalises the data, and redirects the data for pipeline processing or requeuing depending on workload_partitioning configuration.

If a pipeline is configured to support workload_partitioning, data from the main queue endpoints are shared and requeued in internal queues. The notification agent configures a second notification consumer to handle these internal queues and pushes data to endpoints defined by get_interim_endpoints in the pipeline manager. These interim endpoints define how to handle the shared, normalised data models for pipeline processing

Both main queue and interim queue notification endpoints should implement:

event_types

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_types and returns a sequence of objects. Using the SampleEndpoint, it should yield Sample objects as defined in the ceilometer/sample.py file.

Two pipeline configurations exist and can be found under ceilometer.pipeline.*. The sample pipeline loads in multiple endpoints defined in ceilometer.sample.endpoint namespace. Each of the endpoints normalises a given notification into different samples.