EMQX Exporter 技术文档

镜像概述和主要用途

emqx-exporter 用于暴露 EMQX Prometheus API 未包含的部分指标，补充 EMQX 监控能力。该工具兼容 EMQX 4.4 与 EMQX 5 版本（包括开源版和企业版），支持与 Prometheus、Grafana 集成，构建完整的 EMQX 监控面板。

核心功能和特性

• 补充指标暴露：提供 EMQX 原生 Prometheus API 未覆盖的关键指标
• 多版本兼容：支持 EMQX 4.4 和 EMQX 5 版本的开源及企业版部署
• 探针功能：可配置 TCP 探针监控 EMQX 服务端口状态
• 灵活集成：支持 Prometheus 指标抓取与 Grafana 可视化
• TLS 支持：实验性 TLS 端点功能，提升数据传输安全性

使用场景和适用范围

适用于需要全面监控 EMQX 集群状态的场景，特别是：

• 企业级 EMQX 部署的精细化监控需求
• 需监控 EMQX 服务端口可用性的场景
• 构建包含补充指标的自定义 Grafana 监控面板
• 对 EMQX 4.4/5 混合集群进行统一监控

使用方法和配置说明

前置要求

1. EMQX 访问权限
   emqx-exporter 需要通过 EMQX Dashboard API 访问集群数据，需使用 Basic Auth 认证，因此需在 EMQX Dashboard 中创建 API 密钥。不同版本的 EMQX 创建方式存在差异：

   • EMQX 5
     创建 API 密钥（路径：Dashboard → 系统设置 → API 密钥）。

   • EMQX 4.4
     创建新 用户（非 应用），并确保用户具备访问 API 的权限。

2. 插件启用
   所有 EMQX 节点需启用 emqx_prometheus 插件，可通过 Dashboard 插件页面（http://<集群地址>:***/#/plugins）逐一检查。

安装部署

Docker 快速启动

bash
docker run -d \
  --name emqx-exporter \
  -p 8085:8085 \
  -v $(pwd)/config.yml:/etc/emqx-exporter/config.yml \
  emqx/emqx-exporter \
  --config.file=/etc/emqx-exporter/config.yml

Docker Compose 部署

创建 docker-compose.yml：

yaml
version: '3'
services:
  emqx-exporter:
    image: emqx/emqx-exporter
    ports:
      - "8085:8085"
    volumes:
      - ./config.yml:/etc/emqx-exporter/config.yml
    command: --config.file=/etc/emqx-exporter/config.yml
    restart: always
    environment:
      - TZ=Asia/Shanghai

启动服务：

bash
docker-compose up -d

Kubernetes 部署

参考 ***示例，通过 Deployment 和 Service 资源部署，需配置环境变量或 ConfigMap 挂载配置文件。

配置说明

配置文件格式

emqx-exporter 支持通过配置文件定义监控目标和探针，默认监听 HTTP 端口 8085。配置文件示例：

yaml
metrics:
  target: 127.0.0.1:***  # EMQX Dashboard API 地址
  api_key: "your_api_key"   # API 密钥（EMQX 5）或用户名（EMQX 4.4）
  api_secret: "your_secret" # API 密钥密钥（EMQX 5）或密码（EMQX 4.4）
probes:
  - target: 127.0.0.1:1883  # 待探测的 EMQX 服务端口（如 MQTT 端口）

参数说明

• metrics：指标采集配置（可选），未配置则禁用指标功能

  • target：EMQX Dashboard 地址（格式：IP:端口）
  • api_key：访问 Dashboard API 的认证密钥/用户名
  • api_secret：访问 Dashboard API 的密钥/密码

• probes：端口探针配置（可选列表），未配置则禁用探针功能

  • target：待探测的目标端口（格式：IP:端口）

Prometheus 配置

Prometheus 需配置三个抓取任务，分别采集 EMQX 原生指标、exporter 指标及探针指标。配置示例：

yaml
scrape_configs:
  # 1. EMQX 原生指标（EMQX 5）
  - job_name: 'emqx-self-metrics'
    metrics_path: /api/v5/prometheus/stats
    scrape_interval: 5s
    honor_labels: true
    static_configs:
      - targets: [<EMQX节点地址>:***]  # 所有 EMQX 节点地址列表
        labels:
          cluster: <集群名称>           # 集群标识标签
          from: emqx                    # 固定标签，不可修改

  # 2. Exporter 补充指标
  - job_name: 'exporter-metrics'
    metrics_path: /metrics
    scrape_interval: 5s
    static_configs:
      - targets: [<exporter地址>:8085]  # emqx-exporter 地址
        labels:
          cluster: <集群名称>
          from: exporter               # 固定标签，不可修改

  # 3. Exporter 探针指标
  - job_name: 'exporter-probe'
    metrics_path: /probe
    params:
      target: [<探针目标>]  # 需与配置文件中 probes[*].target 一致
    scrape_interval: 5s
    static_configs:
      - targets: [<exporter地址>:8085]
        labels:
          cluster: <集群名称>
          from: exporter

Grafana 集成

1. 导入仪表板模板
   下载 仪表板模板 中的 JSON 文件，通过 Grafana 导入（路径：Dashboards → Import → 上传 JSON 文件）。

2. 查看监控面板
   导入后可在 Grafana 中查看名为 EMQX 的仪表板，包含完整的指标可视化图表。

关于仪表板导入的详细操作，参考 Grafana ***文档。

高级配置

TLS 端点（实验性）

emqx-exporter 支持通过 Web 配置文件启用 TLS，配置示例：

1. 创建 web-config.yml：

yaml
tls_server_config:
  cert_file: /path/to/cert.pem
  key_file: /path/to/key.pem

2. 启动时指定配置文件：

bash
./emqx-exporter --web.config.file=web-config.yml

详细配置说明参考 exporter-toolkit HTTPS 文档。

指标说明

仪表板指标的详细解释可参考 仪表板模板说明文档。

结构与架构

!架构图

emqx-exporter 通过访问 EMQX Dashboard API 采集补充指标，并提供探针功能监控服务端口，最终将数据暴露给 Prometheus，结合 Grafana 实现可视化监控。