Settings
Note
If you're unsure about what "Django settings" are, you can refer to How to Edit Django Settings in OpenWISP for guidance.
TIMESERIES_DATABASE
type: |
|
default: |
see below |
TIMESERIES_DATABASE = {
"BACKEND": "openwisp_monitoring.db.backends.influxdb",
"USER": "openwisp",
"PASSWORD": "openwisp",
"NAME": "openwisp2",
"HOST": "localhost",
"PORT": "8086",
"OPTIONS": {
"udp_writes": False,
"udp_port": 8089,
},
}
The following table describes all keys available in
TIMESERIES_DATABASE setting:
Key |
|
|
The timeseries database backend to use. You can select one of
the backends located in |
|
User for logging into the timeseries database |
|
Password of the timeseries database user |
|
Name of the timeseries database |
|
IP address/hostname of machine where the timeseries database is running |
|
Port for connecting to the timeseries database |
|
These settings depends on the timeseries backend. Refer the Timeseries Database Options table below for available options |
Timeseries Database Options
|
Whether to use UDP for writing data to the timeseries database |
|
Timeseries database port for writing data using UDP |
Important
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:
# For writing data with the "default" retention policy
[[udp]]
enabled = true
bind-address = "127.0.0.1:8089"
database = "openwisp2"
# For writing data with the "short" retention policy
[[udp]]
enabled = true
bind-address = "127.0.0.1:8090"
database = "openwisp2"
retention-policy = 'short'
If you are using 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. You can refer to
the ansible-ow-influxdb's (a
dependency of ansible-openwisp2) documentation to learn more.
OPENWISP_MONITORING_DEFAULT_RETENTION_POLICY
type: |
|
default: |
|
The default retention policy that applies to the timeseries data.
OPENWISP_MONITORING_SHORT_RETENTION_POLICY
type: |
|
default: |
|
The default retention policy used to store raw device data.
This data is only used to assess the recent status of devices, keeping it for a long time would not add much benefit and would cost a lot more in terms of disk space.
OPENWISP_MONITORING_AUTO_PING
type: |
|
default: |
|
Whether ping checks are created automatically for devices.
OPENWISP_MONITORING_PING_CHECK_CONFIG
type: |
|
default: |
|
This setting allows to override the default ping check configuration
defined in
openwisp_monitoring.check.classes.ping.DEFAULT_PING_CHECK_CONFIG.
For example, if you want to change only the timeout of ping you
can use:
OPENWISP_MONITORING_PING_CHECK_CONFIG = {
"timeout": {
"default": 1000,
},
}
If you are overriding the default value for any parameter beyond the
maximum or minimum value defined in
openwisp_monitoring.check.classes.ping.DEFAULT_PING_CHECK_CONFIG, you
will also need to override the maximum or minimum fields as
following:
OPENWISP_MONITORING_PING_CHECK_CONFIG = {
"timeout": {
"default": 2000,
"minimum": 1500,
"maximum": 2500,
},
}
Note
Above maximum and minimum values are only used for validating
custom parameters of a Check object.
OPENWISP_MONITORING_AUTO_DEVICE_CONFIG_CHECK
type: |
|
default: |
|
This setting allows you to choose whether config_applied checks should be created automatically for newly registered devices. It's enabled by default.
OPENWISP_MONITORING_CONFIG_CHECK_INTERVAL
type: |
|
default: |
|
This setting allows you to configure the config check interval used by config_applied. By default it is set to 5 minutes.
OPENWISP_MONITORING_AUTO_IPERF3
type: |
|
default: |
|
This setting allows you to choose whether iperf3 checks should be created automatically for newly registered devices. It's disabled by default.
OPENWISP_MONITORING_IPERF3_CHECK_CONFIG
type: |
|
default: |
|
This setting allows to override the default iperf3 check configuration
defined in
openwisp_monitoring.check.classes.iperf3.DEFAULT_IPERF3_CHECK_CONFIG.
For example, you can change the values of supported iperf3 check parameters.
OPENWISP_MONITORING_IPERF3_CHECK_CONFIG = {
# 'org_pk' : {'host' : [], 'client_options' : {}}
"a9734710-db30-46b0-a2fc-01f01046fe4f": {
# Some public iperf3 servers
# https://iperf.fr/iperf-servers.php#public-servers
"host": ["iperf3.openwisp.io", "2001:db8::1", "192.168.5.2"],
"client_options": {
"port": 6209,
# Number of parallel client streams to run
# note that iperf3 is single threaded
# so if you are CPU bound this will not
# yield higher throughput
"parallel": 5,
# Set the connect_timeout (in milliseconds) for establishing
# the initial control connection to the server, the lower the value
# the faster the down iperf3 server will be detected (ex. 1000 ms (1 sec))
"connect_timeout": 1000,
# Window size / socket buffer size
"window": "300K",
# Only one reverse condition can be chosen,
# reverse or bidirectional
"reverse": True,
# Only one test end condition can be chosen,
# time, bytes or blockcount
"blockcount": "1K",
"udp": {"bitrate": "50M", "length": "1460K"},
"tcp": {"bitrate": "20M", "length": "256K"},
},
}
}
OPENWISP_MONITORING_IPERF3_CHECK_DELETE_RSA_KEY
type: |
|
default: |
|
This setting allows you to set whether iperf3 check RSA public key will be deleted after successful completion of the check or not.
OPENWISP_MONITORING_IPERF3_CHECK_LOCK_EXPIRE
type: |
|
default: |
|
This setting allows you to set a cache lock expiration time for the iperf3 check when running on multiple servers. Make sure it is always greater than the total iperf3 check time, i.e. greater than the TCP + UDP test time. By default, it is set to 600 seconds (10 mins).
OPENWISP_MONITORING_AUTO_CHARTS
type: |
|
default: |
|
Automatically created charts.
OPENWISP_MONITORING_CRITICAL_DEVICE_METRICS
type: |
|
default: |
|
Device metrics that are considered critical:
when a value crosses the boundary defined in the "threshold value" field
of the alert settings related to one of these metric types, the health
status of the device related to the metric moves into CRITICAL.
By default, if devices are not reachable by pings they are flagged as
CRITICAL.
OPENWISP_MONITORING_HEALTH_STATUS_LABELS
type: |
|
default: |
|
This setting allows to change the health status labels, for example, if we
want to use online instead of ok and offline instead of
critical, you can use the following configuration:
OPENWISP_MONITORING_HEALTH_STATUS_LABELS = {
"ok": "online",
"problem": "problem",
"critical": "offline",
}
OPENWISP_MONITORING_WIFI_SESSIONS_ENABLED
type: |
|
default: |
|
Setting this to False will disable Monitoring WiFi Sessions feature.
OPENWISP_MONITORING_MANAGEMENT_IP_ONLY
type: |
|
default: |
|
By default, only the management IP will be used to perform active checks to the devices.
If the devices are connecting to your OpenWISP instance using a shared
layer2 network, hence the OpenWSP server can reach the devices using the
last_ip field, you can set this to False.
Note
If this setting is not configured, it will fallback to the value of
OPENWISP_CONTROLLER_MANAGEMENT_IP_ONLY setting. If
OPENWISP_CONTROLLER_MANAGEMENT_IP_ONLY also not configured, then
it will fallback to True.
OPENWISP_MONITORING_DEVICE_RECOVERY_DETECTION
type: |
|
default: |
|
When device recovery detection is enabled, recoveries are discovered as soon as a device contacts the openwisp system again (e.g.: to get the configuration checksum or to send monitoring metrics).
This feature is enabled by default.
If you use OpenVPN as the management VPN, you may want to check out a similar integration built in openwisp-network-topology: when the status of an OpenVPN link changes (detected by monitoring the status information of OpenVPN), the network topology module will trigger the monitoring checks. For more information see: Network Topology Device Integration.
OPENWISP_MONITORING_MAC_VENDOR_DETECTION
type: |
|
default: |
|
Indicates whether mac addresses will be complemented with hardware vendor information by performing lookups on the OUI (Organization Unique Identifier) table.
This feature is enabled by default.
OPENWISP_MONITORING_WRITE_RETRY_OPTIONS
type: |
|
default: |
see below |
# default value of OPENWISP_MONITORING_RETRY_OPTIONS:
dict(
max_retries=None,
retry_backoff=True,
retry_backoff_max=600,
retry_jitter=True,
)
Retry settings for recoverable failures during metric writes.
By default if a metric write fails (e.g.: due to excessive load on timeseries database at that moment) then the operation will be retried indefinitely with an exponential random backoff and a maximum delay of 10 minutes.
This feature makes the monitoring system resilient to temporary outages and helps to prevent data loss.
For more information regarding these settings, consult the celery documentation regarding automatic retries for known errors.
Note
The retry mechanism does not work when using UDP for writing data
to the timeseries database. It is due to the nature of UDP
protocol which does not acknowledge receipt of data packets.
OPENWISP_MONITORING_TIMESERIES_RETRY_OPTIONS
type: |
|
default: |
see below |
# default value of OPENWISP_MONITORING_RETRY_OPTIONS:
dict(max_retries=6, delay=2)
On busy systems, communication with the timeseries DB can occasionally fail. The timeseries DB backend will retry on any exception according to these settings. The delay kicks in only after the third consecutive attempt.
This setting shall not be confused with
OPENWISP_MONITORING_WRITE_RETRY_OPTIONS, which is used to configure
the infinite retrying of the celery task which writes metric data to the
timeseries DB, while OPENWISP_MONITORING_TIMESERIES_RETRY_OPTIONS
deals with any other read/write operation on the timeseries DB which may
fail.
However these retries are not handled by celery but are simple python loops, which will eventually give up if a problem persists.
OPENWISP_MONITORING_TIMESERIES_RETRY_DELAY
type: |
|
default: |
|
This settings allow you to configure the retry delay time (in seconds) after 3 failed attempt in timeseries database.
This retry setting is used in retry mechanism to make the requests to the timeseries database resilient.
This setting is independent of celery retry settings.
OPENWISP_MONITORING_DASHBOARD_MAP
type: |
|
default: |
|
Whether the geographic map in the dashboard is enabled or not. This feature provides a geographic map which shows the locations which have devices installed in and provides a visual representation of the monitoring status of the devices, this allows to get an overview of the network at glance.
This feature is enabled by default and depends on the setting
OPENWISP_ADMIN_DASHBOARD_ENABLED from openwisp-utils being set to True (which is the
default).
You can turn this off if you do not use the geographic features of OpenWISP.
OPENWISP_MONITORING_DASHBOARD_TRAFFIC_CHART
type: |
|
default: |
|
This settings allows to configure the interfaces which should be included in the General Traffic chart in the admin dashboard.
This setting should be defined in the following format:
E.g., if you want the General Traffic chart to show data from two interfaces for an organization, you need to configure this setting as follows:
Note
The value of __all__ key is used if an organization does not have
list of interfaces defined in
OPENWISP_MONITORING_DASHBOARD_TRAFFIC_CHART.
Note
If a user can manage more than one organization (e.g. superusers),
then the General Traffic chart will always show data from
interfaces of __all__ configuration.
OPENWISP_MONITORING_METRICS
type: |
|
default: |
|
This setting allows to define additional metric configuration or to
override the default metric configuration defined in
openwisp_monitoring.monitoring.configuration.DEFAULT_METRICS.
For example, if you want to change only the field_name of clients
metric to wifi_clients you can use:
from django.utils.translation import gettext_lazy as _
OPENWISP_MONITORING_METRICS = {
"clients": {
"label": _("WiFi clients"),
"field_name": "wifi_clients",
},
}
For example, if you want to change only the default alert settings of
memory metric you can use:
OPENWISP_MONITORING_METRICS = {
"memory": {"alert_settings": {"threshold": 75, "tolerance": 10}},
}
For example, if you want to change only the notification of
config_applied metric you can use:
from django.utils.translation import gettext_lazy as _
OPENWISP_MONITORING_METRICS = {
"config_applied": {
"notification": {
"problem": {
"verbose_name": "Configuration PROBLEM",
"verb": _("has not been applied"),
"email_subject": _(
"[{site.name}] PROBLEM: {notification.target} configuration "
"status issue"
),
"message": _(
"The configuration for device [{notification.target}]"
"({notification.target_link}) {notification.verb} in a timely manner."
),
},
"recovery": {
"verbose_name": "Configuration RECOVERY",
"verb": _("configuration has been applied again"),
"email_subject": _(
"[{site.name}] RECOVERY: {notification.target} {notification.verb} "
"successfully"
),
"message": _(
"The device [{notification.target}]({notification.target_link}) "
"{notification.verb} successfully."
),
},
},
},
}
Or if you want to define a new metric configuration, which you can then call in your custom code (e.g.: a custom check class), you can do so as follows:
from django.utils.translation import gettext_lazy as _
OPENWISP_MONITORING_METRICS = {
"top_fields_mean": {
"name": "Top Fields Mean",
"key": "{key}",
"field_name": "{field_name}",
"label": "_(Top fields mean)",
"related_fields": ["field1", "field2", "field3"],
},
}
OPENWISP_MONITORING_CHARTS
type: |
|
default: |
|
This setting allows to define additional charts or to override the default
chart configuration defined in
openwisp_monitoring.monitoring.configuration.DEFAULT_CHARTS.
In the following example, we modify the description of the traffic chart:
OPENWISP_MONITORING_CHARTS = {
"traffic": {
"description": (
"Network traffic, download and upload, measured on "
'the interface "{metric.key}", custom message here.'
),
}
}
Or if you want to define a new chart configuration, which you can then call in your custom code (e.g.: a custom check class), you can do so as follows:
from django.utils.translation import gettext_lazy as _
OPENWISP_MONITORING_CHARTS = {
"ram": {
"type": "line",
"title": "RAM usage",
"description": "RAM usage",
"unit": "bytes",
"order": 100,
"query": {
"influxdb": (
"SELECT MEAN(total) AS total, MEAN(free) AS free, "
"MEAN(buffered) AS buffered FROM {key} WHERE time >= '{time}' AND "
"content_type = '{content_type}' AND object_id = '{object_id}' "
"GROUP BY time(1d)"
)
},
}
}
In case you just want to change the colors used in a chart here's how to do it:
OPENWISP_MONITORING_CHARTS = {
"traffic": {"colors": ["#000000", "#cccccc", "#111111"]}
}
Adaptive Size Charts
When configuring charts, it is possible to flag their unit as
adaptive_prefix, this allows to make the charts more readable because
the units are shown in either KB, MB, GB and TB depending on the
size of each point, the summary values and Y axis are also resized.
Example taken from the default configuration of the traffic chart:
OPENWISP_MONITORING_CHARTS = {
"traffic": {
# other configurations for this chart
# traffic measured in 'B' (bytes)
# unit B, KB, MB, GB, TB
"unit": "adaptive_prefix+B",
},
"bandwidth": {
# other configurations for this chart
# adaptive unit for bandwidth related charts
# bandwidth measured in 'bps'(bits/sec)
# unit bps, Kbps, Mbps, Gbps, Tbps
"unit": "adaptive_prefix+bps",
},
}
OPENWISP_MONITORING_DEFAULT_CHART_TIME
type: |
|
default: |
|
possible values |
|
Allows to set the default time period of the time series charts.
OPENWISP_MONITORING_AUTO_CLEAR_MANAGEMENT_IP
type: |
|
default: |
|
This setting allows you to automatically clear management_ip of a device when it goes offline. It is enabled by default.
OPENWISP_MONITORING_API_URLCONF
type: |
|
default: |
|
Changes the urlconf option of django URLs to point the monitoring API
URLs to another installed module, example, myapp.urls. (Useful when
you have a separate API instance.)
OPENWISP_MONITORING_API_BASEURL
type: |
|
default: |
|
If you have a separate instance of the OpenWISP Monitoring API on a
different domain, you can use this option to change the base of the URL,
this will enable you to point all the API URLs to your API server's
domain, example: https://api.myservice.com.
OPENWISP_MONITORING_CACHE_TIMEOUT
type: |
|
default: |
|
This setting allows to configure timeout (in seconds) for monitoring data cache.