openwisp-monitoring 1.0.4

在生产环境中部署

见

• ansible-openwisp2

• docker-openwisp

安装系统依赖项

openwisp-monitoring 使用InfluxDB来存储指标。请按照InfluxDB官方文档中的安装说明进行操作。

注意：在openwisp-monitoring中只支持InfluxDB 1.8.x。

安装系统包

sudo apt install -y openssl libssl-dev \
                    gdal-bin libproj-dev libgeos-dev \
                    fping

从PyPI安装稳定版本

从PyPI安装

pip install openwisp-monitoring

安装开发版本

安装tar包

pip install https://github.com/openwisp/openwisp-monitoring/tarball/master

或者，您可以使用pip通过git安装

pip install -e git+git://github.com/openwisp/openwisp-monitoring#egg=openwisp_monitoring

如果您想贡献，请遵循“为开发安装”部分中的说明。

开发环境安装

安装“安装系统依赖”部分中提到的系统依赖。安装以下开发所需的附加包

sudo apt install -y sqlite3 libsqlite3-dev \
                    libspatialite-dev libsqlite3-mod-spatialite \
                    chromium

创建并克隆分叉的仓库

git clone git://github.com/<your_fork>/openwisp-monitoring

导航到克隆的仓库中

cd openwisp-monitoring/

使用Docker启动Redis和InfluxDB

docker-compose up -d redis influxdb

设置并激活虚拟环境。（我们将使用virtualenv）

python -m virtualenv env
source env/bin/activate

在下一步之前，请确保您正在使用pip版本20.2.4

pip install -U pip wheel setuptools

安装开发依赖

pip install -e .
pip install -r requirements-test.txt
npm install -g jshint stylelint

从https://chromedriver.chromium.org/home下载适用于您浏览器版本的WebDriver for Chromium，并将其解压到您的$PATH目录之一（例如：~/.local/bin/）。

创建数据库

cd tests/
./manage.py migrate
./manage.py createsuperuser

使用以下命令运行celery和celery-beat（需要单独的终端窗口）

cd tests/
celery -A openwisp2 worker -l info
celery -A openwisp2 beat -l info

启动开发服务器

./manage.py runserver 0.0.0.0:8000

您可以通过http://127.0.0.1:8000/admin/访问管理界面。

使用以下命令运行测试

./runtests.py --parallel

使用以下命令运行质量保证测试

./run-qa-checks

在Docker上安装和运行

注意：此Docker镜像仅适用于开发目的。有关官方OpenWISP Docker镜像，请参阅：docker-openwisp。

从Dockerfile构建

docker-compose build

运行Docker容器

docker-compose up

设置（集成到现有的Django项目中）

遵循openwisp-controller的设置说明，然后添加以下描述的设置。

INSTALLED_APPS = [
    # django apps
    # all-auth
    'django.contrib.sites',
    'allauth',
    'allauth.account',
    'allauth.socialaccount',
    'django_extensions',
    'django_filters',
    # openwisp2 modules
    'openwisp_users',
    'openwisp_controller.pki',
    'openwisp_controller.config',
    'openwisp_controller.connection',
    'openwisp_controller.geo',
    # monitoring
    'openwisp_monitoring.monitoring',
    'openwisp_monitoring.device',
    'openwisp_monitoring.check',
    'nested_admin',
    # notifications
    'openwisp_notifications',
    # openwisp2 admin theme (must be loaded here)
    'openwisp_utils.admin_theme',
    # admin
    'django.contrib.admin',
    'django.forms',
    # other dependencies ...
]

# Make sure you change them in production
# You can select one of the backends located in openwisp_monitoring.db.backends
TIMESERIES_DATABASE = {
    'BACKEND': 'openwisp_monitoring.db.backends.influxdb',
    'USER': 'openwisp',
    'PASSWORD': 'openwisp',
    'NAME': 'openwisp2',
    'HOST': 'localhost',
    'PORT': '8086',
}

urls.py:

from django.conf import settings
from django.conf.urls import include, url
from django.contrib.staticfiles.urls import staticfiles_urlpatterns

from openwisp_utils.admin_theme.admin import admin, openwisp_admin

openwisp_admin()

urlpatterns = [
    url(r'^admin/', include(admin.site.urls)),
    url(r'', include('openwisp_controller.urls')),
    url(r'', include('openwisp_monitoring.urls')),
]

urlpatterns += staticfiles_urlpatterns()

配置缓存（如果您想使用不同的缓存存储，可以更改）

