+++ /dev/null
-..
- # 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
-
-OSM MON module
-**************
-This is a guide for using the OSM MON module source code to create a container
-for monitoring. It will allow the use of the three plugins available to the
-module; CloudWatch, OpenStack and vROPs.
-
-
-At the moment this process requires a number of steps, but in the future the
-process will become automated as it will become part of the osm installation
-script which is contained within the devops repo.
-: `</devops/installers/install_mon.sh>`
-
-
-For information on how to use this module refer to this usage guide:
-: `</MON/doc/MON_usage_guide.rst>`
-
-
-You can find the source code for MON by following the link below:
-https://osm.etsi.org/gitweb/?p=osm/MON.git;a=tree
-
-
-Requirements
-------------
-* lxc setup
-* OSM deployment
-
-
-Creating a MON Container
-------------------------
-To create a MON container and utilize the supported functionality, clone the
-MON repo and then run the provided script for container creation and
-installation:
-
- ::
-
- git clone https://osm.etsi.org/gerrit/osm/MON.git
- cd MON/scripts
- . install_mon.sh
-
-This script will create a MON container, install all of the required packages,
-as well as initializing the Apache Kafka and the vROPs web service.
-
-
-Plugin Utilization
-------------------
-There are three plugins supported by this monitoring module; CloudWatch,
-OpenStack and vROPs.
-
-vROPs plugin
-~~~~~~~~~~~~
-The vROPs plugin will automatically be installed after you have run the above
-installation script.
-
-OpenStack Plugin
-~~~~~~~~~~~~~~~~
-There are two OpenStack services supported within this module monitoring and
-alarming, which are supported by the Gnocchi and Aodh plugins respectively.
-
-For more information on what metrics and alarms that these plugins support
-please refer to the following documentation:
-: `</MON/doc/OpenStack/>`.
-
-These documents will also describe what alarming and monitoring functionality
-the plugins support.
-
-The following steps will allow you to use the plugins:
-
-* Pass your openstack deployment credentials to the MON container:
-
- ::
-
- lxc exec MON -- export OS_AUTH_URL=<AUTH_URL>
- lxc exec MON -- export OS_PASSWORD=<PASSWORD>
- lxc exec MON -- export OS_TENANT_NAME=<TENANT_NAME>
- lxc exec MON -- export OS_USERNAME=<USER_NAME>
-
-* The Gnocchi and Aodh plugins work from a common KafkaConsumer that checks for
- the appropriate topics and keys. To run this consumer:
-
- ::
-
- lxc exec MON -- nohup python /root/MON/osm_mon/core/message_bus/common_consumer.py > /root/MON_plugins.log 2>&1 &
-
-* To enable Aodh alarm notifications to be sent to SO:
-
- ::
-
- lxc exec MON - nohup python /root/MON/osm_mon/plugins/OpenStack/Aodh/notifier.py &
-
-CloudWatch
-~~~~~~~~~~
-The MON container supports a CloudWatch plugin on installation.
-
-
-Verification
-------------
-* To confirm that you have created your MON container, run the following command
- and confirm that your container is in a RUNNING state:
-
- ::
-
- lxc list | grep MON
-
-* Confirm that the kafka service is installed and running within the container:
-
- ::
-
- lxc exec MON -- service kafka status
-
-* To check the logs of the plugins:
-
- ::
-
- lxc exec MON -- tail -f /root/MON_plugins.log
+++ /dev/null
-..
- # 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
-
-MON Usage Guide
-***************
-This is a guide on how to use the MON module and its three plugins.
-
-The MON module sends requests to an from the SO via an Apache Kafka message
-bus. Currently each message is sent on the message bus in json format, along
-with a unique request key and its topic.
-
-The topics that the plugins will consume messages based on are:
-
-* alarm_request
-* metric_request
-
-Each type of request has it's own unique key:
-* create_alarm_request
-* create_metric_request
-* list_alarm_request
-* list_metric_request
-* delete_alarm_request
-* delete_metric_request
-* update_alarm_request
-* update_metric_request
-* acknowledge_alarm_request
-* read_metric_data_request
-
-In return the plugins will send messages back to the SO with the following
-topics:
-
-* alarm_response
-* metric_response
-
-Each request has a corresponding response key:
-* create_alarm_reponse
-* create_metric_response
-* list_alarm_response
-* list_metric_response
-* delete_alarm_response
-* delete_metric_response
-* update_alarm_response
-* update_metric_response
-* acknowledge_alarm_response
-* read_metric_data_response
-
- .. note::
-
- There is an additional response key to send notifications to the SO
- when an alarm has been triggered:
- * notify_alarm
-
-Sending Request Messages
-------------------------
-For each of the request message that can be sent there is a json schema defined
-in the models directory of the MON repo:
-: `</MON/osm_mon/core/models/>`
-
-To send a valid message to the MON module for use by one of the plugins, your
-message must match the json schema for that request type.
-
-Once you have created a valid json object with your message you can send it on
-the message bus with the required topic and key.
-
-To ensure that the correct plugin uses your message you must also specify the
-vim_type correctly:
-
- +----------------------+----------------------+
- | Plugin | vim_type |
- +----------------------+----------------------+
- | CloudWatch | cloudwatch |
- | | |
- | OpenStack | openstack |
- | | |
- | vROPs | vrops |
- +----------------------+----------------------+
-
-
-* Example
- A create alarm request for the vROPs plugin would be sent with the following
- information:
-
- - topic: alarm_request
- - create_alarm_request
- - message: a valid message that matches the json schema, with the vim_type
- specified as vrops
-
-A KafkaProducer is used to send the message and it will be consumed by a
-KafkaConsumer which is running for each plugin
-
-
- .. note::
-
- The SO support for sending and receiving messages is currently not
- supported. Support will be added in a later release.
+++ /dev/null
-..
- # 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
+++ /dev/null
-..
- # 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.
+++ /dev/null
-..
- # 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:
-: `<doc/OpenStack/gnocchi_plugin_guide.rst>`
-
-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:
-: `<doc/OpenStack/aodh_plugin_guide.rst>`
--- /dev/null
+<!--
+This file is part of OSM Monitoring module
+All Rights Reserved to Whitestack, LLC
+
+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: bdiaz@whitestack.com or glavado@whitestack.com
+-->
+# Monitoring module (MON)
+
+## Summary
+
+MON accomplishes the following tasks:
+
+* Collects VDU metrics exposed by the VIM.
+* Collects VNF metrics exposed by the VNF via Juju charms.
+* Collects infrastructure metrics of external components, such as VIMs, WIMs and SDN controllers.
+* Stores metrics in a TSDB.
+* Manages and evaluates alarms related to VNF/VDU metrics.
+
+## Overview
+
+
+
+MON has the following components:
+
+* MON Server: Handles alarms CRUD operations, through messages in the Kafka bus.
+* MON Collector: Collects VNF related metrics from VIMs and VCA and infrastructure metrics from external components, and then exports them to a Prometheus TSDB. It uses a plugin model both for collectors and for backends.
+* MON Evaluator: Evaluates alarms and sends notifications through the Kafka bus when they trigger.
+
+## MON Server
+
+
+
+MON Server subscribes to the message bus and waits for the following messages:
+
+* topic: alarm_request - key: create_alarm_request
+* topic: alarm_request - key: delete_alarm_request
+
+It performs the corresponding action and sends a response through a unique topic made of 'alarm_response_' plus a correlation_id, which is a field contained in the request message.
+
+Alarms are stored in MON database in the OSM MySQL engine.
+
+## MON Collector
+
+
+
+MON Collector handles two different types of metrics:
+
+* VNF related metrics: Provided by the VIM (eg. cpu utilization of a VDU) or directly from the VNF itself (eg. number of users connected).
+* Infrastructure metrics: Correspond to metrics regarding external components such as VIMs (eg. status, hypervisor capacity, etc), WIMs and SDN controllers.
+
+The module uses a plugin model to do the metric collection. In every collection cycle, it iterates over the running VNFs (VNFRs) as obtains the declared metrics in their VNFD. If it is a VIM provided metric (nfvi_metric), it selects the corresponding VIM plugin for doing that collection. In the case of an application metric (defined using proxy charms and the juju metrics framework), it is done through the Juju plugin.
+
+Similar situation happens for external components. The module iterates over the registered VIMs, SDNCs and WIMs, and does collection of the status and other metrics through the corresponding plugin (eg. OpenStack, ONOS).
+
+## MON Evaluator
+
+
+
+MON Evaluator iterates over the alarms stored in the system and evaluates the corresponding metric by querying the TSDB against the alarm defined threshold. Then it published to the message bus a message containing the alarm info and the corresponding status.
+
+An alarm can have three status:
+
+* ok: The metric has not crossed the threshold.
+* alarm: The metric crossed the threshold.
+* insufficient-data: There is no metric data in the TSDB.
projects / osm / MON.git / commitdiff
