1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
|
======
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.
|
