Telemetry Plugin

The telemetry plugin collects device metrics (CPU, memory, disk, network, runtime) and makes them queryable via Prometheus. Metric collection is configured per-tenant and hot-applied to devices via the shadow/config system — no device restart required.

---

Overview

Property	Value
Plugin ID	telemetry
Tier	SDK (pluginsdk.BackendPlugin)
Version	1.0.0
HTTP routes	None
Prometheus metrics	Yes — device metrics exposed for scraping
Bus subscriptions	evt.telemetry.v1.*
DB schema	None

---

RBAC Permissions

Permission	Default roles	Description
telemetry/metrics:read	viewer, operator, tenant_admin	Query device telemetry via the Prometheus proxy

To access telemetry from the Web UI, the user needs telemetry/metrics:read. This gates the monitoring dashboards that call through /api/v1/metrics/*.

can(perms, 'telemetry/metrics', 'read')   // show monitoring dashboards

---

Message Bus

Subscriptions

The telemetry plugin subscribes to the wildcard topic evt.telemetry.v1.* to receive all telemetry events published by device agents.

Published Topics

Topic	Trigger	Payload	Description
device/{id}/cmd.telemetry.v1.ping_ack	Heartbeat	{timestamp}	Acknowledge a device telemetry heartbeat
device/{id}/cfg.plugins.v1.set	Config change	{plugin_id, config}	Push updated telemetry config to the device agent

---

Telemetry Wire Format

Device agents publish telemetry reports as structured messages on the bus:

{
  "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" } }
  ]
}

The server-side plugin ingests these reports and writes them into Prometheus (via the MetricsRegistry capability) with a device_id and tenant_id label on each metric.

---

Available Device Metrics

Metric name	Unit	Description
cpu_usage_percent	%	Overall CPU utilization
memory_used_bytes	bytes	RSS / used memory
memory_total_bytes	bytes	Total physical memory
disk_used_bytes	bytes	Disk space used (per mount point)
disk_total_bytes	bytes	Disk capacity (per mount point)
net_rx_bytes_total	bytes (counter)	Bytes received (per interface)
net_tx_bytes_total	bytes (counter)	Bytes transmitted (per interface)
runtime_uptime_seconds	seconds	Agent/device uptime

Label device_id and tenant_id are attached to every metric automatically by the server-side plugin.

---

Plugin Configuration

Configuration is stored per-tenant using SetPluginConfig / GetPluginConfig.

Key	Type	Default	Description
interval_seconds	int	30	How often the device agent collects and reports metrics
metrics	string[]	["cpu","memory","disk","network","runtime"]	Which metric groups to collect

Example per-tenant config:

{
  "interval_seconds": 60,
  "metrics": ["cpu", "memory", "disk"]
}

Config changes are propagated to devices via cfg.plugins.v1.set bus messages — no agent restart needed.

---

Querying Telemetry

Use the ConnectRPC QueryDeviceTelemetry RPC or the Prometheus proxy:

Via ConnectRPC

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"
}

Required permission: telemetry/metrics:read

Via Prometheus Proxy

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>

Required permission: metrics:read

---

Agent-Side Plugin

The device agent runs a corresponding telemetry agent plugin that:

1. Reads the interval_seconds and metrics config from its local plugin config store.
2. On each interval, samples the configured metric groups.
3. Publishes the report as evt.telemetry.v1.report on the agent bus, which is bridged to the server via NATS.
4. Listens for cfg.plugins.v1.set messages to hot-reload its configuration.

---

See Also

• Monitoring Guide — dashboards and alerting setup
• Alerts Guide — Alertmanager integration
• Auth & RBAC — full permission model