ceilometer/doc/source/contributor/measurements.rst

111 lines
4.0 KiB
ReStructuredText

..
Copyright 2012 New Dream Network (DreamHost)
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
.. _measurements:
============
Measurements
============
Existing meters
===============
For the list of existing meters see the tables under the
`Measurements page`_ of Ceilometer in the Administrator Guide.
.. _Measurements page: https://docs.openstack.org/ceilometer/latest/admin/telemetry-measurements.html
New measurements
================
Ceilometer is designed to collect measurements from OpenStack services and
from other external components. If you would like to add new meters to the
currently existing ones, you need to follow the guidelines given in this
section.
.. _meter_types:
Types
-----
Three type of meters are defined in Ceilometer:
.. index::
double: meter; cumulative
double: meter; gauge
double: meter; delta
========== ===================================================================
Type Definition
========== ===================================================================
Cumulative Increasing over time (instance hours)
Gauge Discrete items (floating IPs, image uploads) and fluctuating values
(disk I/O)
Delta Changing over time (bandwidth)
========== ===================================================================
When you're about to add a new meter choose one type from the above list, which
is applicable.
Units
-----
1. Whenever a volume is to be measured, SI approved units and their
approved symbols or abbreviations should be used. Information units
should be expressed in bits ('b') or bytes ('B').
2. For a given meter, the units should NEVER, EVER be changed.
3. When the measurement does not represent a volume, the unit
description should always describe WHAT is measured (ie: apples,
disk, routers, floating IPs, etc.).
4. When creating a new meter, if another meter exists measuring
something similar, the same units and precision should be used.
5. Meters and samples should always document their units in Ceilometer (API
and Documentation) and new sampling code should not be merged without the
appropriate documentation.
============ ======== ============== =======================
Dimension Unit Abbreviations Note
============ ======== ============== =======================
None N/A Dimension-less variable
Volume byte B
Time seconds s
============ ======== ============== =======================
Naming convention
-----------------
If you plan on adding meters, please follow the convention below:
1. Always use '.' as separator and go from least to most discriminant word.
For example, do not use ephemeral_disk_size but disk.ephemeral.size
2. When a part of the name is a variable, it should always be at the end and
start with a ':'. For example, do not use <type>.image but image:<type>,
where type is your variable name.
3. If you have any hesitation, come and ask in #openstack-telemetry
Meter definitions
-----------------
Meters definitions by default, are stored in separate configuration
file, called :file:`ceilometer/data/meters.d/meters.yaml`. This is essentially
a replacement for prior approach of writing notification handlers to consume
specific topics.
A detailed description of how to use meter definition is illustrated in
the `admin_guide`_.
.. _admin_guide: https://docs.openstack.org/ceilometer/latest/admin/telemetry-data-collection.html#meter-definitions