doc/MON_usage_guide.rst

   1 ..
   2        # Copyright 2017 Intel Research and Development Ireland Limited
   3        # *************************************************************
   4        # This file is part of OSM Monitoring module
   5        # All Rights Reserved to Intel Corporation
   6        #
   7        # Licensed under the Apache License, Version 2.0 (the "License"); you
   8        # may not use this file except in compliance with the License. You may
   9        # obtain a copy of the License at
  10        #
  11        #         http://www.apache.org/licenses/LICENSE-2.0
  12        #
  13        # Unless required by applicable law or agreed to in writing, software
  14        # distributed under the License is distributed on an "AS IS" BASIS,
  15        # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
  16        # implied. See the License for the specific language governing
  17        # permissions and limitations under the License.
  18        #
  19        # For those usages not covered by the Apache License, Version 2.0 please
  20        # contact: helena.mcgough@intel.com or adrian.hoban@intel.com
  21
  22 MON Usage Guide
  23 ***************
  24 This is a guide on how to use the MON module and its three plugins.
  25
  26 The MON module sends requests to an from the SO via an Apache Kafka message
  27 bus. Currently each message is sent on the message bus in json format, along
  28 with a unique request key and its topic.
  29
  30 The topics that the plugins will consume messages based on are:
  31
  32 * alarm_request
  33 * metric_request
  34
  35 Each type of request has it's own unique key:
  36 * create_alarm_request
  37 * create_metric_request
  38 * list_alarm_request
  39 * list_metric_request
  40 * delete_alarm_request
  41 * delete_metric_request
  42 * update_alarm_request
  43 * update_metric_request
  44 * acknowledge_alarm_request
  45 * read_metric_data_request
  46
  47 In return the plugins will send messages back to the SO with the following
  48 topics:
  49
  50 * alarm_response
  51 * metric_response
  52
  53 Each request has a corresponding response key:
  54 * create_alarm_reponse
  55 * create_metric_response
  56 * list_alarm_response
  57 * list_metric_response
  58 * delete_alarm_response
  59 * delete_metric_response
  60 * update_alarm_response
  61 * update_metric_response
  62 * acknowledge_alarm_response
  63 * read_metric_data_response
  64
  65   .. note::
  66
  67       There is an additional response key to send notifications to the SO
  68       when an alarm has been triggered:
  69       * notify_alarm
  70
  71 Sending Request Messages
  72 ------------------------
  73 For each of the request message that can be sent there is a json schema defined
  74 in the models directory of the MON repo:
  75 : `</MON/osm_mon/core/models/>`
  76
  77 To send a valid message to the MON module for use by one of the plugins, your
  78 message must match the json schema for that request type.
  79
  80 Once you have created a valid json object with your message you can send it on
  81 the message bus with the required topic and key.
  82
  83 To ensure that the correct plugin uses your message you must also specify the
  84 vim_type correctly:
  85
  86     +----------------------+----------------------+
  87     |       Plugin         |      vim_type        |
  88     +----------------------+----------------------+
  89     | CloudWatch           | cloudwatch           |
  90     |                      |                      |
  91     | OpenStack            | openstack            |
  92     |                      |                      |
  93     | vROPs                | vrops                |
  94     +----------------------+----------------------+
  95
  96
  97 * Example
  98   A create alarm request for the vROPs plugin would be sent with the following
  99   information:
 100
 101     - topic: alarm_request
 102     - create_alarm_request
 103     - message: a valid message that matches the json schema, with the vim_type
 104       specified as vrops
 105
 106 A KafkaProducer is used to send the message and it will be consumed by a
 107 KafkaConsumer which is running for each plugin
 108
 109
 110   .. note::
 111
 112         The SO support for sending and receiving messages is currently not
 113         supported. Support will be added in a later release.