CACHES = {
    'default': {
        'BACKEND': 'django_redis.cache.RedisCache',
        'LOCATION': 'redis://localhost/0',
        'OPTIONS': {
            'CLIENT_CLASS': 'django_redis.client.DefaultClient',
        }
    }
}

SESSION_ENGINE = 'django.contrib.sessions.backends.cache'
SESSION_CACHE_ALIAS = 'default'

配置celery（如果您想使用不同的代理，可以更改）

# here we show how to configure celery with redis but you can
# use other brokers if you want, consult the celery docs
CELERY_BROKER_URL = 'redis://localhost/1'
CELERY_BEAT_SCHEDULE = {
    'run_checks': {
        'task': 'openwisp_monitoring.check.tasks.run_checks',
        'schedule': timedelta(minutes=5),
    },
}

INSTALLED_APPS.append('djcelery_email')
EMAIL_BACKEND = 'djcelery_email.backends.CeleryEmailBackend'

如果您决定使用Redis（如以下示例所示），请安装以下Python包。

pip install redis django-redis

安装OpenWISP监控

使用“安装说明”中提到的任一方法安装OpenWISP Monitoring。

在设备上安装openwisp-config

在您的设备上安装openwisp-config代理。

在设备上安装监控包

在您的设备上安装openwrt-openwisp-monitoring包。

这些包从设备收集并发送监控数据到OpenWISP Monitoring，收集指标（如接口流量、WiFi客户端、CPU负载、内存使用等）是必需的。

注意：如果您是openwisp-monitoring的现有用户并正在使用用于收集指标的传统监控模板，我们强烈建议从监控脚本迁移到监控包。

确保OpenWISP可以访问您的设备

为了执行主动检查和其他操作，如触发配置更改的推送、执行shell命令或执行固件升级，OpenWISP服务器需要能够访问网络设备。

OpenWISP主要有两种部署场景

1. OpenWISP服务器部署在公共互联网上，而设备地理分布在不同的位置：在这种情况下需要一个管理隧道

2. OpenWISP服务器部署在计算机/服务器上，该计算机/服务器位于设备所在的同一层2网络（即同一局域网）中。在这种情况下不需要管理隧道

# In /etc/config/openwisp on the device

config controller 'http'
    # ... other configuration directives ...
    option management_interface 'tun0'

为设备创建检查

默认情况下，为所有设备自动创建活动检查，除非已禁用某些特定检查的自动创建。有关如何进行此操作的更多信息，请参阅活动检查部分。

这些检查由celery工作进程在后台创建和执行。

UNKNOWN

每当创建新设备时，它将默认具有UNKNOWN作为其健康状态。

这意味着系统尚不知道设备是否可访问。

OK

一切正常。

PROBLEM

其中一个度量值的值不在预期范围内（已超过警报设置中设置的阈值值）。

示例：CPU使用率应低于90%，但当前值为95%。

CRITICAL

在OPENWISP_MONITORING_CRITICAL_DEVICE_METRICS中定义的一个度量值的值不在预期范围内（已超过警报设置中设置的阈值值）。

示例：ping默认是一个关键度量值，预期始终为1（可访问）。

设备状态

此度量值存储设备的状态以供查看。

Ping

运行时间:

丢包率:

往返时间:

流量

{
  'organization_id': '<organization-id-of-the-related-device>',
  'ifname': '<interface-name>',
  # optional
  'location_id': '<location-id-of-the-related-device-if-present>',
  'floorplan_id': '<floorplan-id-of-the-related-device-if-present>',
}

WiFi客户端

{
  'organization_id': '<organization-id-of-the-related-device>',
  'ifname': '<interface-name>',
  # optional
  'location_id': '<location-id-of-the-related-device-if-present>',
  'floorplan_id': '<floorplan-id-of-the-related-device-if-present>',
}

内存使用

CPU负载

磁盘使用

移动信号强度

移动信号质量

正在使用的移动接入技术

Ping

此检查返回有关设备运行时间和RTT（往返时间）的信息。创建了图表运行时间、丢包率和rtt。使用fping命令收集这些指标。您可以选择通过将OPENWISP_MONITORING_AUTO_PING设置为False来禁用此检查的自动创建。

您可以使用OPENWISP_MONITORING_PING_CHECK_CONFIG设置更改用于ping检查的默认值。

应用的配置

此检查确保openwisp-config代理正在运行并及时应用配置更改。您可以通过使用设置OPENWISP_MONITORING_AUTO_DEVICE_CONFIG_CHECK来选择禁用此检查的自动创建。

