288 lines
8.7 KiB
Markdown
288 lines
8.7 KiB
Markdown
# NETCONF Transceiver Exporter
|
||
|
||
基于 Python 的 Prometheus Exporter，通过 NETCONF 周期性轮询 H3C 交换机，采集光模块（transceiver）及其物理通道指标，并通过 HTTP `/metrics` 暴露给 Prometheus。
|
||
|
||
本项目已按设计文档 `specs/transceiver-exporter-design-v9.md` 与 TDD 文档 `specs/transcrive-exporter-tdd-design-v2.md` 实现，并带有完整测试集。
|
||
|
||
下面以本仓库为路径 `/home/yuyr/dev/switch_lab/netconf_exporter` 为例，说明从零开始的操作步骤。
|
||
|
||
---
|
||
|
||
## 1. 创建虚拟环境 & 安装依赖
|
||
|
||
### 1.1 创建虚拟环境
|
||
|
||
```bash
|
||
cd /home/yuyr/dev/switch_lab/netconf_exporter
|
||
|
||
python3 -m venv .venv
|
||
source .venv/bin/activate
|
||
```
|
||
|
||
之后所有命令都建议在虚拟环境中执行（终端提示符前通常会有 `(.venv)`）。
|
||
|
||
### 1.2 安装依赖
|
||
|
||
```bash
|
||
cd /home/yuyr/dev/switch_lab/netconf_exporter
|
||
|
||
pip install --upgrade pip
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
`requirements.txt` 包含：
|
||
|
||
- 运行依赖：`fastapi`, `uvicorn`, `ncclient`, `cryptography`, `prometheus_client`, `PyYAML` 等；
|
||
- 开发/测试依赖：`pytest`, `pytest-asyncio`, `pytest-cov`, `httpx` 等。
|
||
|
||
---
|
||
|
||
## 2. 运行测试
|
||
|
||
项目所有源码都在 `src/exporter/` 下，测试在 `tests/` 目录中。
|
||
|
||
推荐使用如下命令运行所有测试：
|
||
|
||
```bash
|
||
cd /home/yuyr/dev/switch_lab/netconf_exporter
|
||
|
||
PYTHONPATH=src .venv/bin/pytest -q
|
||
```
|
||
|
||
- 会自动加载 `tests/conftest.py` 中定义的配置（包括从 `.env` 加载 H3C NETCONF 参数）；
|
||
- 默认会运行：
|
||
- 单元/组件测试；
|
||
- 集成测试（包括 HTTP E2E）；
|
||
- H3C NETCONF live 测试（如果 `.env` 中配置了可用的 H3C 连接参数）。
|
||
|
||
如果只想运行 H3C 相关测试，可以使用 mark 过滤，例如：
|
||
|
||
```bash
|
||
PYTHONPATH=src .venv/bin/pytest -q -m "h3c_live"
|
||
```
|
||
|
||
只跑 HTTP 端到端测试：
|
||
|
||
```bash
|
||
PYTHONPATH=src .venv/bin/pytest -q -m "http_e2e"
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 配置 H3C NETCONF 访问参数（.env）
|
||
|
||
为了方便本地联调 H3C 设备，本项目支持从 `.env` 文件中加载 H3C 连接参数。`tests/conftest.py` 会在 pytest 启动时自动读取 `.env`。
|
||
|
||
在项目根目录创建或编辑 `.env`：
|
||
|
||
```env
|
||
H3C_NETCONF_HOST=127.0.0.1
|
||
H3C_NETCONF_PORT=8830
|
||
H3C_NETCONF_USER=netconf_user
|
||
H3C_NETCONF_PASSWORD='NASPLab123!'
|
||
```
|
||
|
||
说明：
|
||
|
||
- 上述示例假设已经在本机将 127.0.0.1:8830 转发到真实 H3C 设备的 NETCONF 端口；
|
||
- `.env` 支持行尾注释（以 `#` 开头的行会被忽略），支持被单/双引号包裹的值；
|
||
- 若不想把密码写入 `.env`，可以在 shell 中 `export H3C_NETCONF_PASSWORD=...`，环境变量优先生效。
|
||
|
||
---
|
||
|
||
## 4. 编辑配置文件 config.yaml
|
||
|
||
Exporter 在启动时从 `config.yaml` 中加载全局配置和静态设备列表。典型最小配置示例如下（仅含全局配置，设备通过 HTTP API 注册）：
|
||
|
||
```yaml
|
||
global:
|
||
http_listen: "0.0.0.0:19100" # HTTP 监听地址
|
||
scrape_interval_seconds: 5 # 采集周期（秒）
|
||
netconf_port: 830 # 默认 NETCONF 端口（可被 runtime 设备覆盖）
|
||
connect_timeout_seconds: 5 # SSH 连接超时
|
||
rpc_timeout_seconds: 30 # RPC 调用超时
|
||
max_workers: 5
|
||
|
||
api_token: "changeme" # HTTP API token，curl/客户端需携带
|
||
|
||
runtime_db_path: "./devices.db" # SQLite 路径（保存 runtime 设备列表）
|
||
|
||
# Fernet 密钥：32 字节 URL-safe Base64（长度 44）
|
||
# 生成方式：
|
||
# python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
|
||
password_secret: "在这里替换为你的FernetKey"
|
||
|
||
ssh_keepalive_seconds: 30
|
||
failure_threshold: 3 # 连续失败多少次开始退避
|
||
max_backoff_factor: 8 # 最大退避倍数
|
||
shutdown_timeout_seconds: 60 # 关停时等待 scraper 的超时时间
|
||
|
||
log_level: INFO
|
||
log_to_stdout: true
|
||
log_file: "" # 若非空，则写入指定文件
|
||
|
||
devices: [] # 静态设备先留空，通过 API 动态注册
|
||
```
|
||
|
||
注意：
|
||
|
||
- `global.password_secret` 必须是合法的 Fernet key，否则程序会在启动时抛异常；
|
||
- 若将 `shutdown_timeout_seconds` 配得太小，相比 `scrape_interval_seconds + rpc_timeout_seconds`，会在启动时打印一个 warning（来自配置校验），提示关停可能会在 RPC 尚未结束时终止 scraper。
|
||
|
||
---
|
||
|
||
## 5. 启动 Exporter HTTP Server
|
||
|
||
虚拟环境里，使用如下命令启动服务：
|
||
|
||
```bash
|
||
cd /home/yuyr/dev/switch_lab/netconf_exporter
|
||
|
||
PYTHONPATH=src .venv/bin/python -m exporter.main --config config.yaml
|
||
```
|
||
|
||
行为说明：
|
||
|
||
- 启动时：
|
||
- 加载 `config.yaml`；
|
||
- 初始化日志系统（包含 `device=...` 字段）；
|
||
- 初始化 SQLite `devices.db`；
|
||
- 加载静态设备（若有）；
|
||
- 启动 Scraper 线程，按全局配置定期轮询设备；
|
||
- 启动 Uvicorn HTTP server，默认监听 `http_listen`（例如 `0.0.0.0:19100`）。
|
||
- Ctrl+C 时：
|
||
- Uvicorn 会优雅关停 HTTP；
|
||
- Scraper 会收到 stop 信号并在 `shutdown_timeout_seconds` 内退出；
|
||
- 所有 NETCONF 连接和 SQLite 资源会被关闭；
|
||
- `KeyboardInterrupt` 会被捕获，退出不会打印 traceback。
|
||
|
||
启动成功后，可以在另一个终端通过：
|
||
|
||
```bash
|
||
curl -s http://127.0.0.1:19100/healthz
|
||
```
|
||
|
||
查看基本健康状态（`{"status":"ok", ...}`）。
|
||
|
||
---
|
||
|
||
## 6. 通过 curl 注册 H3C 设备（runtime device）
|
||
|
||
假设已经准备好 H3C 的 NETCONF 代理：
|
||
|
||
- H3C 可通过 127.0.0.1:8830 被访问；
|
||
- 用户名/密码为 `.env` 中配置的 `H3C_NETCONF_USER` / `H3C_NETCONF_PASSWORD`。
|
||
|
||
启动 exporter 后，在另一个终端中执行（注意 token 要与 config.yaml 中一致）：
|
||
|
||
```bash
|
||
cd /home/yuyr/dev/switch_lab/netconf_exporter
|
||
|
||
curl -s -X POST \
|
||
-H "Content-Type: application/json" \
|
||
-H "X-API-Token: changeme" \
|
||
-d '{
|
||
"name": "h3c-live-1",
|
||
"host": "127.0.0.1",
|
||
"port": 8830,
|
||
"username": "netconf_user",
|
||
"password": "NASPLab123!",
|
||
"enabled": true,
|
||
"supports_xpath": false
|
||
}' \
|
||
http://127.0.0.1:19100/api/v1/devices
|
||
```
|
||
|
||
预期返回（示例）：
|
||
|
||
```json
|
||
{
|
||
"name": "h3c-live-1",
|
||
"host": "127.0.0.1",
|
||
"port": 8830,
|
||
"enabled": true,
|
||
"scrape_interval_seconds": null,
|
||
"supports_xpath": false,
|
||
"source": "runtime"
|
||
}
|
||
```
|
||
|
||
可以再通过：
|
||
|
||
```bash
|
||
curl -s -H "X-API-Token: changeme" http://127.0.0.1:19100/api/v1/devices
|
||
```
|
||
|
||
确认设备已注册（包含 `source: "runtime"`）。
|
||
|
||
---
|
||
|
||
## 7. 通过 curl 获取 Prometheus 指标
|
||
|
||
Scraper 线程会按 `global.scrape_interval_seconds` 周期性访问所有启用的设备，通过 NETCONF `<get>` 拉取 transceiver/channel 数据，并写入内存缓存。
|
||
|
||
等待一到两个采集周期（例如配置为 5 秒，则等待 10 秒左右）后，可用 curl 获取指标：
|
||
|
||
```bash
|
||
curl -s http://127.0.0.1:19100/metrics | head -n 40
|
||
```
|
||
|
||
或聚焦某些关键指标：
|
||
|
||
```bash
|
||
# 健康状态
|
||
curl -s http://127.0.0.1:19100/metrics | grep netconf_scrape
|
||
|
||
# Transceiver 级指标
|
||
curl -s http://127.0.0.1:19100/metrics | grep '^transceiver_'
|
||
|
||
# Channel 级指标
|
||
curl -s http://127.0.0.1:19100/metrics | grep '^transceiver_channel_'
|
||
```
|
||
|
||
典型输出示例（部分）：
|
||
|
||
```text
|
||
netconf_scrape_success{device="h3c-live-1"} 1
|
||
netconf_scrape_duration_seconds{device="h3c-live-1"} 0.532
|
||
|
||
transceiver_channel_rx_power_dbm{device="h3c-live-1",port="1/0/1",channel="1/0/1:1",component_name="63.TwoHundredGigE1/0/1:1"} -3.53
|
||
transceiver_channel_tx_power_dbm{device="h3c-live-1",port="1/0/1",channel="1/0/1:1",component_name="63.TwoHundredGigE1/0/1:1"} 2.09
|
||
...
|
||
```
|
||
|
||
如果 `netconf_scrape_success=0` 且 `netconf_scrape_errors_total{error_type="TimeoutError"}` > 0，说明采集超时或失败，可通过 exporter 日志进一步排查（`exporter.scraper` logger 会输出具体异常堆栈）。
|
||
|
||
---
|
||
|
||
## 8. 删除 runtime 设备
|
||
|
||
若需删除通过 API 注册的 H3C 设备：
|
||
|
||
```bash
|
||
curl -s -X DELETE \
|
||
-H "X-API-Token: changeme" \
|
||
http://127.0.0.1:19100/api/v1/devices/h3c-live-1
|
||
```
|
||
|
||
再次列出设备即不再看到 `h3c-live-1`。静态设备（来自 config.yaml `devices:`）无法通过 API 删除。
|
||
|
||
---
|
||
|
||
## 9. 关停 Exporter
|
||
|
||
在运行 `exporter.main` 的终端中按 `Ctrl+C`：
|
||
|
||
- Uvicorn 会打印 `Shutting down` / `Application shutdown complete`；
|
||
- Scraper 线程会收到终止信号，尝试在 `shutdown_timeout_seconds` 内退出；
|
||
- 所有 NETCONF 会话会发送 `<close-session>` 并关闭；
|
||
- `KeyboardInterrupt` 会被捕获，退出不会打印 Python traceback。
|
||
|
||
Exporter 本身不持久化运行时状态，只有：
|
||
|
||
- `config.yaml`：静态全局配置 + 静态设备；
|
||
- `devices.db`：运行时注册的设备列表（已加密的密码）。
|
||
|
||
因此重启 Exporter 不会影响 H3C 设备，只会重新加载配置并恢复运行时设备列表。
|
||
|