ntc-netbox-plugin-metrics-ext

NetBox的插件，用于暴露额外的指标信息。

插件由多个可独立使用的功能组成

• 应用指标端点：在/api/plugins/metrics-ext/app-metrics的Prometheus端点
• RQ Worker指标命令：在每个RQ Worker上添加Prometheus端点

应用指标端点

NetBox已经通过Prometheus端点暴露了一些信息，但当前可用的信息主要是系统级别的，而不是应用级别的。

• 系统指标对于监控代码、跟踪临时信息以及更好地了解正在发生的事情非常有用。（指标示例：请求数量、每秒请求数、异常数量、响应时间等）当多个NetBox实例在负载均衡器后面运行时，每个实例都会生成一组不同的指标，监控系统需要从所有运行的实例中收集这些指标并将它们聚合到仪表板中。NetBox在localhost/metrics NetBox文档中暴露了一些系统指标。
• 应用指标处于更高层次，代表所有在负载均衡器后面运行的应用实例中相同的信息。如果我运行了3个NetBox实例，询问每个实例数据库中有多少设备对象没有意义，因为它们总是返回相同的信息。在这种情况下，目标只暴露一个任何运行实例都可以提供服务的端点。

系统指标和应用级指标是相互补充的。

目前该插件默认公开以下简单指标。

• RQ队列统计。
• 报告统计。
• 模型数量（可通过configuration.py配置）。

添加您自己的指标。

此插件支持一些选项，以在相同的端点生成和发布您自己的应用指标。

选项1 - 通过configuration.py注册函数。

可以创建自己的函数来生成一些指标，并将其在configuration.py中注册到插件中。以下是一个示例，其中自定义函数集中在一个名为metrics.py的文件中，该文件位于主configuration.py旁边。

# metrics.py
from prometheus_client.core import GaugeMetricFamily

def metric_prefix_utilization():
    """Report prefix utilization as a metric per container."""
    from ipam.models import Prefix  # pylint: disable=import-outside-toplevel

    containers = Prefix.objects.filter(status="container").all()
    g = GaugeMetricFamily(
        "netbox_prefix_utilization", "percentage of utilization per container prefix", labels=["prefix", "role", "site"]
    )

    for container in containers:

        site = "none"
        role = "none"
        if container.role:
            role = container.role.slug

        if container.site:
            site = container.site.slug

        g.add_metric(
            [str(container.prefix), site, role], container.get_utilization(),
        )

    yield g

新函数可以导入到configuration.py文件中，并与插件注册。

# configuration.py
from netbox.metrics import metric_prefix_utilization
PLUGINS_CONFIG = {
    "netbox_metrics_ext": {
      "app_metrics": {
        "extras": [
          metric_prefix_utilization
        ]
      }
    }
},

选项2 - 第三方插件注册表。

任何插件都可以包含它自己的指标以提高其可见性或故障排除。第三方插件可以使用ready()函数作为其PluginConfig类的一部分来注册自己的函数。

# my_plugin/__init__.py
from netbox_metrics_ext import register_metric_func
from netbox.metrics import metric_circuit_bandwidth

class MyPluginConfig(PluginConfig):
    name = "netbox_myplugin"
    verbose_name = "Demo Plugin "
    # [ ... ]
    def ready(self):
        super().ready()
        register_metric_func(metric_circuit_bandwidth)

选项3 - 尚未可用 - 指标目录。

将来，可以通过添加预定义目录中的指标来添加指标，类似于报告和脚本。

参数。

可以通过以下设置列表（在netbox_metrics_ext > app_metrics下）控制app_metrics功能的行为。

• reports布尔值（默认为True），发布有关报告的统计信息（成功、警告、信息、失败）。
• queues布尔值（默认为True），发布有关RQ Worker的统计信息（工作器数量、不同队列中的作业数量和类型）。
• models嵌套字典，发布给定对象的计数（设备数量、IP数量等）。第一级必须是模块名称的小写（dcim、ipam等），第二级必须是对象名称（通常以大写字母开头）。

  {
    "dcim": {"Site": True, "Rack": True, "Device": True,},
    "ipam": {"IPAddress": True, "Prefix": True}
  }
  

用法。

配置您的Prometheus服务器以从/api/plugins/metrics-ext/app-metrics/收集应用指标。

# Sample prometheus configuration
scrape_configs:
  - job_name: 'netbox_app'
    scrape_interval: 60s
    metrics_path: /api/plugins/metrics-ext/app-metrics
    static_configs:
      - targets: ['netbox']

RQ Worker指标端点。

此插件添加了一个新的django管理命令rqworker_metrics，该命令的行为与默认的rqworker命令相同，但该命令还公开了Prometheus端点（默认端口8001）。

使用此端点，可以测量在worker中异步运行的任务。

用法。

需要在新命令上执行worker以替换默认的rqworker。

python manage.py rqworker_metrics

用于公开Prometheus端点的端口号可以在每个worker的CLI中配置。

python manage.py rqworker_metrics --prom-port 8002