此检查定期运行，但也会在设备配置状态更改时触发，这确保检查能够快速响应网络中的事件，并在出现任何不符合预期的情况时及时通知用户。

OPENWISP_MONITORING_SHORT_RETENTION_POLICY

存储原始设备数据的默认保留策略。

这些数据仅用于评估设备最近的状态，长时间保留它不会带来很多好处，并且会消耗更多的磁盘空间。

OPENWISP_MONITORING_AUTO_PING

是否为设备自动创建ping检查。

OPENWISP_MONITORING_PING_CHECK_CONFIG

此设置允许覆盖在openwisp_monitoring.check.classes.ping.DEFAULT_PING_CHECK_CONFIG中定义的默认ping检查配置。

例如，如果您只想更改ping的timeout，则可以使用

OPENWISP_MONITORING_PING_CHECK_CONFIG = {
    'timeout': {
        'default': 1000,
    },
}

如果您要覆盖openwisp_monitoring.check.classes.ping.DEFAULT_PING_CHECK_CONFIG中定义的任何参数的默认值，超出最大值或最小值，则需要像以下那样覆盖maximum或minimum字段

OPENWISP_MONITORING_PING_CHECK_CONFIG = {
    'timeout': {
        'default': 2000,
        'minimum': 1500,
        'maximum': 2500,
    },
}

注意：上述 最大值 和 最小值 仅用于验证 Check 对象的自定义参数。

OPENWISP_MONITORING_AUTO_DEVICE_CONFIG_CHECK

此设置允许您选择是否为新注册的设备自动创建 config_applied 检查。默认情况下是启用的。

OPENWISP_MONITORING_CONFIG_CHECK_INTERVAL

此设置允许您配置 config_applied 使用的配置检查间隔。默认设置为 5 分钟。

OPENWISP_MONITORING_AUTO_CHARTS

自动创建的图表。

OPENWISP_MONITORING_CRITICAL_DEVICE_METRICS

认为是关键设备的指标

当值超过与这些指标类型相关的警报设置中“阈值值”字段定义的边界时，与该指标相关的设备的健康状况将移动到 CRITICAL 状态。

默认情况下，如果设备无法通过 ping 访问，它们将被标记为 CRITICAL。

OPENWISP_MONITORING_HEALTH_STATUS_LABELS

此设置允许更改健康状况标签，例如，如果我们想用 online 代替 ok，用 offline 代替 critical，则可以使用以下配置

OPENWISP_MONITORING_HEALTH_STATUS_LABELS = {
    'ok': 'online',
    'problem': 'problem',
    'critical': 'offline'
}

OPENWISP_MONITORING_MANAGEMENT_IP_ONLY

默认情况下，只有管理 IP 将用于对设备执行主动检查。

如果设备正在使用共享层 2 网络连接到您的 OpenWISP 实例，因此 OpenWSP 服务器可以使用 last_ip 字段访问设备，则可以将此设置为 False。

OPENWISP_MONITORING_DEVICE_RECOVERY_DETECTION

当启用设备恢复检测时，设备恢复会在设备再次联系 openwisp 系统时被发现（例如：获取配置校验和或发送监控指标）。

此功能默认启用。

如果您使用 OpenVPN 作为管理 VPN，您可能希望查看 openwisp-network-topology 中内置的类似集成：当 OpenVPN 链路的状态发生变化时（通过监视 OpenVPN 的状态信息检测），网络拓扑模块将触发监控检查。有关更多信息，请参阅：网络拓扑设备集成

OPENWISP_MONITORING_MAC_VENDOR_DETECTION

指示是否通过在 OUI（组织唯一标识符）表中查找来使用硬件厂商信息补充 MAC 地址。

此功能默认启用。

OPENWISP_MONITORING_WRITE_RETRY_OPTIONS

# default value of OPENWISP_MONITORING_RETRY_OPTIONS:

dict(
    max_retries=None,
    retry_backoff=True,
    retry_backoff_max=600,
    retry_jitter=True,
)

在指标写入期间可恢复失败的重新尝试设置。

默认情况下，如果指标写入失败（例如：由于当时时间序列数据库负载过高），则操作将无限期地使用指数随机退避和最大延迟 10 分钟进行重试。

此功能使监控系统对暂时中断具有弹性，并有助于防止数据丢失。

有关这些设置的更多信息，请参阅 Celery 关于已知错误自动重试的文档。

OPENWISP_MONITORING_TIMESERIES_RETRY_OPTIONS

# default value of OPENWISP_MONITORING_RETRY_OPTIONS:

dict(
    max_retries=6,
    delay=2
)

