NetBox 原生 Prometheus 指标/metrics接入指南配置、指标类型与多进程部署【免费下载链接】netboxThe premier source of truth powering network automation. Open source under Apache 2. Try NetBox Cloud free: https://netboxlabs.com/products/free-netbox-cloud/项目地址: https://gitcode.com/gh_mirrors/ne/netbox本文围绕 NetBox 自带的 Prometheus 监控指标能力展开如何通过METRICS_ENABLED配置在/metrics端点暴露应用指标NetBox 默认采集哪些维度的监控数据以及以多进程多 Gunicorn worker方式部署时如何正确配置共享指标目录。读完本文你将掌握从配置开启、指标链路梳理到生产环境落地采集的一整套实操方案。概述NetBox 为什么内置 Prometheus 指标Prometheus 是当前主流的时序指标平台广泛用于应用与基础设施监控。NetBox 作为网络自动化的事实数据源source of truth在应用层内置了可选的 Prometheus 指标暴露能力开启后应用会在 HTTP 端点/metrics例如https://netbox.local/metrics以 Prometheus 文本格式输出指标供 Prometheus Server 定时抓取。该能力的开关由配置项METRICS_ENABLED控制默认关闭——指标不会未经配置就对外暴露。这一设计兼顾了开箱即用与按需开启两种诉求。NetBox 的指标体系基于 Python 生态中成熟的 django-prometheusdjango-prometheus2.4.0,2.5.0,!2.4.1django-prometheus 通过 Django 中间件、数据库后端替换等手段把模型操作、视图请求、数据库、缓存等维度的埋点自动挂接到请求处理链路中NetBox 在此基础上又扩展了 REST API 与 GraphQL 的自定义计数器。第一步用 METRICS_ENABLED 开启指标暴露配置方式很简单在 NetBox 的配置文件configuration.py中将METRICS_ENABLED设为True。仓库自带的配置示例netbox/netbox/configuration_example.py中明确注释了这一用途# Expose Prometheus monitoring metrics at the HTTP endpoint /metrics METRICS_ENABLED False对应的默认值定义在 settings.pyMETRICS_ENABLED getattr(configuration, METRICS_ENABLED, False)即若configuration.py中未定义该参数则默认False不暴露。设置为True并重启 WSGI 服务后访问https://netbox域名/metrics即可看到指标输出。值得说明的是METRICS_ENABLED并非只在 URL 层面生效它同时驱动了多项底层行为详见下文源码视角小节因此开启它相当于一次性接通整套监控埋点链路而不是简单地挂载一个视图。指标类型总览得益于 django-prometheus 的自动埋点开启后 NetBox 会暴露以下几类指标信息继承自 docs/integrations/prometheus-metrics.md指标类别说明模型操作计数器每个模型Model的 insert / update / delete 操作计数视图请求计数器每个视图View的请求次数计数视图请求延迟直方图每个视图的请求耗时分布histogramREST API 请求指标按端点与请求方法method统计的请求计数GraphQL API 请求指标GraphQL API 请求计数请求体大小直方图请求体request body字节数分布响应体大小直方图响应体response body字节数分布响应码计数器HTTP 响应状态码计数数据库指标数据库连接、执行次数与错误计数器缓存指标缓存命中hit、未命中miss与失效invalidation计数器中间件延迟直方图Django 中间件处理耗时分布Django 元数据指标其他与 Django 运行时相关的元数据指标要获取当前实例完整、权威的指标清单最直接的办法就是开启后访问本实例的/metrics端点——该端点输出的正是 Prometheus 实际抓取的全部指标名称与当前值天然与部署版本保持同步无需依赖任何文档清单。源码视角从配置到指标暴露的完整链路只改一个配置项背后NetBox 实际做了四件事阅读源码可以完整还原这条链路1. 注册 django_prometheus 应用当METRICS_ENABLED为真时django_prometheus始终位于 INSTALLED_APPS 中为指标采集提供应用级支持。2. 替换数据库后端以采集数据库指标settings.py 中会根据开关动态选择数据库引擎if ENGINE not in DATABASES[default]: DATABASES[default].update({ ENGINE: django_prometheus.db.backends.postgresql if METRICS_ENABLED else django.db.backends.postgresql })也就是说开启指标后 PostgreSQL 后端会被替换为 django-prometheus 提供的包装后端从而在数据库连接、查询执行层面产生计数器与直方图——这就是上文数据库连接、执行、错误计数器的来源。3. 注入前后置 Prometheus 中间件settings.py 中开启后会在中间件链的最前端和最末端分别插入两个中间件if METRICS_ENABLED: # If metrics are enabled, add the before after Prometheus middleware MIDDLEWARE [ netbox.middleware.PrometheusBeforeMiddleware, *MIDDLEWARE, netbox.middleware.PrometheusAfterMiddleware, ]这两个中间件定义在 middleware.py分别继承 django-prometheus 的同名基类并指定自定义的metrics_cls Metricsclass PrometheusBeforeMiddleware(middleware.PrometheusBeforeMiddleware): metrics_cls Metrics class PrometheusAfterMiddleware(middleware.PrometheusAfterMiddleware): metrics_cls Metrics它们一前一后包住整个请求周期前者在请求进入时打点如记录开始时间后者在响应返回时统计耗时、响应码、响应体大小等从而生成按视图的请求计数与延迟直方图“响应码计数器”等指标。4. 挂载 /metrics 路由urls.py 中按开关条件挂载 django-prometheus 自带的路由# Prometheus metrics if settings.METRICS_ENABLED: _patterns.append(path(, include(django_prometheus.urls)))这就是/metrics端点的来源。需要注意的是这些路由最终统一置于BASE_PATH前缀之下urls.py如果你的 NetBox 配置了自定义BASE_PATH实际访问地址会相应变为https://域名/BASE_PATH/metrics。深入NetBox 自定义的 REST API 与 GraphQL 指标除了 django-prometheus 的通用指标外NetBox 还通过自定义中间件类扩展了三个 API 相关计数器定义在 metrics.py 中class Metrics(middleware.Metrics): Expand the stock Metrics class from django_prometheus to add our own counters. def register(self): super().register() # REST API metrics self.rest_api_requests self.register_metric( Counter, rest_api_requests_total_by_method, Count of total REST API requests by method, [method], namespaceNAMESPACE, ) self.rest_api_requests_by_view_method self.register_metric( Counter, rest_api_requests_total_by_view_method, Count of REST API requests by view method, [view, method], namespaceNAMESPACE, ) # GraphQL API metrics self.graphql_api_requests self.register_metric( Counter, graphql_api_requests_total, Count of total GraphQL API requests, namespaceNAMESPACE, )rest_api_requests_total_by_method按 HTTP 方法GET/POST/PATCH/DELETE 等统计的 REST API 请求总数rest_api_requests_total_by_view_method按视图 方法组合统计的 REST API 请求数可精确到具体 API 端点graphql_api_requests_totalGraphQL API 请求总数。这些计数器的触发逻辑位于 middleware.py 的PrometheusAfterMiddleware.process_responsedef process_response(self, request, response): response super().process_response(request, response) # Increment REST API request counters if is_api_request(request): method self._method(request) name self._get_view_name(request) self.label_metric(self.metrics.rest_api_requests, request, methodmethod).inc() self.label_metric(self.metrics.rest_api_requests_by_view_method, request, methodmethod, viewname).inc() # Increment GraphQL API request counters elif is_graphql_request(request): self.metrics.graphql_api_requests.inc() return response其中is_api_request与is_graphql_request由 utilities/api.py 提供用于在中间件层面区分 REST 与 GraphQL 请求GraphQL 端点/graphql本身也是 Django 视图仅靠视图名无法与普通页面区分。这解释了为何文档中REST API 请求按端点与方法和GraphQL API 请求被单列为两类指标——它们是 NetBox 在 django-prometheus 之上专门补充的、面向 API 可观测性的差异化能力。多进程部署注意事项Multi Processing Notes当 NetBox 以多进程方式部署例如 Gunicorn 启动多个 worker时Prometheus 客户端库要求使用共享目录来汇聚所有 worker 进程的指标文件。配置步骤如下创建或指定一个本地目录确保所有 worker 进程对该目录拥有读写权限在 WSGI 服务如 Gunicorn的启动环境中将该目录路径定义为环境变量prometheus_multiproc_dir。以仓库自带的 Gunicorn 配置为例contrib/gunicorn.py 默认workers 5、threads 3多 worker 场景下需要在启动命令中注入该环境变量例如prometheus_multiproc_dir/var/run/prometheus_metrics gunicorn --config /opt/netbox/gunicorn.py netbox.wsgi具体路径可自行指定只要满足所有 worker 可读写这一前提即可。重要警告如果多进程环境下长期指标的准确性对部署至关重要官方文档建议优先使用uwsgi库而非gunicorn。原因在于二者对 worker 进程的跟踪机制不同——gunicorn 对 worker 进程的跟踪方式会影响上述配置所生成的指标文件的管理与清理例如 worker 退出后遗留的指标文件可能导致数据错乱或重复计数而 uwsgi 的跟踪机制更有利于维护这些文件。针对这一问题的更详细讨论可参考 NetBox 社区 issue #3779。不过有一个重要的例外场景如果你使用容器化方式部署 NetBox并遵循每个容器内仅运行单个进程one-process-per-container的实践那么每个容器只有一个 worker 进程天然不存在跨进程指标文件冲突问题通常无需为此切换到 uwsgi。换言之裸机/虚拟机多 worker 部署且看重长期指标准确性→ 评估使用 uwsgi容器化、单容器单进程部署→ 保持 gunicorn 即可。接入 Prometheus抓取配置与查询示例开启/metrics后即可在 Prometheus Server 的抓取配置prometheus.yml中加入该目标。以下是一个典型的 scrape job 配置以官方 NetBox 容器/服务部署为例域名按实际替换scrape_configs: - job_name: netbox scheme: https static_configs: - targets: [netbox.local] metrics_path: /metrics抓取到数据后可在 Prometheus / Grafana 中按指标名称与标签进行查询与告警例如查看 NetBox 近 5 分钟 REST API 请求速率rate(rest_api_requests_total_by_method[5m])按视图拆分的 API 请求量sum by (view, method) (rate(rest_api_requests_total_by_view_method[5m]))GraphQL 请求总量graphql_api_requests_total注意实际可用的指标名以你实例/metrics端点的输出为准——指标清单与 django-prometheus 版本、NetBox 版本强相关不同版本之间可能存在增删。上述示例中 REST/GraphQL 相关名称来自 metrics.py 的定义可作为查询起点。小结要点结论开启方式configuration.py中设置METRICS_ENABLED True默认关闭configuration_example.py暴露端点/metrics受BASE_PATH前缀影响路由见 urls.py指标来源django-prometheus 自动埋点 NetBox 自定义 REST/GraphQL 计数器metrics.py开启的副作用自动替换 PostgreSQL 后端、注入前后置中间件settings.py、settings.py多进程部署必须设置prometheus_multiproc_dir共享目录看重长期指标准确性建议评估 uwsgi容器化部署单容器单进程时无需特殊处理gunicorn 即可通过本文的配置步骤与源码级链路梳理你可以为 NetBox 实例快速建立起完整的 Prometheus 可观测性从模型操作、页面与 API 请求到数据库、缓存与中间件性能全部纳入统一监控体系。【免费下载链接】netboxThe premier source of truth powering network automation. Open source under Apache 2. Try NetBox Cloud free: https://netboxlabs.com/products/free-netbox-cloud/项目地址: https://gitcode.com/gh_mirrors/ne/netbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考