sapcc/unbound_exporter

Unbound Prometheus Exporter 镜像文档

镜像概述

Unbound Prometheus Exporter是一个用于收集Unbound DNS解析器运行指标的工具，通过Prometheus兼容格式暴露指标，便于监控系统（如Prometheus+Grafana）对Unbound服务的性能、健康状态进行实时跟踪和分析。

核心功能和特性

• 全面的指标收集：支持Unbound关键运行指标，包括DNS查询总量、查询类型分布、缓存命中率、递归查询次数、响应时间分位数、服务器连接状态等。
• Unbound原生集成：通过Unbound的控制接口（unbound-control）或统计信息文件（unbound-statistics）获取数据，无需修改Unbound核心配置。
• Prometheus兼容：输出符合Prometheus规范的指标格式（OpenMetrics），支持Prometheus自动发现和指标抓取。
• 轻量级设计：镜像体积小，资源占用低，适合在资源受限环境中部署。
• 可配置性：支持自定义监听端口、指标路径、Unbound连接参数等，适配不同部署场景。

使用场景和适用范围

• DNS服务监控：实时监控Unbound DNS解析器的查询量、成功率、延迟等核心指标。
• 性能分析：通过缓存命中率、递归查询比例等指标优化Unbound配置（如缓存大小、上游服务器设置）。
• 故障排查：结合指标异常（如查询失败率突增、响应时间延长）快速定位DNS服务问题。
• 适用对象：运维工程师、系统管理员、需要监控DNS服务健康状态的企业或个人用户。

使用方法

前置条件

1. Unbound DNS解析器已安装并运行，且已启用控制接口（control-enable: yes）或统计信息输出（具体配置参考Unbound官方文档）。
2. 确保Exporter能够访问Unbound的控制接口（默认端口8953）或统计信息文件路径。

Docker Run 示例

bash
docker run -d \
  --name unbound-exporter \
  -p 9167:9167 \  # Exporter监听端口，默认9167
  -e UNBOUND_HOST=192.168.1.100 \  # Unbound服务器IP/主机名，默认localhost
  -e UNBOUND_PORT=8953 \  # Unbound控制接口端口，默认8953
  -e UNBOUND_PASSWORD=your-unbound-control-password \  # 若Unbound控制接口启用密码认证
  -e LISTEN_PORT=9167 \  # 自定义Exporter监听端口（可选，默认9167）
  -e METRICS_PATH=/metrics \  # 自定义指标暴露路径（可选，默认/metrics）
  prometheus-unbound-exporter:latest

Docker Compose 示例

yaml
version: '3'
services:
  unbound-exporter:
    image: prometheus-unbound-exporter:latest
    container_name: unbound-exporter
    ports:
      - "9167:9167"
    environment:
      - UNBOUND_HOST=unbound-server  # 可使用Docker网络内的服务名
      - UNBOUND_PORT=8953
      - UNBOUND_PASSWORD=secure-password
      - LISTEN_PORT=9167
    restart: unless-stopped
    networks:
      - monitoring-network  # 确保与Prometheus、Unbound在同一网络

networks:
  monitoring-network:
    external: true  # 若已存在监控网络，设为true

Prometheus 配置

在Prometheus的prometheus.yml中添加如下抓取配置，以收集Exporter暴露的指标：

yaml
scrape_configs:
  - job_name: 'unbound'
    static_configs:
      - targets: ['unbound-exporter:9167']  # Exporter的地址和端口
    scrape_interval: 15s  # 抓取频率，根据需求调整

配置参数

支持的核心指标

Exporter暴露的主要指标示例（完整列表可通过访问http://<exporter-ip>:<port>/metrics查看）：

• unbound_queries_total：DNS查询总次数（按查询类型、响应码等标签拆分）
• unbound_cache_hits_ratio：缓存命中率
• unbound_response_time_seconds：DNS响应时间（分位数，如p50/p90/p99）
• unbound_recursion_count_total：递归查询次数
• unbound_up：Exporter与Unbound的连接状态（1=正常，0=异常）

注意事项

1. 确保Unbound控制接口配置正确（control-interface、control-port、server-key-file等），否则Exporter可能无法获取指标。
2. 若Unbound运行在Docker容器中，需确保Exporter与Unbound在同一网络，或通过端口映射暴露控制接口。
3. 生产环境建议为Exporter配置资源限制（如--memory=128m），避免异常占用过多资源。