监控与日志
TMQTT 内置完善的监控和日志系统，帮助你实时了解 Broker 运行状态、排查问题和设置告警。
Prometheus 指标
TMQTT 默认在 9090 端口暴露 Prometheus Exporter 接口，开箱即用，无需额外配置。
采集方式
在 Prometheus 配置文件中添加 TMQTT 节点作为 scrape target：
yaml
scrape_configs:
- job_name: 'tmqtt'
static_configs:
- targets: ['tmqtt-host:9090']核心指标
| 指标名称 | 类型 | 说明 |
|---|---|---|
tmqtt_connections_total | Gauge | 当前连接总数 |
tmqtt_connections_active | Gauge | 活跃连接数 |
tmqtt_messages_received_total | Counter | 累计接收消息数 |
tmqtt_messages_sent_total | Counter | 累计发送消息数 |
tmqtt_messages_dropped_total | Counter | 丢弃的消息数（如队列满时） |
tmqtt_subscribe_total | Counter | 累计订阅次数 |
tmqtt_unsubscribe_total | Counter | 累计取消订阅次数 |
tmqtt_auth_success_total | Counter | 认证成功次数 |
tmqtt_auth_failure_total | Counter | 认证失败次数 |
tmqtt_bridge_sink_sent_total | Counter | 桥接 Sink 成功发送消息数（按 Sink 名分维度） |
tmqtt_bridge_sink_failed_total | Counter | 桥接 Sink 发送失败消息数 |
tmqtt_bridge_dlq_total | Counter | 进入死信队列的消息数 |
Grafana 可视化
配合 Grafana 的 Prometheus 数据源，可以快速搭建监控仪表盘。常用面板：
- 连接数变化趋势
- 消息吞吐率（messages_received_total 的 rate）
- 认证失败率（auth_failure_total 的 rate，可检测攻击）
- 桥接 Sink 健康度（sent vs failed 对比）
系统主题（$SYS/）
TMQTT 定期将运行状态发布到 $SYS/ 前缀的主题上。客户端订阅 $SYS/# 即可实时获取以下信息：
| 主题 | 内容 |
|---|---|
$SYS/broker/version | Broker 版本号 |
$SYS/broker/uptime | 运行时间（秒） |
$SYS/broker/clients/total | 总连接数 |
$SYS/broker/clients/connected | 当前活跃连接数 |
$SYS/broker/messages/received | 累计接收消息数 |
$SYS/broker/messages/sent | 累计发送消息数 |
$SYS/broker/messages/dropped | 丢弃的消息数 |
发布间隔：默认每 60 秒更新一次。
提示：
$SYS/主题属于特殊内部主题，客户端只能订阅，不能发布。
日志配置
日志级别
| 级别 | 输出内容 | 使用场景 |
|---|---|---|
error | 仅错误信息 | 生产环境，减少日志量 |
warn | 错误和警告 | 关注异常但不需要详细信息 |
info | 运行状态信息（默认） | 生产环境推荐 |
debug | 详细调试信息 | 开发和问题排查 |
trace | 最详细的信息，包括每条消息流转 | 仅在排查疑难问题时临时使用 |
日志格式
| 格式 | 说明 | 使用场景 |
|---|---|---|
text | 人类可读的文本格式（默认） | 直接查看、调试 |
json | JSON 结构化格式 | 日志采集系统（如 ELK、Loki） |
运行时调整日志级别
无需重启，通过热重载即可修改日志级别：
- 修改
config.toml中的log.level - TMQTT 自动检测文件变更并应用
慢消费者监控
当客户端接收消息速度明显落后于发送速度时，TMQTT 的慢消费者检测机制会自动介入：
- 发送队列容量占比超过阈值（默认 80%）时记录告警日志
- 持续超过设定时间（默认 30 秒）后自动断开该客户端连接，防止拖累整体性能
- 断开事件会记录在日志中，可通过日志或管理 API 查看
健康检查
/healthz 接口无需鉴权，返回简单的 HTTP 200 响应，适合用于负载均衡器或 Kubernetes 的健康探针：
bash
curl http://localhost:8080/healthz
# 响应：HTTP 200 OKCopyright (c) 2026 桃子 TaoZi.Pub https://taozi.pub | MIT License