在繁忙的系统上，与时间序列 DB 的通信有时会失败。时间序列 DB 后端将根据这些设置在任何异常上重试。延迟仅在第三次连续尝试后启动。

此设置不应与 OPENWISP_MONITORING_WRITE_RETRY_OPTIONS 混淆，后者用于配置将指标数据写入时序数据库的 celery 任务无限重试，而 OPENWISP_MONITORING_TIMESERIES_RETRY_OPTIONS 用于处理可能失败的时序数据库上的任何其他读写操作。

然而，这些重试是由 celery 处理的，而不是简单的 python 循环，如果问题持续存在，最终会放弃。

OPENWISP_MONITORING_TIMESERIES_RETRY_DELAY

此设置允许您配置在时序数据库中失败 3 次尝试后的重试延迟时间（以秒为单位）。

此重试设置用于重试机制，以使对时序数据库的请求具有弹性。

此设置独立于 celery 重试设置。

OPENWISP_MONITORING_DASHBOARD_MAP

仪表板中的地理地图是否启用。此功能提供一张显示安装了设备的地理位置的地图，并提供了设备监控状态的视觉表示，这使得可以一瞥网络概览。

默认启用此功能，并依赖于来自 openwisp-utils 的设置 OPENWISP_ADMIN_DASHBOARD_ENABLED 被设置为 True（默认值）。

如果您不使用 OpenWISP 的地理功能，可以将其关闭。

OPENWISP_MONITORING_METRICS

此设置允许您定义额外的指标配置或覆盖在 openwisp_monitoring.monitoring.configuration.DEFAULT_METRICS 中定义的默认指标配置。

例如，如果您只想更改 clients 指标的 field_name 为 wifi_clients，则可以使用以下内容：

from django.utils.translation import gettext_lazy as _

OPENWISP_MONITORING_METRICS = {
    'clients': {
        'label': _('WiFi clients'),
        'field_name': 'wifi_clients',
    },
}

例如，如果您只想更改 memory 指标的默认警报设置，则可以使用以下内容：

OPENWISP_MONITORING_METRICS = {
    'memory': {
        'alert_settings': {'threshold': 75, 'tolerance': 10}
    },
}

例如，如果您只想更改 config_applied 指标的警报通知，则可以使用以下内容：

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.'
                ),
            },
        },
    },
}

或者，如果您想定义一个新的指标配置，然后可以在自定义代码（例如：自定义检查类）中调用它，可以这样操作：

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

此设置允许您定义额外的图表或覆盖在 openwisp_monitoring.monitoring.configuration.DEFAULT_CHARTS 中定义的默认图表配置。

例如，如果您想将流量图表更改为显示 MB（兆字节）而不是 GB（千兆字节），则可以使用以下内容：

OPENWISP_MONITORING_CHARTS = {
    'traffic': {
        'unit': ' MB',
        'description': (
            'Network traffic, download and upload, measured on '
            'the interface "{metric.key}", measured in MB.'
        ),
        'query': {
            'influxdb': (
                "SELECT SUM(tx_bytes) / 1000000 AS upload, "
                "SUM(rx_bytes) / 1000000 AS download FROM {key} "
                "WHERE time >= '{time}' AND content_type = '{content_type}' "
                "AND object_id = '{object_id}' GROUP BY time(1d)"
            )
        },
    }
}

或者，如果您想定义一个新的图表配置，然后可以在自定义代码（例如：自定义检查类）中调用它，可以这样操作：

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)"
            )
        },
    }
}

如果您只想更改图表中使用的颜色，以下是操作方法：

OPENWISP_MONITORING_CHARTS = {
    'traffic': {
        'colors': ['#000000', '#cccccc']
    }
}

OPENWISP_MONITORING_AUTO_CLEAR_MANAGEMENT_IP

此设置允许您在设备离线时自动清除设备的 management_ip。默认启用。

OPENWISP_MONITORING_API_URLCONF

更改 django urls 的 urlconf 选项，以便将监控 API urls 指向另一个已安装的模块，例如 myapp.urls。（当您有一个单独的 API 实例时很有用。）

OPENWISP_MONITORING_API_BASEURL

如果您有在另一个域上运行的 openwisp-monitoring API 服务器，您可以使用此选项更改 URL 的基础，这将使您能够将所有 API urls 指向您的 openwisp-monitoring API 服务器域，例如：https://mymonitoring.myapp.com。

register_metric

此函数用于从代码的任何位置注册一个新的指标配置。

下面已显示示例用法。

from django.utils.translation import gettext_lazy as _
from openwisp_monitoring.monitoring.configuration import register_metric

