Skip to content

Commit

Permalink
[monitoring] Readme updated #274
Browse files Browse the repository at this point in the history 
Fixes #274
  • Loading branch information
@praptisharma28
praptisharma28 committed Jun 3, 2024
1 parent 43e53ab commit 4a6c3aa
Showing 1 changed file with 113 additions and 50 deletions.
163 changes: 113 additions & 50 deletions README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -326,20 +326,23 @@ Follow the setup instructions of `openwisp-controller
# Make sure you change them in production
# You can select one of the backends located in openwisp_monitoring.db.backends
TIMESERIES_DATABASE = {
INFLUXDB_1x_DATABASE = {
'BACKEND': 'openwisp_monitoring.db.backends.influxdb',
'USER': 'openwisp',
'PASSWORD': 'openwisp',
'NAME': 'openwisp2',
'HOST': 'localhost',
'HOST': 'influxdb',
'PORT': '8086',
'OPTIONS': {
# Specify additional options to be used while initializing
# database connection.
# Note: These options may differ based on the backend used.
'udp_writes': True,
'udp_port': 8089,
}
'OPTIONS': {'udp_writes': False, 'udp_port': 8089},
}
INFLUXDB_2x_DATABASE = {
'BACKEND': 'openwisp_monitoring.db.backends.influxdb2',
'TOKEN': 'my-super-secret-auth-token',
'ORG': 'openwisp',
'BUCKET': 'openwisp2',
'HOST': 'influxdb2',
'PORT': '9999',
}
``urls.py``:
Expand Down Expand Up @@ -1413,56 +1416,109 @@ Settings
| **default**: | see below |
+--------------+-----------+

Timeseries Database Configuration
---------------------------------

The ``TIMESERIES_DATABASE`` setting allows configuring the timeseries
database backend used by OpenWISP Monitoring. The configuration supports
both InfluxDB 1.x and 2.x versions.

Configuration for InfluxDB 1.x
------------------------------

.. code-block:: python
TIMESERIES_DATABASE = {
INFLUXDB_1x_DATABASE = {
'BACKEND': 'openwisp_monitoring.db.backends.influxdb',
'USER': 'openwisp',
'PASSWORD': 'openwisp',
'NAME': 'openwisp2',
'HOST': 'localhost',
'HOST': 'influxdb',
'PORT': '8086',
'OPTIONS': {
'udp_writes': False,
'udp_port': 8089,
}
'OPTIONS': {'udp_writes': False, 'udp_port': 8089},
}
The following table describes all keys available in ``TIMESERIES_DATABASE``
setting:

+---------------+--------------------------------------------------------------------------------------+
| **Key** | ``Description`` |
+---------------+--------------------------------------------------------------------------------------+
| ``BACKEND`` | The timeseries database backend to use. You can select one of the backends |
| | located in ``openwisp_monitoring.db.backends`` |
+---------------+--------------------------------------------------------------------------------------+
| ``USER`` | User for logging into the timeseries database |
+---------------+--------------------------------------------------------------------------------------+
| ``PASSWORD`` | Password of the timeseries database user |
+---------------+--------------------------------------------------------------------------------------+
| ``NAME`` | Name of the timeseries database |
+---------------+--------------------------------------------------------------------------------------+
| ``HOST`` | IP address/hostname of machine where the timeseries database is running |
+---------------+--------------------------------------------------------------------------------------+
| ``PORT`` | Port for connecting to the timeseries database |
+---------------+--------------------------------------------------------------------------------------+
| ``OPTIONS`` | These settings depends on the timeseries backend: |
| | |
| | +-----------------+----------------------------------------------------------------+ |
| | | ``udp_writes`` | Whether to use UDP for writing data to the timeseries database | |
| | +-----------------+----------------------------------------------------------------+ |
| | | ``udp_port`` | Timeseries database port for writing data using UDP | |
| | +-----------------+----------------------------------------------------------------+ |
+---------------+--------------------------------------------------------------------------------------+

**Note:** UDP packets can have a maximum size of 64KB. When using UDP for writing timeseries
data, if the size of the data exceeds 64KB, TCP mode will be used instead.

**Note:** If you want to use the ``openwisp_monitoring.db.backends.influxdb`` backend
with UDP writes enabled, then you need to enable two different ports for UDP
(each for different retention policy) in your InfluxDB configuration. The UDP configuration
section of your InfluxDB should look similar to the following:
Configuration for InfluxDB 2.x
------------------------------

.. code-block:: python
INFLUXDB_2x_DATABASE = {
'BACKEND': 'openwisp_monitoring.db.backends.influxdb2',
'TOKEN': 'my-super-secret-auth-token',
'ORG': 'openwisp',
'BUCKET': 'openwisp2',
'HOST': 'influxdb2',
'PORT': '9999',
}
Dynamic Configuration Based on Environment
------------------------------------------

You can dynamically switch between InfluxDB 1.x and 2.x configurations
using environment variables:

.. code-block:: python
import os
if os.environ.get('USE_INFLUXDB2', 'False') == 'True':
TIMESERIES_DATABASE = INFLUXDB_2x_DATABASE
else:
TIMESERIES_DATABASE = INFLUXDB_1x_DATABASE
if TESTING:
if os.environ.get('TIMESERIES_UDP', False):
TIMESERIES_DATABASE['OPTIONS'] = {'udp_writes': True, 'udp_port': 8091}
Explanation of Settings
-----------------------

+---------------+---------------------------------------------------------------+
| **Key** | **Description** |
+-------------------------------------------------------------------------------+
| ``BACKEND`` | The timeseries database backend to use. You can select one |
| | of the backends located in ``openwisp_monitoring.db.backends``|
+---------------+---------------------------------------------------------------+
| ``USER`` | User for logging into the timeseries database (only for |
| | InfluxDB 1.x) |
+---------------+---------------------------------------------------------------+
| ``PASSWORD`` | Password of the timeseries database user (only for InfluxDB |
| | 1.x) |
+---------------+---------------------------------------------------------------+
| ``NAME`` | Name of the timeseries database (only for InfluxDB 1.x) |
+---------------+---------------------------------------------------------------+
| ``TOKEN`` | Authentication token for InfluxDB 2.x |
+---------------+---------------------------------------------------------------+
| ``ORG`` | Organization name for InfluxDB 2.x |
+---------------+---------------------------------------------------------------+
| ``BUCKET`` | Bucket name for InfluxDB 2.x |
+---------------+---------------------------------------------------------------+
| ``HOST`` | IP address/hostname of machine where the timeseries |
| | database is running |
+---------------+---------------------------------------------------------------+
| ``PORT`` | Port for connecting to the timeseries database |
+---------------+---------------------------------------------------------------+
| ``OPTIONS`` | Additional options for the timeseries backend |
| | |
| | +-----------------+-----------------------------------------+ |
| | | ``udp_writes`` | Whether to use UDP for writing data | |
| | | | to the timeseries database | |
| | +-----------------+-----------------------------------------+ |
| | | ``udp_port`` | Timeseries database port for writing | |
| | | | data using UDP | |
| | +-----------------+-----------------------------------------+ |
+---------------+---------------------------------------------------------------+

UDP Configuration for InfluxDB 1.x
----------------------------------

If you want to use the ``openwisp_monitoring.db.backends.influxdb`` backend
with UDP writes enabled, you need to enable two different ports for UDP
(each for a different retention policy) in your InfluxDB configuration.

Here is an example of the UDP configuration section in your InfluxDB
configuration file:

.. code-block:: text
Expand All @@ -1479,6 +1535,13 @@ section of your InfluxDB should look similar to the following:
database = "openwisp2"
retention-policy = 'short'
**Note:** UDP packets can have a maximum size of 64KB. When using UDP for
writing timeseries data, if the size of the data exceeds 64KB, TCP mode
will be used instead.

Deploying with Ansible
----------------------

If you are using `ansible-openwisp2 <https://github.com/openwisp/ansible-openwisp2>`_
for deploying OpenWISP, you can set the ``influxdb_udp_mode`` ansible variable to ``true``
in your playbook, this will make the ansible role automatically configure the InfluxDB UDP listeners.
Expand Down

0 comments on commit 4a6c3aa

Please sign in to comment.