由于rq-worker是基于分叉模式，要使此功能工作，需要使用多进程模式的Prometheus。要启用此模式，必须定义环境变量prometheus_multiproc_dir并将其指向有效的目录。

安装。

该插件作为pypi上的Python包可用，可以使用pip安装。

pip install ntc-netbox-plugin-metrics-ext

该插件与NetBox 2.8.1及以上版本兼容。

为确保在未来的升级过程中自动重新安装应用指标插件，请创建一个名为local_requirements.txt的文件（如果尚未创建），位于NetBox根目录中（与requirements.txt相同），并列出ntc-netbox-plugin-metrics-ext包。

# echo ntc-netbox-plugin-metrics-ext >> local_requirements.txt

安装后，需要在configuration.py中启用插件。

# In your configuration.py
PLUGINS = ["netbox_metrics_ext"]

# PLUGINS_CONFIG = {
#   "netbox_metrics_ext": {
#     "app_metrics": {
#       "models": {
#         "dcim": {"Site": True, "Rack": True, "Device": True,},
#          "ipam": {"IPAddress": True, "Prefix": True},
#        },
#        "reports": True,
#        "queues": True,
#       }
#     }
#   }
# }

包含的Grafana仪表板。

此插件包含一个Grafana仪表板，该仪表板将使用上面的示例配置工作。要安装此仪表板，请将JSON从Grafana仪表板导入到Grafana中。

贡献。

欢迎提交拉取请求。项目通过TravisCI自动构建和测试，兼容多个Python版本和多个NetBox版本。

项目使用基于docker-compose的轻量级开发环境，以帮助本地开发和在TravisCI中运行测试。

项目遵循网络到代码软件开发指南，并利用

• Black、Pylint、Bandit和pydocstyle进行Python代码风格检查和格式化。
• 使用Django单元测试来确保插件正常工作。

CLI辅助命令

项目包含一个基于invoke的CLI辅助工具，用于设置开发环境。命令分为以下三类：开发环境、实用工具和测试。

每个命令都可以用invoke <command>执行。所有命令都支持--netbox-ver和--python-ver参数，如果您想手动指定Python和NetBox的版本。每个命令也都有其自己的帮助信息invoke <command> --help

本地开发环境

  build            Build all docker images.
  debug            Start NetBox and its dependencies in debug mode.
  destroy          Destroy all containers and volumes.
  start            Start NetBox and its dependencies in detached mode.
  stop             Stop NetBox and its dependencies.

实用工具

  cli              Launch a bash shell inside the running NetBox container.
  create-user      Create a new user in django (default: admin), will prompt for password.
  makemigrations   Run Make Migration in Django.
  nbshell          Launch a nbshell session.

测试

  tests            Run all tests for this plugin.
  pylint           Run pylint code analysis.
  pydocstyle       Run pydocstyle to validate docstring formatting adheres to NTC defined standards.
  bandit           Run bandit to validate basic static code security analysis.
  black            Run black to check that Python files adhere to its style standards.
  unittest         Run Django unit tests for the plugin.

问题

如有任何问题或评论，请先查看常见问题解答，并欢迎访问Network to Code Slack频道（频道#networktocode）。请在此注册

应用度量端点的默认指标

默认情况下，插件将生成以下指标

# HELP netbox_queue_stats Per RQ queue and job status statistics
# TYPE netbox_queue_stats gauge
netbox_queue_stats{name="check_releases",status="finished"} 0.0
netbox_queue_stats{name="check_releases",status="started"} 0.0
netbox_queue_stats{name="check_releases",status="deferred"} 0.0
netbox_queue_stats{name="check_releases",status="failed"} 0.0
netbox_queue_stats{name="check_releases",status="scheduled"} 0.0
netbox_queue_stats{name="default",status="finished"} 0.0
netbox_queue_stats{name="default",status="started"} 0.0
netbox_queue_stats{name="default",status="deferred"} 0.0
netbox_queue_stats{name="default",status="failed"} 0.0
netbox_queue_stats{name="default",status="scheduled"} 0.0
# HELP netbox_report_stats Per report statistics
# TYPE netbox_report_stats gauge
netbox_report_stats{name="test_hostname",status="success"} 13.0
netbox_report_stats{name="test_hostname",status="warning"} 0.0
netbox_report_stats{name="test_hostname",status="failure"} 0.0
netbox_report_stats{name="test_hostname",status="info"} 0.0
# HELP netbox_model_count Per NetBox Model count
# TYPE netbox_model_count gauge
netbox_model_count{app="dcim",name="Site"} 24.0
netbox_model_count{app="dcim",name="Rack"} 24.0
netbox_model_count{app="dcim",name="Device"} 46.0
netbox_model_count{app="ipam",name="IPAddress"} 58.0
netbox_model_count{app="ipam",name="Prefix"} 18.0
# HELP netbox_app_metrics_processing_ms Time in ms to generate the app metrics endpoint
# TYPE netbox_app_metrics_processing_ms gauge
netbox_app_metrics_processing_ms 19.90485