遥测插件
telemetry 插件收集设备指标（CPU、内存、磁盘、网络、运行时），并通过 Prometheus 提供查询。指标采集按租户配置，通过 shadow/config 系统热推送到设备——无需重启设备。
概览
| 属性 | 值 |
|---|---|
| 插件 ID | telemetry |
| 类型 | SDK（pluginsdk.BackendPlugin） |
| 版本 | 1.0.0 |
| HTTP 路由 | 无 |
| Prometheus 指标 | 是——暴露设备指标供抓取 |
| 总线订阅 | evt.telemetry.v1.* |
| 数据库架构 | 无 |
RBAC 权限
| 权限 | 默认角色 | 说明 |
|---|---|---|
telemetry/metrics:read | viewer、operator、tenant_admin | 通过 Prometheus 代理查询设备遥测数据 |
要从 Web UI 访问遥测数据，用户需要 telemetry/metrics:read 权限。该权限用于保护调用 /api/v1/metrics/* 的监控仪表板。
typescript
can(perms, 'telemetry/metrics', 'read') // 显示监控仪表板消息总线
订阅主题
遥测插件订阅通配符主题 evt.telemetry.v1.*，接收设备代理发布的所有遥测事件。
发布主题
| 主题 | 触发时机 | 载荷 | 说明 |
|---|---|---|---|
device/{id}/cmd.telemetry.v1.ping_ack | 心跳 | {timestamp} | 确认设备遥测心跳 |
device/{id}/cfg.plugins.v1.set | 配置变更 | {plugin_id, config} | 将更新后的遥测配置推送到设备代理 |
遥测数据格式
设备代理在总线上发布结构化遥测报告：
json
{
"device_id": "550e8400-e29b-41d4-a716-446655440000",
"tenant_id": "660f9511-...",
"timestamp": "2025-03-25T10:00:00Z",
"metrics": [
{ "name": "cpu_usage_percent", "value": 23.5, "labels": {} },
{ "name": "memory_used_bytes", "value": 536870912, "labels": {} },
{ "name": "disk_used_bytes", "value": 1073741824, "labels": { "mount": "/" } },
{ "name": "net_rx_bytes_total", "value": 98765432, "labels": { "iface": "eth0" } },
{ "name": "net_tx_bytes_total", "value": 12345678, "labels": { "iface": "eth0" } }
]
}服务端插件接收这些报告后，通过 MetricsRegistry 能力将其写入 Prometheus，并自动为每个指标附加 device_id 和 tenant_id 标签。
可用设备指标
| 指标名称 | 单位 | 说明 |
|---|---|---|
cpu_usage_percent | % | CPU 总体利用率 |
memory_used_bytes | bytes | RSS / 已用内存 |
memory_total_bytes | bytes | 物理内存总量 |
disk_used_bytes | bytes | 已用磁盘空间（按挂载点） |
disk_total_bytes | bytes | 磁盘容量（按挂载点） |
net_rx_bytes_total | bytes（计数器） | 接收字节数（按网络接口） |
net_tx_bytes_total | bytes（计数器） | 发送字节数（按网络接口） |
runtime_uptime_seconds | seconds | 代理/设备运行时间 |
device_id 和 tenant_id 标签由服务端插件自动附加到每个指标上。
插件配置
配置通过 SetPluginConfig / GetPluginConfig 按租户存储。
| 键 | 类型 | 默认值 | 说明 |
|---|---|---|---|
interval_seconds | int | 30 | 设备代理采集并上报指标的频率（秒） |
metrics | string[] | ["cpu","memory","disk","network","runtime"] | 要采集的指标组 |
租户配置示例：
json
{
"interval_seconds": 60,
"metrics": ["cpu", "memory", "disk"]
}配置变更通过 cfg.plugins.v1.set 总线消息推送到设备——无需重启代理。
查询遥测数据
使用 ConnectRPC QueryDeviceTelemetry RPC 或 Prometheus 代理：
通过 ConnectRPC
http
POST /umoo.v1.admin.AdminService/QueryDeviceTelemetry
Authorization: Bearer <token>
X-Tenant-ID: <tenant-id>
Content-Type: application/json
{
"device_id": "550e8400-...",
"metric": "cpu_usage_percent",
"start": "2025-03-25T00:00:00Z",
"end": "2025-03-25T12:00:00Z",
"step": "5m"
}所需权限：telemetry/metrics:read
通过 Prometheus 代理
http
GET /api/v1/metrics/api/v1/query_range
?query=cpu_usage_percent{device_id="550e8400-..."}
&start=2025-03-25T00:00:00Z
&end=2025-03-25T12:00:00Z
&step=300
Authorization: Bearer <token>所需权限：metrics:read
设备端插件
设备代理运行对应的 telemetry 代理插件，负责：
- 从本地插件配置存储中读取
interval_seconds和metrics配置。 - 按配置间隔采样各指标组。
- 在代理总线上将报告发布为
evt.telemetry.v1.report，通过 NATS 桥接传输至服务端。 - 监听
cfg.plugins.v1.set消息以热重载配置。