# Define configuration of your metric
metric_config = {
    'label': _('Ping'),
    'name': 'Ping',
    'key': 'ping',
    'field_name': 'reachable',
    'related_fields': ['loss', 'rtt_min', 'rtt_max', 'rtt_avg'],
    'charts': {
        'uptime': {
            'type': 'bar',
            'title': _('Uptime'),
            'description': _(
                'A value of 100% means reachable, 0% means unreachable, values in '
                'between 0% and 100% indicate the average reachability in the '
                'period observed. Obtained with the fping linux program.'
            ),
            'summary_labels': [_('Average uptime')],
            'unit': '%',
            'order': 200,
            'colorscale': {
                'max': 100,
                'min': 0,
                'label': _('Reachable'),
                'scale': [
                    [[0, '#c13000'],
                    [0.1,'cb7222'],
                    [0.5,'#deed0e'],
                    [0.9, '#7db201'],
                    [1, '#498b26']],
                ],
                'map': [
                   [100, '#498b26', _('Reachable')],
                   [90, '#7db201', _('Mostly Reachable')],
                   [50, '#deed0e', _('Partly Reachable')],
                   [10, '#cb7222', _('Mostly Unreachable')],
                   [None, '#c13000', _('Unreachable')],
                ],
                'fixed_value': 100,
            },
            'query': chart_query['uptime'],
        },
        'packet_loss': {
            'type': 'bar',
            'title': _('Packet loss'),
            'description': _(
                'Indicates the percentage of lost packets observed in ICMP probes. '
                'Obtained with the fping linux program.'
            ),
            'summary_labels': [_('Average packet loss')],
            'unit': '%',
            'colors': '#d62728',
            'order': 210,
            'query': chart_query['packet_loss'],
        },
        'rtt': {
            'type': 'scatter',
            'title': _('Round Trip Time'),
            'description': _(
                'Round trip time observed in ICMP probes, measuered in milliseconds.'
            ),
            'summary_labels': [
                _('Average RTT'),
                _('Average Max RTT'),
                _('Average Min RTT'),
            ],
            'unit': _(' ms'),
            'order': 220,
            'query': chart_query['rtt'],
        },
    },
    'alert_settings': {'operator': '<', 'threshold': 1, 'tolerance': 0},
    'notification': {
        'problem': {
            'verbose_name': 'Ping PROBLEM',
            'verb': 'cannot be reached anymore',
            'level': 'warning',
            'email_subject': _(
                '[{site.name}] {notification.target} is not reachable'
            ),
            'message': _(
                'The device [{notification.target}] {notification.verb} anymore by our ping '
                'messages.'
            ),
        },
        'recovery': {
            'verbose_name': 'Ping RECOVERY',
            'verb': 'has become reachable',
            'level': 'info',
            'email_subject': _(
                '[{site.name}] {notification.target} is reachable again'
            ),
            'message': _(
                'The device [{notification.target}] {notification.verb} again by our ping '
                'messages.'
            ),
        },
    },
}

# Register your custom metric configuration
register_metric('ping', metric_config)

以上示例将注册一个指标配置（命名为 ping），三个图表配置（命名为 rtt、packet_loss、uptime），如 charts 键中定义；两个通知类型（命名为 ping_recovery、ping_problem），如 notification 键中定义。

ping 指标的 AlertSettings 默认将使用在 alert_settings 键中定义的 threshold 和 tolerance。您始终可以通过 admin 覆盖它们并定义自己的自定义值。

注意：如果已注册具有相同名称（不要与 verbose_name 混淆）的指标配置，将引发 ImproperlyConfigured 异常。

如果您不需要注册新的指标，但需要更改现有指标配置的特定键，可以使用 OPENWISP_MONITORING_METRICS。

unregister_metric

此功能用于从代码中的任何位置注销指标配置。

以下是一个示例用法。

from openwisp_monitoring.monitoring.configuration import unregister_metric

# Unregister previously registered metric configuration
unregister_metric('metric_name')

注意：如果相关的指标配置未注册，将引发 ImproperlyConfigured 异常。

register_chart

此功能用于从代码中的任何位置注册新的图表配置。

下面已显示示例用法。

from openwisp_monitoring.monitoring.configuration import register_chart

# Define configuration of your chart
chart_config = {
    'type': 'histogram',
    'title': 'Histogram',
    'description': 'Histogram',
    'top_fields': 2,
    'order': 999,
    'query': {
        'influxdb': (
            "SELECT {fields|SUM|/ 1} FROM {key} "
            "WHERE time >= '{time}' AND content_type = "
            "'{content_type}' AND object_id = '{object_id}'"
        )
    },
}

