# 监控

通过 WebSocket 通道、Prometheus 指标和健康检查进行实时监控。

## 前提条件

- FluxiQ PIX 后端运行中，`NATS_ENABLED=true`
- 管理门户访问权限（用于 WebSocket 仪表板）
- Prometheus 已配置用于指标抓取（可选）

## WebSocket 监控

管理门户通过 `/socket` 上的 WebSocket 连接到 6 个 Phoenix Channel 主题：

| 通道 | 主题 | 数据 |
|------|------|------|
| 交易 | `transactions:live` | 实时交易流（状态变更、新支付） |
| 系统健康 | `system:health` | 服务状态、DB、Redis、NATS 健康 |
| 清算 | `settlement:status` | 清算周期进度和结果 |
| DICT 操作 | `dict:operations` | 密钥查询、认领、CID 同步事件 |
| BACEN 通道 | `bacen:channels` | CPM/CSM 通道健康和故障转移事件 |
| 队列深度 | `queues:depth` | 每个流的 NATS 消费者延迟 |

### WebSocket 认证

Socket 连接需要有效的 JWT token：

```javascript
import { Socket } from "phoenix"

const socket = new Socket("/socket", {
  params: { token: jwtToken }
})
socket.connect()

const channel = socket.channel("transactions:live")
channel.join()
channel.on("new_transaction", (payload) => { ... })
```

## 健康检查

### 端点

| 端点 | 端口 | 检查项 |
|------|------|--------|
| `GET /health` | 4003 | Settlement 服务 + DB + Redis + NATS |
| `GET /api/health` | 4001 | Dict 服务健康 |
| `GET /api/health` | 4002 | SPI 服务健康 |
| `GET /metrics` | 4003 | Prometheus 指标 |

### HealthChecker GenServer

`SettlementService.Monitoring.HealthChecker` 运行定期检查：

- **每 10 秒**：服务健康（Dict、SPI、Settlement）、DB 连接、Redis ping、NATS 进程存活
- **每 30 秒**：BACEN 通道健康（CPM/CSM）
- 状态转换日志：`healthy -> degraded -> down`

### QueueMonitor GenServer

`SettlementService.Monitoring.QueueMonitor` 每 15 秒轮询 NATS 消费者延迟。

## Prometheus 指标

`/metrics` 端点暴露基于 Telemetry 的指标：

### 请求指标

| 指标 | 类型 | 标签 |
|------|------|------|
| `phoenix_http_request_duration_ms` | Histogram | method, route, status |
| `phoenix_http_request_count` | Counter | method, route, status |

### 数据库指标

| 指标 | 类型 | 描述 |
|------|------|------|
| `ecto_query_duration_ms` | Histogram | 查询执行时间 |
| `ecto_pool_size` | Gauge | 连接池大小 |
| `ecto_pool_available` | Gauge | 可用连接数 |

### Worker 指标

| 指标 | 类型 | 标签 |
|------|------|------|
| `pix_worker_message_processed_duration_ms` | Histogram | worker, subject, status |
| `pix_worker_batch_completed_count` | Counter | worker |
| `pix_worker_poll_interval_ms` | Gauge | worker, batch_size |

### 断路器指标

| 指标 | 类型 | 标签 |
|------|------|------|
| `pix_circuit_breaker_state_change` | Counter | name, from, to |
| `pix_circuit_breaker_request` | Counter | name, result |

## 监控仪表板

管理门户包含 6 面板实时仪表板：

1. **TPS 图表**：带迷你折线图的每秒交易数
2. **状态分布**：交易状态柱状图
3. **系统健康**：服务状态指示器（绿/黄/红）
4. **清算**：当前周期进度
5. **队列深度**：每个流的 NATS 消费者延迟
6. **BACEN 通道**：CPM/CSM 健康状态

## 告警

### 推荐告警规则

| 告警 | 条件 | 严重性 |
|------|------|--------|
| 服务宕机 | 健康检查连续失败 3 次 | 严重 |
| 高延迟 | p99 > 2000ms | 高 |
| 队列积压 | 消费者延迟 > 10,000 | 高 |
| 断路器打开 | 断路器打开 | 高 |
| DB 连接池耗尽 | 可用连接 = 0 | 严重 |
| BACEN 通道宕机 | CPM 或 CSM 宕机 | 严重 |
| 速率限制飙升 | 每分钟 > 100 个 429 | 中 |

## 预期结果

配置监控后：

- WebSocket 仪表板跨 6 个通道显示实时数据
- Prometheus 按配置间隔抓取指标
- 健康检查每 10-30 秒运行
- 告警规则在关键条件下触发