Skip to content

Commit 4a6c3aa

Browse files
praptisharma28praptisharma28
committed
[monitoring] Readme updated #274
Fixes #274
1 parent 43e53ab commit 4a6c3aa

File tree

1 file changed

+113
-50
lines changed

1 file changed

+113
-50
lines changed

‎README.rst

Lines changed: 113 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -326,20 +326,23 @@ Follow the setup instructions of `openwisp-controller
326326
327327
# Make sure you change them in production
328328
# You can select one of the backends located in openwisp_monitoring.db.backends
329-
TIMESERIES_DATABASE = {
329+
INFLUXDB_1x_DATABASE = {
330330
'BACKEND': 'openwisp_monitoring.db.backends.influxdb',
331331
'USER': 'openwisp',
332332
'PASSWORD': 'openwisp',
333333
'NAME': 'openwisp2',
334-
'HOST': 'localhost',
334+
'HOST': 'influxdb',
335335
'PORT': '8086',
336-
'OPTIONS': {
337-
# Specify additional options to be used while initializing
338-
# database connection.
339-
# Note: These options may differ based on the backend used.
340-
'udp_writes': True,
341-
'udp_port': 8089,
342-
}
336+
'OPTIONS': {'udp_writes': False, 'udp_port': 8089},
337+
}
338+
339+
INFLUXDB_2x_DATABASE = {
340+
'BACKEND': 'openwisp_monitoring.db.backends.influxdb2',
341+
'TOKEN': 'my-super-secret-auth-token',
342+
'ORG': 'openwisp',
343+
'BUCKET': 'openwisp2',
344+
'HOST': 'influxdb2',
345+
'PORT': '9999',
343346
}
344347
345348
``urls.py``:
@@ -1413,56 +1416,109 @@ Settings
14131416
| **default**: | see below |
14141417
+--------------+-----------+
14151418

1419+
Timeseries Database Configuration
1420+
---------------------------------
1421+
1422+
The ``TIMESERIES_DATABASE`` setting allows configuring the timeseries
1423+
database backend used by OpenWISP Monitoring. The configuration supports
1424+
both InfluxDB 1.x and 2.x versions.
1425+
1426+
Configuration for InfluxDB 1.x
1427+
------------------------------
1428+
14161429
.. code-block:: python
14171430
1418-
TIMESERIES_DATABASE = {
1431+
INFLUXDB_1x_DATABASE = {
14191432
'BACKEND': 'openwisp_monitoring.db.backends.influxdb',
14201433
'USER': 'openwisp',
14211434
'PASSWORD': 'openwisp',
14221435
'NAME': 'openwisp2',
1423-
'HOST': 'localhost',
1436+
'HOST': 'influxdb',
14241437
'PORT': '8086',
1425-
'OPTIONS': {
1426-
'udp_writes': False,
1427-
'udp_port': 8089,
1428-
}
1438+
'OPTIONS': {'udp_writes': False, 'udp_port': 8089},
14291439
}
14301440
1431-
The following table describes all keys available in ``TIMESERIES_DATABASE``
1432-
setting:
1433-
1434-
+---------------+--------------------------------------------------------------------------------------+
1435-
| **Key** | ``Description`` |
1436-
+---------------+--------------------------------------------------------------------------------------+
1437-
| ``BACKEND`` | The timeseries database backend to use. You can select one of the backends |
1438-
| | located in ``openwisp_monitoring.db.backends`` |
1439-
+---------------+--------------------------------------------------------------------------------------+
1440-
| ``USER`` | User for logging into the timeseries database |
1441-
+---------------+--------------------------------------------------------------------------------------+
1442-
| ``PASSWORD`` | Password of the timeseries database user |
1443-
+---------------+--------------------------------------------------------------------------------------+
1444-
| ``NAME`` | Name of the timeseries database |
1445-
+---------------+--------------------------------------------------------------------------------------+
1446-
| ``HOST`` | IP address/hostname of machine where the timeseries database is running |
1447-
+---------------+--------------------------------------------------------------------------------------+
1448-
| ``PORT`` | Port for connecting to the timeseries database |
1449-
+---------------+--------------------------------------------------------------------------------------+
1450-
| ``OPTIONS`` | These settings depends on the timeseries backend: |
1451-
| | |
1452-
| | +-----------------+----------------------------------------------------------------+ |
1453-
| | | ``udp_writes`` | Whether to use UDP for writing data to the timeseries database | |
1454-
| | +-----------------+----------------------------------------------------------------+ |
1455-
| | | ``udp_port`` | Timeseries database port for writing data using UDP | |
1456-
| | +-----------------+----------------------------------------------------------------+ |
1457-
+---------------+--------------------------------------------------------------------------------------+
1458-
1459-
**Note:** UDP packets can have a maximum size of 64KB. When using UDP for writing timeseries
1460-
data, if the size of the data exceeds 64KB, TCP mode will be used instead.
1461-
1462-
**Note:** If you want to use the ``openwisp_monitoring.db.backends.influxdb`` backend
1463-
with UDP writes enabled, then you need to enable two different ports for UDP
1464-
(each for different retention policy) in your InfluxDB configuration. The UDP configuration
1465-
section of your InfluxDB should look similar to the following:
1441+
Configuration for InfluxDB 2.x
1442+
------------------------------
1443+
1444+
.. code-block:: python
1445+
1446+
INFLUXDB_2x_DATABASE = {
1447+
'BACKEND': 'openwisp_monitoring.db.backends.influxdb2',
1448+
'TOKEN': 'my-super-secret-auth-token',
1449+
'ORG': 'openwisp',
1450+
'BUCKET': 'openwisp2',
1451+
'HOST': 'influxdb2',
1452+
'PORT': '9999',
1453+
}
1454+
1455+
Dynamic Configuration Based on Environment
1456+
------------------------------------------
1457+
1458+
You can dynamically switch between InfluxDB 1.x and 2.x configurations
1459+
using environment variables:
1460+
1461+
.. code-block:: python
1462+
1463+
import os
1464+
1465+
if os.environ.get('USE_INFLUXDB2', 'False') == 'True':
1466+
TIMESERIES_DATABASE = INFLUXDB_2x_DATABASE
1467+
else:
1468+
TIMESERIES_DATABASE = INFLUXDB_1x_DATABASE
1469+
1470+
if TESTING:
1471+
if os.environ.get('TIMESERIES_UDP', False):
1472+
TIMESERIES_DATABASE['OPTIONS'] = {'udp_writes': True, 'udp_port': 8091}
1473+
1474+
Explanation of Settings
1475+
-----------------------
1476+
1477+
+---------------+---------------------------------------------------------------+
1478+
| **Key** | **Description** |
1479+
+-------------------------------------------------------------------------------+
1480+
| ``BACKEND`` | The timeseries database backend to use. You can select one |
1481+
| | of the backends located in ``openwisp_monitoring.db.backends``|
1482+
+---------------+---------------------------------------------------------------+
1483+
| ``USER`` | User for logging into the timeseries database (only for |
1484+
| | InfluxDB 1.x) |
1485+
+---------------+---------------------------------------------------------------+
1486+
| ``PASSWORD`` | Password of the timeseries database user (only for InfluxDB |
1487+
| | 1.x) |
1488+
+---------------+---------------------------------------------------------------+
1489+
| ``NAME`` | Name of the timeseries database (only for InfluxDB 1.x) |
1490+
+---------------+---------------------------------------------------------------+
1491+
| ``TOKEN`` | Authentication token for InfluxDB 2.x |
1492+
+---------------+---------------------------------------------------------------+
1493+
| ``ORG`` | Organization name for InfluxDB 2.x |
1494+
+---------------+---------------------------------------------------------------+
1495+
| ``BUCKET`` | Bucket name for InfluxDB 2.x |
1496+
+---------------+---------------------------------------------------------------+
1497+
| ``HOST`` | IP address/hostname of machine where the timeseries |
1498+
| | database is running |
1499+
+---------------+---------------------------------------------------------------+
1500+
| ``PORT`` | Port for connecting to the timeseries database |
1501+
+---------------+---------------------------------------------------------------+
1502+
| ``OPTIONS`` | Additional options for the timeseries backend |
1503+
| | |
1504+
| | +-----------------+-----------------------------------------+ |
1505+
| | | ``udp_writes`` | Whether to use UDP for writing data | |
1506+
| | | | to the timeseries database | |
1507+
| | +-----------------+-----------------------------------------+ |
1508+
| | | ``udp_port`` | Timeseries database port for writing | |
1509+
| | | | data using UDP | |
1510+
| | +-----------------+-----------------------------------------+ |
1511+
+---------------+---------------------------------------------------------------+
1512+
1513+
UDP Configuration for InfluxDB 1.x
1514+
----------------------------------
1515+
1516+
If you want to use the ``openwisp_monitoring.db.backends.influxdb`` backend
1517+
with UDP writes enabled, you need to enable two different ports for UDP
1518+
(each for a different retention policy) in your InfluxDB configuration.
1519+
1520+
Here is an example of the UDP configuration section in your InfluxDB
1521+
configuration file:
14661522

14671523
.. code-block:: text
14681524
@@ -1479,6 +1535,13 @@ section of your InfluxDB should look similar to the following:
14791535
database = "openwisp2"
14801536
retention-policy = 'short'
14811537
1538+
**Note:** UDP packets can have a maximum size of 64KB. When using UDP for
1539+
writing timeseries data, if the size of the data exceeds 64KB, TCP mode
1540+
will be used instead.
1541+
1542+
Deploying with Ansible
1543+
----------------------
1544+
14821545
If you are using `ansible-openwisp2 <https://github.com/openwisp/ansible-openwisp2>`_
14831546
for deploying OpenWISP, you can set the ``influxdb_udp_mode`` ansible variable to ``true``
14841547
in your playbook, this will make the ansible role automatically configure the InfluxDB UDP listeners.

0 commit comments

Comments
 (0)