nautobot 插件容量指标

Nautobot的插件，用于公开其他指标信息。

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

• Application Metrics Endpoint：普罗米修斯端点/api/plugins/capacity-metrics/app-metrics
• RQ Queue Metrics Endpoint：普罗米修斯端点/api/plugins/capacity-metrics/rq-metrics
• RQ Worker Metrics 命令：在每个 RQ worker 上添加 prometheus 端点

应用程序指标端点

Nautobot 已经通过 Prometheus 端点公开了一些信息，但当前可用的信息主要是在系统级别，而不是在应用程序级别。

• SYSTEM Metrics对于检测代码、跟踪临时信息和更好地了解正在发生的事情非常有用。（指标示例：请求数、每秒请求数、异常数、响应时间等......）这个想法是，当 Nautobot 的多个实例在负载均衡器后面运行时，每个实例都会产生一组不同的指标和监控系统需要从所有正在运行的实例中收集这些指标，并将它们汇总到仪表板中。localhost/metrics Nautobot 在Nautobot DOC公开了一些系统指标。
• 应用程序指标处于更高级别，代表在负载均衡器后面运行的应用程序的所有实例中相同的信息。如果我有 3 个 Nautobot 实例正在运行，则没有必要询问每个实例我在数据库中有多少个 Device 对象，因为它们总是会返回相同的信息。在这种情况下，目标是仅公开 1 个可由任何正在运行的实例提供服务的端点。

系统指标和应用程序级别指标相辅相成

目前该插件默认公开这些简单的指标：

• RQ 队列统计
• 工作统计
• 模型数量（可通过 nautobot_config.py 配置）

队列系统指标端点

除了默认的 Nautobot 系统指标，这些指标/metrics主要集中在 Nautobot 所基于的 Django 系统上，该插件围绕 Nautobot 用于与 Nautobot 工作服务通信的排队系统提供了一些额外的系统指标。这个端点是通过 单独提供的/api/plugins/capacity-metrics/rq-metrics，这个端点可以比其他应用程序指标端点更频繁地被抓取。

添加您自己的指标

这个插件支持一些选项来生成和发布你自己的应用程序指标在同一个端点后面。

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

