From 758adf82f672b0a0ee89c32f625f62533822cc79 Mon Sep 17 00:00:00 2001 From: Helena McGough Date: Tue, 10 Oct 2017 13:17:22 +0100 Subject: [PATCH] Included a documentation directory - Included a OpenStack plugin usage specific documentation - Updated the licensing on any docmentation file for correct rendering Signed-off-by: Helena McGough --- README.rst | 40 +++--- doc/plugins/OpenStack/aodh_plugin_guide.rst | 124 ++++++++++++++++++ .../OpenStack/gnocchi_plugin_guide.rst | 100 ++++++++++++++ doc/plugins/OpenStack/openstack_plugins.rst | 57 ++++++++ 4 files changed, 301 insertions(+), 20 deletions(-) create mode 100644 doc/plugins/OpenStack/aodh_plugin_guide.rst create mode 100644 doc/plugins/OpenStack/gnocchi_plugin_guide.rst create mode 100644 doc/plugins/OpenStack/openstack_plugins.rst diff --git a/README.rst b/README.rst index cafe0c5..99a910a 100644 --- a/README.rst +++ b/README.rst @@ -1,23 +1,23 @@ -# Copyright 2017 Intel Research and Development Ireland Limited -# ************************************************************* - -# This file is part of OSM Monitoring module -# All Rights Reserved to Intel Corporation - -# 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. - -# For those usages not covered by the Apache License, Version 2.0 please -# contact: prithiv.mohan@intel.com or adrian.hoban@intel.com +.. + # Copyright 2017 Intel Research and Development Ireland Limited + # ************************************************************* + # This file is part of OSM Monitoring module + # All Rights Reserved to Intel Corporation + # + # 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. + # + # For those usages not covered by the Apache License, Version 2.0 please + # contact: prithiv.mohan@intel.com or adrian.hoban@intel.com OSM MON Module **************** diff --git a/doc/plugins/OpenStack/aodh_plugin_guide.rst b/doc/plugins/OpenStack/aodh_plugin_guide.rst new file mode 100644 index 0000000..b19eca3 --- /dev/null +++ b/doc/plugins/OpenStack/aodh_plugin_guide.rst @@ -0,0 +1,124 @@ +.. + # Copyright 2017 Intel Research and Development Ireland Limited + # ************************************************************* + # This file is part of OSM Monitoring module + # All Rights Reserved to Intel Corporation + # + # 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. + # + # For those usages not covered by the Apache License, Version 2.0 please + # contact: helena.mcgough@intel.com or adrian.hoban@intel.com + +Aodh Plugin Guide for OSM MON +***************************** +The Aodh plugin for the MON module allows an OSM user to utilise the OpenStack +alarming functionality. + +This plugin allows you to create, list, delete and update alarms. These alarms +are based on metrics generated by the OpenStack Gnocchi plugin. + +Supported Alarms +---------------- +Currently the plugin only supports the following alarms for their corresponding +metrics: + + +-----------------------------+---------------------------------+ + | Gnocchi Metric | Aodh Alarm | + +-----------------------------+---------------------------------+ + | AVERAGE_MEMORY_UTILIZATION | AVERAGE_MEMORY_UTILIZATION | + | DISK_READ_OPS | DISK_READ_OPS | + | DISK_WRITE_OPS | DISK_WRITE_OPS | + | DISK_READ_BYTES | DISK_READ_BYTES | + | DISK_WRITE_BYTES | DISK_WRITE_BYTES | + | PACKETS_DROPPED | NET_PACKETS_DROPPED | + | PACKETS_RECEIVED | PACKETS_IN_ABOVE_THRESHOLD | + | PACKETS_SENT | PACKETS_OUT_ABOVE_THRESHOLD | + | CPU_UTILIZATION | CPU_UTILIZATION_ABOVE_THRESHOLD | + +-----------------------------+---------------------------------+ + +Creating an Alarm +----------------- +To create an alarm for one of the supported metrics a no. of configuration +parameters must be set: + +* alarm_name: Defines the name of the alarm and must correspond to the desired + metric. +* metric_name: Defines the name of the metric for which the alarm is to be + created. +* resource_uuid: Defines the resource that the chosen metric will monitor. +* severity: defines the significance of the alarm if it is triggered. Options + for this parameter include: + + - WARNING + - MINOR + - MAJOR + - CRITICAL + - INDETERMINATE + +* operation: Defines how the metric data is to be evaluated when determining if + the alarm has been triggered. Valid inputs for this parameter include: + + - GE (greater than or equal to) + - LE (less that or equal to) + - GT (greater than) + - LT (less than) + - EQ (equal to) + +* threshold_value: Defines a threshold that the metric values will be compared + against to determine if the alarm should be triggered. +* statistic: Defines the way in which the metric data should be evaluated. + Valid options for this parameter include: + + - AVERAGE + - MINIMUM + - MAXIMUM + - COUNT + - SUM + + .. note:: + + - To create a valid alarm the metric that you request must exist as a + Gnocchi metric and it must exist for the resource requested. + - Multiple alarms can be created for the same metric as you can define + different thresholds, operations, etc. for each alarm. + +Deleting an Alarm +----------------- +To delete an alarm just before a delete request with the alarm_id of the alarm +you wish to delete. + +Listing Alarms +-------------- +A full list of alarms will be generated if a list request is performed and no +configuration parameters are set. + +To generate a more specified list you can define one or both of the following +configuration parameters: + +* alarm_name +* severity + + .. note:: + + For now resource_uuid must be defined when generating a list of alarms. + This will be removed in a future release. + +Updating an alarm +----------------- +Certain parameters of an alarm can be updated after the alarm has been created. +These include: + +* threshold_value +* operation +* statistic +* severity diff --git a/doc/plugins/OpenStack/gnocchi_plugin_guide.rst b/doc/plugins/OpenStack/gnocchi_plugin_guide.rst new file mode 100644 index 0000000..e6831cf --- /dev/null +++ b/doc/plugins/OpenStack/gnocchi_plugin_guide.rst @@ -0,0 +1,100 @@ +.. + # Copyright 2017 Intel Research and Development Ireland Limited + # ************************************************************* + # This file is part of OSM Monitoring module + # All Rights Reserved to Intel Corporation + # + # 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. + # + # For those usages not covered by the Apache License, Version 2.0 please + # contact: helena.mcgough@intel.com or adrian.hoban@intel.com + +Gnocchi Plugin Guide for OSM MON +******************************** +The Gnocchi plugin for the MON module allows an OSM user to utilise metric and +resource functionality from their OpenStack deployment. + +This plugin allows you to create, list, delete and read metric data. + + .. note:: + + + An update metric request can also be performed but Gnocchi does not + support this functionality, your request will just be logged. + +Supported Metrics +----------------- +Currently this plugin only supports the following metrics: + +* AVERAGE_MEMORY_UTILIZATION +* DISK_READ_OPS +* DISK_WRITE_OPS +* DISK_READ_BYTES +* DISK_WRITE_BYTES +* PACKETS_DROPPED +* PACKETS_RECEIVED +* PACKETS_SENT +* CPU_UTILIZATION + +Configuring a Metric +-------------------- +Any of the above OpenStack metrics can be configured based on the following +configuration options: + +* Resource_uuid: Specifies the resource that your metric will be configured for. +* Metric_name: Specify one of the above metrics for your desired resource. +* Metric_unit: the unit that you wish your metric to be monitored in. + + .. note:: + + + Your metric can only be specified once for a particular resource. + +Deleting a Metric +----------------- +To delete a metric all that is required is to specify the metric_uuid of the +metric you wish to delete. + +Listing Metrics +--------------- +A full list of OSM generated metrics can be created by perform a list request +without defining any list parameters. + +Specific lists can also be created based on two different input parameters: + +* Metric_name +* Resource_uuid + +These parameters will generate a list of metrics that have the metric_name +and/or the resource_uuid defined. These parameters can be defined seperately or +in combination. + +Reading Metric Data +------------------- +To define what metric data you want to read from the Gnocchi database a no. of +parameters have to be defined: + +* Metric_uuid: To define which metric's data you would like to read. +* Collection_unit: Defines the unit of time that you want to read the metric + data over. + + .. note:: + + + The units that you can define include: HR, DAY, WEEK, MONTH, YEAR. + +* Collection_period: defines the integer value of the collection period. + E.g. 1 DAY. + +This type of request results in a list of data values and a corresponding list +of timestamps. diff --git a/doc/plugins/OpenStack/openstack_plugins.rst b/doc/plugins/OpenStack/openstack_plugins.rst new file mode 100644 index 0000000..f67fd17 --- /dev/null +++ b/doc/plugins/OpenStack/openstack_plugins.rst @@ -0,0 +1,57 @@ +.. + # Copyright 2017 Intel Research and Development Ireland Limited + # ************************************************************* + # This file is part of OSM Monitoring module + # All Rights Reserved to Intel Corporation + # + # 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. + # + # For those usages not covered by the Apache License, Version 2.0 please + # contact: helena.mcgough@intel.com or adrian.hoban@intel.com + +OpenStack Plugin Guide +********************** +The OSM MON module provides support for two different OpenStack plugins that +provide monitoring functionality. The Gnocchi plugin implements metric +functionality, whilst the Aodh plugin supports alarming functionality. + +Gnocchi +------- +Gnocchi is a timeseries, metrics and resources database, which allows you to +store and access the information and history of resources and their metrics. + +For more information on Gnocchi please refer to the source code/documentation: + + :: + + https://github.com/gnocchixyz/gnocchi + +For plugin specific instructions and configuration options please refer to the +following guide: +: `` + +Aodh +---- +Aodh is OpenStack's alarming project, it enables alarms to be created based on +Gnocchi metrics. Rules can be defined for these metrics to create these alarms. + +For more information on this project please refer to the source +code/documentation: + + :: + + https://github.com/openstack/aodh + +For plugin specific instructions and configuration options please refer to the +following guide: +: `` -- 2.25.1