docs/user-guide/tsdr-elasticsearch-user-guide.rst

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