可以创建自己的函数来生成一些指标并将其注册到 nautobot_config.py 中的插件中。这是一个示例，其中自定义函数集中在metrics.py位于 main 旁边的文件中nautobot_config.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(
        "nautobot_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

可以在nautobot_config.py文件中导入新功能并在插件中注册。

# nautobot_config.py
from nautobot.metrics import metric_prefix_utilization
PLUGINS_CONFIG = {
    "nautobot_capacity_metrics": {
      "app_metrics": {
        "extras": [
          metric_prefix_utilization
        ]
      }
    }
},

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

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

# my_plugin/__init__.py
from nautobot_capacity_metrics import register_metric_func
from nautobot.metrics import metric_circuit_bandwidth

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

选项 3 - 尚不可用 - 指标目录

将来，可以通过将指标添加到预定义目录中来添加指标，类似于作业。

插件配置参数

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

• gitrepositories布尔值（默认为False），发布关于 gitrepositories 的统计信息（成功、警告、信息、失败）

• jobs布尔值（默认为False），发布有关作业的统计信息（成功、警告、信息、失败）

• queues布尔值（默认为False），发布关于 RQ Worker 的统计信息（worker 的 nbr、nbr 和不同队列中的作业类型）

• models嵌套字典，发布给定对象（Nbr 设备、Nbr IP 等）的计数。第一层必须是小写的模块名称（dcim、ipam 等），第二层必须是对象的名称（通常以大写开头）

  PLUGINS_CONFIG = {
    "nautobot_capacity_metrics": {
      "app_metrics": {
        "models": {
           "dcim": {"Site": True, "Rack": True, "Device": True},
           "ipam": {"IPAddress": True, "Prefix": True},
         },
         "jobs": True,
         "queues": True,
       }
     }
  }
  

用法

配置您的 Prometheus 服务器以收集应用程序指标/api/plugins/capacity-metrics/app-metrics/

# Sample prometheus configuration
scrape_configs:
  - job_name: 'nautobot_app'
    scrape_interval: 120s
    metrics_path: /api/plugins/capacity-metrics/app-metrics
    static_configs:
      - targets: ['nautobot']
  - job_name: 'nautobot_queue'
    scrape_interval: 20s
    metrics_path: /api/plugins/capacity-metrics/rq-metrics
    static_configs:
      - targets: ['nautobot']

RQ Worker 指标端点

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

有了这个端点，就可以检测在 worker 中异步运行的任务。

用法

新命令需要在worker上执行，作为默认的替代rqworker

nautobot-server rqworker_metrics

可以在 CLI 中为每个 worker 配置用于暴露 prometheus 端点的端口。

nautobot-server rqworker_metrics --prom-port 8002

由于 rq-worker 基于 fork 模型，因此要使此功能正常工作，需要在多进程模式下使用 prometheus。要启用此模式，prometheus_multiproc_dir必须定义环境变量并指向有效目录。

安装

该插件在 pypi 中作为 Python 包提供，可以使用 pip 安装

pip install nautobot-capacity-metrics

该插件与 Nautobot 1.0.0 及更高版本兼容

为确保在未来升级期间自动重新安装 Application Metrics Plugin，请在 Nautobot 根目录（旁边）中创建一个名为local_requirements.txt（如果不存在）的文件requirements.txt并列出nautobot-capacity-metrics软件包：

# echo nautobot-capacity-metrics >> local_requirements.txt

安装后，需要在您的插件中启用该插件nautobot_config.py

# In your nautobot_config.py
PLUGINS = ["nautobot_capacity_metrics"]

# PLUGINS_CONFIG = {
#     "nautobot_capacity_metrics": {
#         "app_metrics": {
#             "gitrepositories": True,
#             "jobs": True,
#             "models": {
#                 "dcim": {
#                     "Site": True,
#                     "Rack": True,
#                     "Device": True,
#                     "Interface": True,
#                     "Cable": True,
#                 },
#                 "ipam": {
#                     "IPAddress": True,
#                     "Prefix": True,
#                 },
#                 "extras": {
#                     "GitRepository": True
#                 },
#             },
#             "queues": True,
#         }
#     },
# }

如果您需要修改插件配置远离默认值，请参考插件配置参数。

包括 Grafana 仪表板

此插件中包含一个 Grafana 仪表板，它将与上面的示例配置一起使用。要安装此仪表板，请将 Grafana 仪表板中的 JSON导入 Grafana。

贡献

拉取请求受到欢迎，并通过 TravisCI 针对多个版本的 Python 和多个版本的 Nautobot 自动构建和测试。

该项目打包了一个基于轻量级的开发环境，docker-compose以帮助项目的本地开发并在 TravisCI 中运行测试。

该项目遵循 Network to Code 软件开发指南并利用：

• 用于 Python linting 和格式化的 Black、Pylint、Bandit 和 pydocstyle。
• Django 单元测试以确保插件正常工作。

CLI 帮助程序命令

该项目附带一个基于调用的 CLI 帮助程序，以帮助设置开发环境。下面列出了 3 个类别中的命令dev environment，utility以及testing。

每个命令都可以用invoke <command>. 所有命令都支持参数--nautobot-ver，--python-ver如果您想手动定义要使用的 Python 和 Nautobot 的版本。每个命令也有自己的帮助invoke <command> --help

本地开发环境

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

效用

  cli              Launch a bash shell inside the running Nautobot 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）摇摆。在这里注册

应用程序指标端点的默认指标

以下指标将通过/api/plugins/capacity-metrics/app-metrics端点提供：

# HELP nautobot_gitrepository_task_stats Per Git repository task statistics
# TYPE nautobot_gitrepository_task_stats gauge
nautobot_gitrepository_task_stats{module="repo1",name="main",status="success"} 1.0
nautobot_gitrepository_task_stats{module="repo1",name="main",status="warning"} 0.0
nautobot_gitrepository_task_stats{module="repo1",name="main",status="failure"} 0.0
nautobot_gitrepository_task_stats{module="repo1",name="main",status="info"} 6.0
nautobot_gitrepository_task_stats{module="repo1",name="total",status="success"} 1.0
nautobot_gitrepository_task_stats{module="repo1",name="total",status="warning"} 0.0
nautobot_gitrepository_task_stats{module="repo1",name="total",status="failure"} 0.0
nautobot_gitrepository_task_stats{module="repo1",name="total",status="info"} 6.0
# HELP nautobot_gitrepository_execution_status Git repository completion status
# TYPE nautobot_gitrepository_execution_status gauge
nautobot_gitrepository_execution_status{module="repo1",status="pending"} 0.0
nautobot_gitrepository_execution_status{module="repo1",status="running"} 0.0
nautobot_gitrepository_execution_status{module="repo1",status="completed"} 1.0
nautobot_gitrepository_execution_status{module="repo1",status="errored"} 0.0
nautobot_gitrepository_execution_status{module="repo1",status="failed"} 0.0
# HELP nautobot_job_task_stats Per Job task statistics
# TYPE nautobot_job_task_stats gauge
nautobot_job_task_stats{module="local/users/CheckUser",name="total",status="success"} 1.0
nautobot_job_task_stats{module="local/users/CheckUser",name="total",status="warning"} 0.0
nautobot_job_task_stats{module="local/users/CheckUser",name="total",status="failure"} 0.0
nautobot_job_task_stats{module="local/users/CheckUser",name="total",status="info"} 0.0
nautobot_job_task_stats{module="local/users/CheckUser",name="test_is_uppercase",status="success"} 1.0
nautobot_job_task_stats{module="local/users/CheckUser",name="test_is_uppercase",status="warning"} 0.0
nautobot_job_task_stats{module="local/users/CheckUser",name="test_is_uppercase",status="failure"} 0.0
nautobot_job_task_stats{module="local/users/CheckUser",name="test_is_uppercase",status="info"} 0.0
# HELP nautobot_job_execution_status Job completion status
# TYPE nautobot_job_execution_status gauge
nautobot_job_execution_status{module="local/users/CheckUser",status="pending"} 0.0
nautobot_job_execution_status{module="local/users/CheckUser",status="running"} 0.0
nautobot_job_execution_status{module="local/users/CheckUser",status="completed"} 1.0
nautobot_job_execution_status{module="local/users/CheckUser",status="errored"} 0.0
nautobot_job_execution_status{module="local/users/CheckUser",status="failed"} 0.0
# HELP nautobot_model_count Per Nautobot Model count
# TYPE nautobot_model_count gauge
nautobot_model_count{app="dcim",name="Site"} 24.0
nautobot_model_count{app="dcim",name="Rack"} 24.0
nautobot_model_count{app="dcim",name="Device"} 46.0
nautobot_model_count{app="ipam",name="IPAddress"} 58.0
nautobot_model_count{app="ipam",name="Prefix"} 18.0
nautobot_model_count{app="extras",name="GitRepository"} 1.0
# HELP nautobot_app_metrics_processing_ms Time in ms to generate the app metrics endpoint
# TYPE nautobot_app_metrics_processing_ms gauge
nautobot_app_metrics_processing_ms 59.48257

以下指标将通过/api/plugins/capacity-metrics/rq-metrics端点提供：

# HELP nautobot_queue_number_jobs Number of Job per RQ queue and status
# TYPE nautobot_queue_number_jobs gauge
nautobot_queue_number_jobs{name="check_releases",status="finished"} 0.0
nautobot_queue_number_jobs{name="check_releases",status="started"} 0.0
nautobot_queue_number_jobs{name="check_releases",status="deferred"} 0.0
nautobot_queue_number_jobs{name="check_releases",status="failed"} 0.0
nautobot_queue_number_jobs{name="check_releases",status="scheduled"} 0.0
nautobot_queue_number_jobs{name="default",status="finished"} 0.0
nautobot_queue_number_jobs{name="default",status="started"} 0.0
nautobot_queue_number_jobs{name="default",status="deferred"} 0.0
nautobot_queue_number_jobs{name="default",status="failed"} 0.0
nautobot_queue_number_jobs{name="default",status="scheduled"} 0.0
# HELP nautobot_queue_number_workers Number of worker per queue
# TYPE nautobot_queue_number_workers gauge
nautobot_queue_number_workers{name="check_releases"} 0.0
nautobot_queue_number_workers{name="default"} 2.0
# HELP nautobot_rq_metrics_processing_ms Time in ms to generate the app metrics endpoint
# TYPE nautobot_rq_metrics_processing_ms gauge
nautobot_rq_metrics_processing_ms 33.34308