docs/user-guide/tsdr-elastic-search.rst

   1 ElasticSearch
   2 -------------
   3
   4 Setting Up the environment
   5 ^^^^^^^^^^^^^^^^^^^^^^^^^^
   6
   7 To setup and run the TSDR data store ElasticSearch feature, you need to have
   8 an ElasticSearch node (or a cluster of such nodes) running. You can use a
   9 customized ElasticSearch docker image for this purpose.
  10
  11 Your ElasticSearch (ES)  setup must have the "Delete By Query Plugin" installed.
  12 Without this, some of the ES functionality won't work properly.
  13
  14
  15 Creating a custom ElasticSearch docker image
  16 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  17
  18 (You can skip this section if you already have an instance of ElasticSearch running)
  19
  20 Run the following set of commands:
  21
  22 .. code-block:: bash
  23
  24     cat << EOF > Dockerfile
  25     FROM elasticsearch:2
  26     RUN /usr/share/elasticsearch/bin/plugin install --batch delete-by-query
  27     EOF
  28
  29 To build the image, run the following command in the directory where the
  30 Dockerfile was created:
  31
  32 .. code-block:: bash
  33
  34     docker build . -t elasticsearch-dd
  35
  36 You can check whether the image was properly created by running:
  37
  38 .. code-block:: bash
  39
  40     docker images
  41
  42 This should print all your container images including the elasticsearch-dd.
  43
  44 Now we can create and run a container from our image by typing:
  45
  46 .. code-block:: bash
  47
  48     docker run -d -p 9200:9200 -p 9300:9300 --name elasticsearch-dd elasticsearch-dd
  49
  50 To see whether the container is running, run the following command:
  51
  52 .. code-block:: bash
  53
  54     docker ps
  55
  56 The output should include a row with elasticsearch-dd in the NAMES column.
  57 To check the std out of this container use
  58
  59 .. code-block:: bash
  60
  61     docker logs elasticsearch-dd
  62
  63 Running the ElasticSearch feature
  64 ---------------------------------
  65
  66 Once the features have been installed, you can change some of its properties. For
  67 example, to setup the URL where your ElasticSearch installation runs,
  68 change the *serverUrl* parameter in tsdr/persistence-elasticsearch/src/main/resources/configuration/initial/:
  69
  70 .. code-block:: bash
  71
  72     tsdr-persistence-elasticsearch.properties
  73
  74 All the data are stored into the TSDR index under a type. The metric data are
  75 stored under the metric type and the log data are store under the log type.
  76 You can modify the files in tsdr/persistence-elasticsearch/src/main/resources/configuration/initial/:
  77
  78 .. code-block:: bash
  79
  80     tsdr-persistence-elasticsearch_metric_mapping.json
  81     tsdr-persistence-elasticsearch_log_mapping.json
  82
  83 to change or tune the mapping for those types. The changes in those files will be promoted after
  84 the feature is reloaded or the distribution is restarted.
  85
  86 Testing the setup
  87 ^^^^^^^^^^^^^^^^^
  88
  89 We can now test whether the setup is correct by downloading and installing mininet,
  90 which we use to send some data to the running ElasticSearch instance.
  91
  92 Installing the necessary features:
  93
  94 .. code-block:: bash
  95
  96     start OpenDaylight
  97     feature:install odl-restconf odl-l2switch-switch odl-tsdr-core odl-tsdr-openflow-statistics-collector
  98     feature:install odl-tsdr-elasticsearch
  99
 100 We can check whether the distribution is now listening on port 6653:
 101
 102 .. code-block:: bash
 103
 104     netstat -an | grep 6653
 105
 106 Run mininet
 107
 108 .. code-block:: bash
 109
 110     sudo mn --topo single,3 --controller 'remote,ip=distro_ip,port=6653' --switch ovsk,protocols=OpenFlow13
 111
 112 where the distro_ip is the IP address of the machine where the OpenDaylight distribution
 113 is running. This command will create three hosts connected to one OpenFlow capable
 114 switch.
 115
 116 We can check if data was stored by ElasticSearch in TSDR by running the
 117 following command:
 118
 119 .. code-block:: bash
 120
 121     tsdr:list FLOWTABLESTATS
 122
 123 The output should look similar to the following::
 124
 125     [NID=openflow:1][DC=FLOWTABLESTATS][MN=ActiveFlows][RK=Node:openflow:1,Table:50][TS=1473427383598][3]
 126     [NID=openflow:1][DC=FLOWTABLESTATS][MN=PacketMatch][RK=Node:openflow:1,Table:50][TS=1473427383598][12]
 127     [NID=openflow:1][DC=FLOWTABLESTATS][MN=PacketLookup][RK=Node:openflow:1,Table:50][TS=1473427383598][12]
 128     [NID=openflow:1][DC=FLOWTABLESTATS][MN=ActiveFlows][RK=Node:openflow:1,Table:80][TS=1473427383598][3]
 129     [NID=openflow:1][DC=FLOWTABLESTATS][MN=PacketMatch][RK=Node:openflow:1,Table:80][TS=1473427383598][17]
 130     [NID=openflow:1][DC=FLOWTABLESTATS][MN=PacketMatch][RK=Node:openflow:1,Table:246][TS=1473427383598][19]
 131     ...
 132
 133 Or you can query your ElasticSearch instance:
 134
 135 .. code-block:: bash
 136
 137     curl -XPOST "http://elasticseach_ip:9200/_search?pretty" -d'{ "from": 0, "size": 10000, "query": { "match_all": {} } }'
 138
 139 The elasticseach_ip is the IP address of the server where the ElasticSearch is running.
 140
 141
 142 Web Activity Collector
 143 ----------------------
 144
 145 The Web Activity Collector records the meaningful REST requests made through the
 146 OpenDaylight RESTCONF interface.
 147
 148
 149 How to test the RESTCONF Collector
 150 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 151
 152 - Install some other feature that has a RESTCONF interface, for example. "odl-tsdr-syslog-collector"
 153 - Issue a RESTCONF command that uses either POST,PUT or DELETE.
 154   For example, you could call the register-filter RPC of tsdr-syslog-collector.
 155 - Look up data in TSDR database from Karaf.
 156
 157   .. code-block:: bash
 158
 159     tsdr:list RESTCONF
 160
 161 - You should see the request that you have sent, along with its information
 162   (URL, HTTP method, requesting IP address and request body)
 163 - Try to send a GET request, then check again, your request should not be
 164   registered, because the collector does not register GET requests by default.
 165 - Open the file: "etc/tsdr.restconf.collector.cfg", and add GET to the list of
 166   METHODS_TO_LOG, so that it becomes:
 167
 168   ::
 169
 170       METHODS_TO_LOG=POST,PUT,DELETE,GET
 171
 172   - Try again to issue your GET request, and check if it was recorded this time,
 173     it should be recorder.
 174   - Try manipulating the other properties (PATHS_TO_LOG (which URLs do we want
 175     to log from), REMOTE_ADDRESSES_TO_LOG (which requesting IP addresses do we
 176     want to log from) and CONTENT_TO_LOG (what should be in the request's body
 177     in order to log it)), and see if the requests are getting logged.
 178   - Try providing invalid properties (unknown methods for the METHODS_TO_LOG
 179     parameter, or the same method repeated multiple times, and invalid regular
 180     expressions for the other parameters), then check karaf's log using
 181     "log:display". It should tell you that the value is invalid, and that it
 182     will use the default value instead.