# Register your custom chart configuration
register_chart('chart_name', chart_config)

注意：如果已注册具有相同名称（不要与 verbose_name 混淆）的图表配置，将引发 ImproperlyConfigured 异常。

如果您不需要注册新的图表，但需要更改现有图表配置的特定键，可以使用 OPENWISP_MONITORING_CHARTS。

unregister_chart

此功能用于从代码中的任何位置注销图表配置。

以下是一个示例用法。

from openwisp_monitoring.monitoring.configuration import unregister_chart

# Unregister previously registered chart configuration
unregister_chart('chart_name')

注意：如果相关的图表配置未注册，将引发 ImproperlyConfigured 异常。

TimeseriesWriteException

路径： openwisp_monitoring.db.exceptions.TimeseriesWriteException

如果在时序数据库中写入数据时出现任何失败，将引发此异常，并带有有用的错误消息，解释失败的原因。通常将捕获此异常，并在后台重试失败的写入任务，以确保在 Timeseries 服务器过载的情况下不会丢失数据。您可以在 OPENWISP_MONITORING_WRITE_RETRY_OPTIONS 中了解有关此重试机制的更多信息。

InvalidMetricConfigException

路径： openwisp_monitoring.monitoring.exceptions.InvalidMetricConfigException

如果指标配置损坏，将引发此异常。

InvalidChartConfigException

路径： openwisp_monitoring.monitoring.exceptions.InvalidChartConfigException

如果图表配置损坏，将引发此异常。

实时文档

这是一个通用的实时API文档（遵循OpenAPI规范），位于/api/v1/docs/。

可浏览的Web界面

此外，在浏览器中直接打开以下列出的任何端点，将显示Django-REST-Framework的可浏览API界面，这使得查找每个端点的详细信息变得更加容易。

端点列表

由于详细的说明包含在每个点的实时文档和可浏览网页中，因此这里我们只提供可用端点的列表，更多信息请打开浏览器中的端点URL。

GET /v1/monitoring/device/{pk}/?key={key}&status=true

POST /v1/monitoring/device/{pk}/?key={key}&time={time}

POST /v1/monitoring/device/{pk}/?key={key}&time={time}&current=true

device_metrics_received

路径: openwisp_monitoring.device.signals.device_metrics_received

参数:

• instance：已接收度量值的Device实例

• request：HTTP请求对象

• time：将保存度量的时间。如果没有提供，则使用服务器时间

• current：数据是否刚刚收集，或者由于网络连接问题而以前收集但现在发送

当接收到的设备度量发送到DeviceMetric视图时（仅当使用HTTP POST时）会发出此信号。

信号在返回成功响应之前发出，如果响应不成功则不会发出。

health_status_changed

路径: openwisp_monitoring.device.signals.health_status_changed

参数:

• instance：状态已更改的DeviceMonitoring实例

• status：通过它更新了DeviceMonitoring的现有状态

只有当DeviceMonitoring对象的健康状态更新时，才会发出此信号。

threshold_crossed

路径: openwisp_monitoring.monitoring.signals.threshold_crossed

参数:

• metric：定义在相关警报设置中的阈值的Metric对象

• alert_settings：与Metric相关的AlertSettings

• target：相关的Device对象

• first_time：当第一次写入度量时，将其设置为true。之后应将其设置为false。

• tolerance_crossed：如果度量已越过警报设置中配置的容差阈值，则将其设置为true。否则，将其设置为false。

first_time参数可用于避免启动不必要的操作。例如，发送恢复通知。

当在警报设置中定义的指标的阈值被越过时，将发出此信号。

pre_metric_write

路径： openwisp_monitoring.monitoring.signals.pre_metric_write

参数:

• metric：需要存储在时序数据库中的指标对象

• values：需要存储在时序数据库中的指标数据

• time：与指标一起保存的时间

• current：数据是否刚刚收集，或者由于网络连接问题而以前收集但现在发送

在将写操作发送到时序数据库之前，为每个指标发出此信号。

post_metric_write

路径： openwisp_monitoring.monitoring.signals.post_metric_write

参数:

• metric：正在存储在时序数据库中的指标对象

• values：正在存储在时序数据库中的指标数据

• time：与指标一起保存的时间

• current：数据是否刚刚收集，或者由于网络连接问题而以前收集但现在发送

在后台成功执行写操作后，为每个指标发出此信号。

run_checks

