Skip to content

Commit

Permalink
Docs updates
Browse files Browse the repository at this point in the history
  • Loading branch information
kcech committed May 3, 2019
1 parent 12ad506 commit dcef01c
Show file tree
Hide file tree
Showing 5 changed files with 114 additions and 73 deletions.
Binary file added docs/_static/images/extensions/catalog-federation-config.png
View file
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/_static/images/extensions/sentilo_federation.png
View file
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
8 changes: 4 additions & 4 deletions docs/conf.py
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# -*- coding: utf-8 -*-
#
# Sentilo documentation build configuration file, created by
# sphinx-quickstart on Thu Jul 11 15:45:31 2013.
# sphinx-quickstart.
#
# This file is execfile()d with the current directory set to its containing dir.
#
Expand Down Expand Up @@ -33,16 +33,16 @@

# General information about the project.
project = u'Sentilo'
copyright = u'2018, Sentilo'
copyright = u'2019, Sentilo'

# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '1.7.0'
version = '1.8.0'
# The full version, including alpha/beta/rc tags.
release = '1.7.0'
release = '1.8.0'

# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
Expand Down
143 changes: 102 additions & 41 deletions docs/extensions.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -96,9 +96,6 @@ repository.
Activity Monitor agent
~~~~~~~~~~~~~~~~~~~~~~

Monitorization
~~~~~~~~~~~~~~

**Background on Activity Monitor Agent**

Sentilo is a publication-subscription platform. The amount of data held
Expand Down Expand Up @@ -201,9 +198,7 @@ pages.
Sentilo has been successfully used in with these versions of ELK (which
does not mean other versions shouldn’t work as well):

- Elasticsearch 2.3.1
- Kibana 4.5.3
- Logstash 2.3.2
- ELK 5+


Historian agent
Expand Down Expand Up @@ -290,8 +285,8 @@ Sentilo has been successfully used in with these versions:

- Hadoop 2.7.2
- HBase 1.2.1
- Opentsdb 2.2.0
- Grafana 3.0.4
- Opentsdb 2.2.0, 2.3.0
- Grafana 3 +



Expand All @@ -300,47 +295,69 @@ Federation agent

**Description**

The federation agent is a module that allows to synchronize two independent instances on Sentilo.
The federation agent is a module that permits to share events between two independent instances of Sentilo.
The sharing is unilateral - one Sentilo instance is emitting events and the other is receiving.
The agent is installed at the side of the receiving instance:

.. image:: _static/images/extensions/sentilo_federation.png

The administrator of the emmitting Sentilo instance only needs to create a new application and provide the token the
administrator of the receiving instance.
As with any Sentilo application, the administrator is in control of which provider's data are readable by the remote federation agent.

Providers, components and sensors are created automatically in the catalog of the receiving instance by the federation agent.
The agent uses its application token to query the emitting catalog API to obtain remote objects, and uses the local catalog
application id to replicate the locally.

The federation agent creates subsriptions on data it has permission. It creates a HTTP endpoint and tells the emitting instance
to forward the events to this endpoint URL.


**Configuration**

Federation Agent's configuration is in file
sentilo/sentilo-agent-federation/src/main/resources/properties/app.properties.

+---------------------------------------------+----------+----------+
| Property | Property | Comments |
+---------------------------------------------+----------+----------+
| server.port | | |
+---------------------------------------------+----------+----------+
| rest.client.local.host | | |
+---------------------------------------------+----------+----------+
| sentilo.master.application.id | | |
+---------------------------------------------+----------+----------+
| catalog.mongodb.host | | |
+---------------------------------------------+----------+----------+
| catalog.mongodb.port | | |
+---------------------------------------------+----------+----------+
| catalog.mongodb.database | | |
+---------------------------------------------+----------+----------+
| catalog.mongodb.user | | |
+---------------------------------------------+----------+----------+
| catalog.mongodb.password | | |
+---------------------------------------------+----------+----------+
| federation.subscription.endpoint | | |
+---------------------------------------------+----------+----------+
| federation.subscription.secret.key.callback | | |
+---------------------------------------------+----------+----------+
| federation.subscription.max.retries | | |
+---------------------------------------------+----------+----------+
| federation.subscription.max.delay | | |
+---------------------------------------------+----------+----------+
sentilo/sentilo-agent-federation/src/main/resources/properties/application.properties.

+---------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------------------------------+
| Property | Default Value | Description |
+---------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------------------------------+
| server.port | 8082 | Agent's HTTP port |
+---------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------------------------------+
| rest.client.local.host | http://127.0.0.1:8081 | Local Sentilo API endpoint |
+---------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------------------------------+
| sentilo.master.application.id | sentilo-catalog | Local Sentilo application Id. The agent will use the token of the application to make changes in catalog |
+---------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------------------------------+
| catalog.mongodb.host | 127.0.0.1 | Local MongoDB host |
+---------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------------------------------+
| catalog.mongodb.port | 27017 | Local MongoDB port |
+---------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------------------------------+
| catalog.mongodb.database | sentilo | Local MongoDB database name |
+---------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------------------------------+
| catalog.mongodb.user | sentilo | Local MongoDB user |
+---------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------------------------------+
| catalog.mongodb.password | sentilo | Local MongoDB password |
+---------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------------------------------+
| federation.subscription.endpoint | http://localhost:8082/data/federated/ | Agent URL that will be used in subscriptions in the remote Sentilo instance. |
+---------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------------------------------+
| federation.subscription.secret.key.callback | secret-callback-key-change-it | HMAC secret used for incoming subscription. |
+---------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------------------------------+
| federation.subscription.max.retries | 3 | Number of retries used for subcription |
+---------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------------------------------+
| federation.subscription.max.delay | 5 | Delay used for subcription |
+---------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------------------------------+

