157 lines
6.3 KiB
ReStructuredText
157 lines
6.3 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
|
||
~~~~~~~~~~~~~~~~~~~
|
||
|
||
To enable the creation and storage of events in the Telemetry service
|
||
``store_events`` option needs to be set to ``True``. For further configuration
|
||
options, see the event section in the `OpenStack Configuration Reference
|
||
<http://docs.openstack.org/newton/config-reference/telemetry.html>`__.
|
||
|
||
.. note::
|
||
|
||
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.
|