此命令将执行所有设备的所有可用检查。默认情况下，检查由celery beat定期运行。您可以在设置中了解更多信息。

示例用法

cd tests/
./manage.py run_checks

migrate_timeseries

此命令触发时序数据库的异步迁移。

示例用法

cd tests/
./manage.py migrate_timeseries

1. 初始化自定义模块

要扩展任何openwisp-monitoring应用，您首先需要创建一个新的django应用，该应用将包含您对该openwisp-monitoring应用的定制版本。

django应用 nothing more than a python package（一个python脚本目录），在以下示例中，我们将这些django应用称为mycheck、mydevicemonitoring、mymonitoring，但您可以按照自己的意愿命名

django-admin startapp mycheck
django-admin startapp mydevicemonitoring
django-admin startapp mymonitoring

请注意，上述命令必须从您的PYTHON_PATH目录中调用，以便您可以将结果导入到项目中。

现在，您需要将mycheck添加到您的settings.py中的INSTALLED_APPS，并确保已从您的项目中移除了openwisp_monitoring.check

INSTALLED_APPS = [
    # ... other apps ...
    # 'openwisp_monitoring.check',        <-- comment out or delete this line
    # 'openwisp_monitoring.device',       <-- comment out or delete this line
    # 'openwisp_monitoring.monitoring'    <-- comment out or delete this line
    'mycheck',
    'mydevicemonitoring',
    'mymonitoring',
    'nested_admin',
]

有关如何使用django项目和django应用的更多信息，请参阅django文档中的“教程：编写您的第一个Django应用”。

2. 安装openwisp-monitoring

安装（并将openwisp-monitoring添加到您的项目需求中）

pip install --U https://github.com/openwisp/openwisp-monitoring/tarball/master

3. 添加EXTENDED_APPS

将以下内容添加到您的settings.py

EXTENDED_APPS = ['device_monitoring', 'monitoring', 'check']

4. 添加openwisp_utils.staticfiles.DependencyFinder

将openwisp_utils.staticfiles.DependencyFinder添加到您的settings.py中的STATICFILES_FINDERS

STATICFILES_FINDERS = [
    'django.contrib.staticfiles.finders.FileSystemFinder',
    'django.contrib.staticfiles.finders.AppDirectoriesFinder',
    'openwisp_utils.staticfiles.DependencyFinder',
]

5. 添加openwisp_utils.loaders.DependencyLoader

将openwisp_utils.loaders.DependencyLoader添加到您的settings.py中的TEMPLATES

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'OPTIONS': {
            'loaders': [
                'django.template.loaders.filesystem.Loader',
                'django.template.loaders.app_directories.Loader',
                'openwisp_utils.loaders.DependencyLoader',
            ],
            'context_processors': [
                'django.template.context_processors.debug',
                'django.template.context_processors.request',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
            ],
        },
    }
]

6. 继承AppConfig类

请参阅测试项目示例应用中的以下文件

• sample_check/__init__.py.

• sample_check/apps.py.

• sample_monitoring/__init__.py.

• sample_monitoring/apps.py.

• sample_device_monitoring/__init__.py.

• sample_device_monitoring/apps.py.

有关AppConfig概念的相关信息，请参阅django文档中的“Applications”部分。

7. 创建自定义模型

要扩展check应用，请参阅sample_check models.py文件。

要扩展monitoring应用，请参阅sample_monitoring models.py文件。

要扩展device_monitoring应用，请参阅sample_device_monitoring models.py文件。

注意:

• 有关如何使用、扩展或开发模型的相关疑问，请参阅django文档中的“Models”部分。

• 有关代理模型的问题，请参考代理模型。

8. 添加交换器配置

将以下内容添加到您的settings.py

# Setting models for swapper module
# For extending check app
CHECK_CHECK_MODEL = 'YOUR_MODULE_NAME.Check'
# For extending monitoring app
MONITORING_CHART_MODEL = 'YOUR_MODULE_NAME.Chart'
MONITORING_METRIC_MODEL = 'YOUR_MODULE_NAME.Metric'
MONITORING_ALERTSETTINGS_MODEL = 'YOUR_MODULE_NAME.AlertSettings'
# For extending device_monitoring app
DEVICE_MONITORING_DEVICEDATA_MODEL = 'YOUR_MODULE_NAME.DeviceData'
DEVICE_MONITORING_DEVICEMONITORING_MODEL = 'YOUR_MODULE_NAME.DeviceMonitoring'

将<YOUR_MODULE_NAME>替换为你的实际django应用名称（也称为app_label）。

9. 创建数据库迁移