Further configuration of the agent is available in the "Federation services" menu.

The menu is available when running Tomcat with the option:

::

Configuration of HDFS, HBase, OpenTSDB and is beyond the scope of this
document and can be easily followed on their respective web pages.
-Dsentilo.federation.enabled=true

The "Client application token" input is the token created in the emitting Sentilo instance:

.. image:: _static/images/extensions/catalog-federation-config.png

**Compatible versions**


Kafka agent
Expand All @@ -351,6 +368,50 @@ Kafka agent
The Kafka agent publishes Sentilo events to Kafka.


**Configuration**

+--------------------------+----------------+-----------------------------------------------------------------------------------------------------+
| Property | Default Value | Description |
+--------------------------+----------------+-----------------------------------------------------------------------------------------------------+
| kafka.bootstrap.servers | localhost:9092 | Comma-separated list of Kafka brokers |
+--------------------------+----------------+-----------------------------------------------------------------------------------------------------+
| kafka.topic.prefix | sentilo | |
+--------------------------+----------------+-----------------------------------------------------------------------------------------------------+
| zookeeper.nodes | localhost:2181 | Comma-separated list of Zookeeper nodes |
+--------------------------+----------------+-----------------------------------------------------------------------------------------------------+
| batch.workers.size | 10 | Number of worker threads |
+--------------------------+----------------+-----------------------------------------------------------------------------------------------------+
| batch.max.retries | 1 | How many times will the agent try to resend the message to Kafka until it gives up |
+--------------------------+----------------+-----------------------------------------------------------------------------------------------------+
| kafka.request.timeout.ms | 30000 | |
+--------------------------+----------------+-----------------------------------------------------------------------------------------------------+
| kafka.linger.ms | 100 | Milliseconds before the contents of buffer are sent or until batch fills up, whichever comes first. |
+--------------------------+----------------+-----------------------------------------------------------------------------------------------------+
| kafka.batch.size | 20000 | Number of bytes of internal buffer. If the size fills up before , contents are sent to Kafka, . |
| | | |
| | | Otherwise contents are sent once kafka.linger.ms passed. |
+--------------------------+----------------+-----------------------------------------------------------------------------------------------------+
| kafka.topicPrefix | sentilo | Topics in Kafka will start with following prefix. May be left blank |
+--------------------------+----------------+-----------------------------------------------------------------------------------------------------+
| kafka.topicSeparator | . | The compound name of topic in Kafka will be separated with this string. |
+--------------------------+----------------+-----------------------------------------------------------------------------------------------------+
| kafka.topicNameMode | topicPerSensor | Possible values of topicNameMode for the "data" event type: |
| | | * topicPerSensor: sentilo.data.providerName.sensorName |
| | | * topicPerProvider: sentilo.data.providerName |
| | | * topicPerSensorType: sentilo.data.temperature |
| | | * topicPerMessageType: sentilo.data |
| | | * singleTopic: sentilo |
| | | |
+--------------------------+----------------+-----------------------------------------------------------------------------------------------------+


**Compatible versions**

Sentilo has been successfully used in with these versions:

- Kafka 0.11.0


Node-red
--------

Expand Down
36 changes: 8 additions & 28 deletions docs/setup.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,10 +27,9 @@ Sentilo uses Maven as a mechanism for building and managing the
dependencies of the platform. In order to build **Sentilo**, it is
necessary to ensure the next set of prerequisites:

- JDK 1.6.x + (Sentilo has been tested on JDK/JRE versions 1.6, 1.7 and
1.8)
- JDK 1.8.x +
- Git **(optional)**
- Maven 2.2.1 +
- Maven 3 +
- Ensure that the the Java SDK and Maven executables are accessible
using your PATH environment variable.

Expand Down Expand Up @@ -87,30 +86,13 @@ If you want modify the code before to build it, you should import it
into an Eclipse workspace with maven plug-in installed. Below we explain
how to do it by using the M2E plugin.

**For M2E plugin version lower than 1.0.0**

Go to the root directoy (./sentilo) and execute:

::

mvn clean install
mvn eclipse:clean eclipse:eclipse

Open the Eclipse workspace to import the code:

- Go to **File > Import > Existing Maven Projects**
- Select **./sentilo** as the root directory
- Select all projects and import

**For M2E plugin version equal/greather than 1.0.0**

- Open the Eclipse workspace to import the code:

- Go to **File> Import> Existing Maven Projects**
- Select **./sentilo** as the root directory
- Select all projects and import

**Warning**: be sure that JDK 1.6, or later, is correctly configured in
**Warning**: be sure that JDK 1.8, or later, is correctly configured in
your Eclipse environment.

After modifying the code, to compile and build the artifacts, our
Expand All @@ -127,20 +109,18 @@ into two categories):

- Mandatory

- Redis 2.6.11 + (Sentilo has been tested on versions 2.6.11 and
2.8.6)
- MongoDB 2.2.x or 2.4.x (Sentilo has been tested on versions 2.2.3,
2.4.8 and 2.4.13)
- Tomcat 7.0.37 +
- Redis 4.0.11
- MongoDB 4.0.1
- Tomcat 8.5.32 +

- Optional

- MySQL 5.5.x (Sentilo has been tested on MySQL 5.5.34 but you could
use your favourite RDBMS) **It is only necessary if you want to
install the relational agent**
- Elasticsearch 2.3.x **It is only necessary if you want to install
- Elasticsearch 5+ **It is only necessary if you want to install
the activity-monitor agent**.
- openTSDB 2.2.0 **It is only necessary if you want to install the
- openTSDB 2.2.0 + **It is only necessary if you want to install the
historian agent**

You must ensure that you have all these elements installed properly (you
Expand Down

0 comments on commit dcef01c

Please sign in to comment.