6b0318e9c7
Events are valuable for understanding system state, so we need to continue to support them. Change-Id: I15f2675a3538c38c834284e1c73decebff5521ed
165 lines
6.4 KiB
ReStructuredText
165 lines
6.4 KiB
ReStructuredText
======
|
|
Events
|
|
======
|
|
|
|
In addition to meters, the Telemetry service collects events triggered
|
|
within an OpenStack environment. This section provides a brief summary
|
|
of the events format in the Telemetry service.
|
|
|
|
While a sample represents a single, numeric datapoint within a
|
|
time-series, an event is a broader concept that represents the state of
|
|
a resource at a point in time. The state may be described using various
|
|
data types including non-numeric data such as an instance's flavor. In
|
|
general, events represent any action made in the OpenStack system.
|
|
|
|
Event configuration
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
By default, ceilometer builds event data from the messages it receives from
|
|
other OpenStack services.
|
|
|
|
.. note::
|
|
|
|
In releases older than Ocata, it is advisable to set
|
|
``disable_non_metric_meters`` to ``True`` when enabling events in the
|
|
Telemetry service. The Telemetry service historically represented events as
|
|
metering data, which may create duplication of data if both events and
|
|
non-metric meters are enabled.
|
|
|
|
Event structure
|
|
~~~~~~~~~~~~~~~
|
|
|
|
Events captured by the Telemetry service are represented by five key
|
|
attributes:
|
|
|
|
event\_type
|
|
A dotted string defining what event occurred such as
|
|
``"compute.instance.resize.start"``.
|
|
|
|
message\_id
|
|
A UUID for the event.
|
|
|
|
generated
|
|
A timestamp of when the event occurred in the system.
|
|
|
|
traits
|
|
A flat mapping of key-value pairs which describe the event. The
|
|
event's traits contain most of the details of the event. Traits are
|
|
typed, and can be strings, integers, floats, or datetimes.
|
|
|
|
raw
|
|
Mainly for auditing purpose, the full event message can be stored
|
|
(unindexed) for future evaluation.
|
|
|
|
Event indexing
|
|
~~~~~~~~~~~~~~
|
|
|
|
The general philosophy of notifications in OpenStack is to emit any and
|
|
all data someone might need, and let the consumer filter out what they
|
|
are not interested in. In order to make processing simpler and more
|
|
efficient, the notifications are stored and processed within Ceilometer
|
|
as events. The notification payload, which can be an arbitrarily complex
|
|
JSON data structure, is converted to a flat set of key-value pairs. This
|
|
conversion is specified by a config file.
|
|
|
|
.. note::
|
|
|
|
The event format is meant for efficient processing and querying.
|
|
Storage of complete notifications for auditing purposes can be
|
|
enabled by configuring ``store_raw`` option.
|
|
|
|
Event conversion
|
|
----------------
|
|
|
|
The conversion from notifications to events is driven by a configuration
|
|
file defined by the ``definitions_cfg_file`` in the ``ceilometer.conf``
|
|
configuration file.
|
|
|
|
This includes descriptions of how to map fields in the notification body
|
|
to Traits, and optional plug-ins for doing any programmatic translations
|
|
(splitting a string, forcing case).
|
|
|
|
The mapping of notifications to events is defined per event\_type, which
|
|
can be wildcarded. Traits are added to events if the corresponding
|
|
fields in the notification exist and are non-null.
|
|
|
|
.. note::
|
|
|
|
The default definition file included with the Telemetry service
|
|
contains a list of known notifications and useful traits. The
|
|
mappings provided can be modified to include more or less data
|
|
according to user requirements.
|
|
|
|
If the definitions file is not present, a warning will be logged, but an
|
|
empty set of definitions will be assumed. By default, any notifications
|
|
that do not have a corresponding event definition in the definitions
|
|
file will be converted to events with a set of minimal traits. This can
|
|
be changed by setting the option ``drop_unmatched_notifications`` in the
|
|
``ceilometer.conf`` file. If this is set to ``True``, any unmapped
|
|
notifications will be dropped.
|
|
|
|
The basic set of traits (all are TEXT type) that will be added to all
|
|
events if the notification has the relevant data are: service
|
|
(notification's publisher), tenant\_id, and request\_id. These do not
|
|
have to be specified in the event definition, they are automatically
|
|
added, but their definitions can be overridden for a given event\_type.
|
|
|
|
Event definitions format
|
|
------------------------
|
|
|
|
The event definitions file is in YAML format. It consists of a list of
|
|
event definitions, which are mappings. Order is significant, the list of
|
|
definitions is scanned in reverse order to find a definition which
|
|
matches the notification's event\_type. That definition will be used to
|
|
generate the event. The reverse ordering is done because it is common to
|
|
want to have a more general wildcarded definition (such as
|
|
``compute.instance.*``) with a set of traits common to all of those
|
|
events, with a few more specific event definitions afterwards that have
|
|
all of the above traits, plus a few more.
|
|
|
|
Each event definition is a mapping with two keys:
|
|
|
|
event\_type
|
|
This is a list (or a string, which will be taken as a 1 element
|
|
list) of event\_types this definition will handle. These can be
|
|
wildcarded with unix shell glob syntax. An exclusion listing
|
|
(starting with a ``!``) will exclude any types listed from matching.
|
|
If only exclusions are listed, the definition will match anything
|
|
not matching the exclusions.
|
|
|
|
traits
|
|
This is a mapping, the keys are the trait names, and the values are
|
|
trait definitions.
|
|
|
|
Each trait definition is a mapping with the following keys:
|
|
|
|
fields
|
|
A path specification for the field(s) in the notification you wish
|
|
to extract for this trait. Specifications can be written to match
|
|
multiple possible fields. By default the value will be the first
|
|
such field. The paths can be specified with a dot syntax
|
|
(``payload.host``). Square bracket syntax (``payload[host]``) is
|
|
also supported. In either case, if the key for the field you are
|
|
looking for contains special characters, like ``.``, it will need to
|
|
be quoted (with double or single quotes):
|
|
``payload.image_meta.`org.openstack__1__architecture```. The syntax
|
|
used for the field specification is a variant of
|
|
`JSONPath <https://github.com/kennknowles/python-jsonpath-rw>`__
|
|
|
|
type
|
|
(Optional) The data type for this trait. Valid options are:
|
|
``text``, ``int``, ``float``, and ``datetime``. Defaults to ``text``
|
|
if not specified.
|
|
|
|
plugin
|
|
(Optional) Used to execute simple programmatic conversions on the
|
|
value in a notification field.
|
|
|
|
Event delivery to external sinks
|
|
--------------------------------
|
|
|
|
You can configure the Telemetry service to deliver the events
|
|
into external sinks. These sinks are configurable in the
|
|
``/etc/ceilometer/event_pipeline.yaml`` file.
|
|
|