docs/user-guide/centinel-user-guide.rst

   1 Centinel User Guide
   2 ===================
   3
   4 The Centinel project aims at providing a distributed, reliable framework
   5 for efficiently collecting, aggregating and sinking streaming data
   6 across Persistence DB and stream analyzers (example: Graylog, Elastic
   7 search, Spark, Hive etc.). This document contains configuration,
   8 administration, management, using sections for the feature.
   9
  10 Overview
  11 --------
  12
  13 In the Beryllium Release of Centinel, this framework enables SDN
  14 applications/services to receive events from multiple streaming sources
  15 (e.g., Syslog, Thrift, Avro, AMQP, Log4j, HTTP/REST) and execute actions
  16 like network configuration/batch processing/real-time analytics. It also
  17 provides a Log Service to assist operators running SDN ecosystem by
  18 installing the feature odl-centinel-all.
  19
  20 With the configurations development of "Log Service" and plug-in for log
  21 analyzer (e.g., Graylog) will take place. Log service will do processing
  22 of real time events coming from log analyzer. Additionally, stream
  23 collector (Flume and Sqoop based) that will collect logs from
  24 OpenDaylight and sink it to persistence service (integrated with TSDR).
  25 Also includes RESTCONF interface to inject events to north bound
  26 applications for real-time analytic/network configuration. Centinel User
  27 Interface (web interface) will be available to operators to enable
  28 rules/alerts/dashboard.
  29
  30 Centinel core features
  31 ----------------------
  32
  33 The core features of the Centinel framework are:
  34
  35 Stream collector
  36     Collecting, aggregating and sinking streaming data
  37
  38 Log Service
  39     Listen log stream events coming from log analyzer
  40
  41 Log Service
  42     Enables user to configure rules (e.g., alerts, diagnostic, health,
  43     dashboard)
  44
  45 Log Service
  46     Performs event processing/analytics
  47
  48 User Interface
  49     Enable set-rule, search, visualize, alert, diagnostic, dashboard
  50     etc.
  51
  52 Adaptor
  53     Log analyzer plug-in to Graylog and a generic data-model to extend
  54     to other stream analyzers (e.g., Logstash)
  55
  56 REST Service
  57     Northbound APIs for Log Service and Steam collector framework
  58
  59 Leverages
  60     TSDR persistence service, data query, purging and elastic search
  61
  62 Centinel Architecture
  63 ---------------------
  64
  65 The following wiki pages capture the Centinel Model/Architecture
  66
  67 a. https://wiki.opendaylight.org/view/Centinel:Main
  68
  69 b. https://wiki.opendaylight.org/view/Project_Proposals:Centinel
  70
  71 c. https://wiki.opendaylight.org/images/0/09/Centinel-08132015.pdf
  72
  73 Administering or Managing Centinel with default configuration
  74 -------------------------------------------------------------
  75
  76 Prerequisites
  77 ~~~~~~~~~~~~~
  78
  79 1. Check whether Graylog is up and running and plugins deployed as
  80    mentioned in `installation
  81    guide <http://opendaylight.readthedocs.io/en/stable-beryllium/getting-started-guide/index.html>`__.
  82
  83 2. Check whether HBase is up and respective tables and column families
  84    as mentioned in `installation
  85    guide <http://opendaylight.readthedocs.io/en/stable-beryllium/getting-started-guide/index.html>`__
  86    are created.
  87
  88 3. Check if apache flume is up and running.
  89
  90 4. Check if apache drill is up and running.
  91
  92 Running Centinel
  93 ~~~~~~~~~~~~~~~~
  94
  95 The following steps should be followed to bring up the controller:
  96
  97 1. Download the Centinel OpenDaylight distribution release from below
  98    link: http://www.opendaylight.org/software/downloads
  99
 100 2. Run Karaf of the distribution from bin folder
 101
 102    ::
 103
 104        ./karaf
 105
 106 3. Install the centinel features using below command:
 107
 108    ::
 109
 110        feature:install odl-centinel-all
 111
 112 4. Give some time for the centinel to come up.
 113
 114 User Actions
 115 ~~~~~~~~~~~~
 116
 117 1. **Log In:** User logs into the Centinel with required credentials
 118    using following URL: http://localhost:8181/index.html
 119
 120 2. **Create Rule:**
 121
 122    a. Select Centinel sub-tree present in left side and go to Rule tab.
 123
 124    b. Create Rule with title and description.
 125
 126    c. Configure flow rule on the stream to filter the logs accordingly
 127       for, e.g., ``bundle_name=org.opendaylight.openflow-plugin``
 128
 129 3. **Set Alarm Condition:** Configure alarm condition, e.g.,
 130    message-count-rule such that if 10 messages comes on a stream (e.g.,
 131    The OpenFlow Plugin) in last 1 minute with an alert is generated.
 132
 133 4. **Subscription:** User can subscribe to the rule and alarm condition
 134    by entering the http details or email-id in subscription textfield by
 135    clicking on the subscribe button.
 136
 137 5. **Create Dashboard:** Configure dashboard for stream and alert
 138    widgets. Alarm and Stream count will be updated in corresponding
 139    widget in Dashboard.
 140
 141 6. **Event Tab:** Intercepted Logs, Alarms and Raw Logs in Event Tab
 142    will be displayed by selecting the appropriate radio button. User can
 143    also filter the searched data using SQL query in the search box.
 144