创建并应用数据库迁移

./manage.py makemigrations
./manage.py migrate

有关更多信息，请参阅django文档中的“迁移”部分。

10. 创建自定义管理器

要扩展check应用，请参考sample_check admin.py文件。

要扩展monitoring应用，请参考sample_monitoring admin.py文件。

要扩展device_monitoring应用，请参考sample_device_monitoring admin.py文件。

要修改admin，你可以按照以下两种方式之一进行。

注意：有关django admin工作方式或如何定制的疑问，请参阅django文档中的“django admin网站”部分。

from openwisp_monitoring.check.admin import CheckAdmin

CheckAdmin.list_display.insert(1, 'my_custom_field')
CheckAdmin.ordering = ['-my_custom_field']

from openwisp_monitoring.device.admin import DeviceAdmin

DeviceAdmin.list_display.insert(1, 'my_custom_field')
DeviceAdmin.ordering = ['-my_custom_field']

from openwisp_monitoring.monitoring.admin import MetricAdmin, AlertSettingsAdmin

MetricAdmin.list_display.insert(1, 'my_custom_field')
MetricAdmin.ordering = ['-my_custom_field']
AlertSettingsAdmin.list_display.insert(1, 'my_custom_field')
AlertSettingsAdmin.ordering = ['-my_custom_field']

from django.contrib import admin

from openwisp_monitoring.check.admin import CheckAdmin as BaseCheckAdmin
from swapper import load_model

Check = load_model('check', 'Check')

admin.site.unregister(Check)

@admin.register(Check)
class CheckAdmin(BaseCheckAdmin):
    # add your changes here

from django.contrib import admin

from openwisp_monitoring.device_monitoring.admin import DeviceAdmin as BaseDeviceAdmin
from swapper import load_model

Device = load_model('config', 'Device')

admin.site.unregister(Device)

@admin.register(Device)
class DeviceAdmin(BaseDeviceAdmin):
    # add your changes here

from django.contrib import admin

from openwisp_monitoring.monitoring.admin import (
    AlertSettingsAdmin as BaseAlertSettingsAdmin,
    MetricAdmin as BaseMetricAdmin
)
from swapper import load_model

Metric = load_model('Metric')
AlertSettings = load_model('AlertSettings')

admin.site.unregister(Metric)
admin.site.unregister(AlertSettings)

@admin.register(Metric)
class MetricAdmin(BaseMetricAdmin):
    # add your changes here

@admin.register(AlertSettings)
class AlertSettingsAdmin(BaseAlertSettingsAdmin):
    # add your changes here

11. 创建根URL配置

请参考测试项目中的urls.py文件。

有关django中URL配置的更多信息，请参阅django文档中的“URL分发器”部分。

12. 创建celery.py

请参考测试项目中的celery.py文件。

有关celery在django中使用方式的更多信息，请参阅celery文档中的“使用Django的初学者指南”部分。

13. 导入Celery任务

在settings.py中添加以下内容以从device_monitoring应用导入celery任务。

CELERY_IMPORTS = ('openwisp_monitoring.device.tasks',)

14. 创建自定义命令run_checks

请参考测试项目中的run_checks.py文件。

有关django中自定义管理命令使用方式的更多信息，请参阅django文档中的“编写自定义django-admin命令”部分。

15. 导入自动测试

当基于此模块开发自定义应用时，同时导入和运行基本测试是个好主意，这样你可以确保你引入的更改不会破坏openwisp-monitoring的一些现有功能。

如果需要添加破坏性更改，可以覆盖基类中定义的测试以测试自己的行为。

有关扩展check应用的更多信息，请参阅sample_check应用的测试。

要扩展 device_monitoring 应用程序，请查看 sample_device_monitoring 应用的测试 以了解如何操作。

要扩展 monitoring 应用程序，请查看 sample_monitoring 应用的测试 以了解如何操作。

可以继承和扩展的其他基类

以下步骤不是必需的，而是为了进行更高级的定制。

# mydevice/api/views.py
from openwisp_monitoring.device.api.views import (
    DeviceMetricView as BaseDeviceMetricView
)

class DeviceMetricView(BaseDeviceMetricView):
    # add your customizations here ...
    pass

re_path(
    'api/v1/monitoring/device/(?P<pk>[^/]+)/$',
    views.device_metric,
    name='api_device_metric',
),

# urls.py
from mydevice.api.views import DeviceMetricView

urlpatterns = [
    # ... other URLs
    re_path(r'^(?P<path>.*)$', DeviceMetricView.as_view(), name='api_device_metric',),
]