[devmittal02]

Closes #183.

What

Adds an opt-in metricsListen controller setting. When set, the controller serves GET /metrics (Prometheus text format) on that address. Unset (the default) changes nothing.

metricsListen: 0.0.0.0:9090

Why

Fleet health is only visible through the management UI today. adminListen must stay on loopback, so a scraper cannot reach it. Operators running a metrics stack (Prometheus, Grafana Alloy, and similar) have no way to alert on stale devices, failed configuration applies, or devices lagging behind the active configuration revision. The usage reporting from #160 covers tokens and cost, not fleet health.

Metrics

Metric	Type
agentdesktop_build_info{version}	gauge
agentdesktop_devices	gauge
agentdesktop_devices_online	gauge (seen in last 90s, same threshold as the UI overview)
agentdesktop_devices_connected	gauge (open streams on this replica)
agentdesktop_device_oldest_seen_age_seconds	gauge
agentdesktop_devices_by_version{os,agent_version}	gauge
agentdesktop_devices_by_config_state{state}	gauge (applied, failed, unreported)
agentdesktop_devices_config_behind	gauge
agentdesktop_config_active_revision	gauge
agentdesktop_inventory_mcp_servers	gauge
agentdesktop_inventory_skills	gauge
agentdesktop_telemetry_events_total{type}	counter
agentdesktop_device_message_errors_total	counter

Fleet state is read from the database at scrape time, so it is correct after a restart. The connected gauge and the two counters are in memory and start from zero on restart, as Prometheus counters do. With several replicas those are per replica and should be summed.

Privacy

Label values come from closed sets, or from the OS and agent version of enrolled devices. Hostnames, users, device IDs, MCP server names, and tool inputs are never exported. scrape_reports_fleet_state_without_identifying_labels asserts that.

Design notes

• A separate listener instead of a route on the admin server, because the admin listener is required to be loopback and has no authentication of its own.
• The endpoint is unauthenticated, like most exporters. The config comment and README say to expose it only to the scraper.
• insert_telemetry now returns the stored event type so the counter uses the same value that is persisted.
• No new dependencies. The text format is written by hand, since the output is small and fixed.

Testing

• cargo test -p agentdesktop-core -p agentdesktop-controller passes, including a scrape test against a SQLite database and a config test for the new field.
• cargo clippy -p agentdesktop-controller -p agentdesktop-core --all-targets -- -D warnings and cargo fmt --all --check are clean.
• I did not build the desktop app crate, which needs its own frontend build and is not touched here.
• Not tested: an end-to-end scrape against a running controller with real devices.

Draft while I get feedback on the metric names and on whether you would rather expose this through an OpenTelemetry exporter.

🤖 Generated with Claude Code

[devmittal02]

@peterj could you take a look when you have a moment? This is the implementation for #183. It is still a draft, mainly to get your view on the metric names, the separate metricsListen listener, and the open questions listed in the issue. Thanks!

[peterj]

Ideally I'd like Krisztian Fekete to chime in here too -- I did ping him and he'll take a look once he's back.

[Copilot]

🔵 Needs a closer look

Listener security and replica semantics still await maintainer review, and the connection gauge has an unresolved lifecycle defect.

1 open issue

• Keep connection guard alive until response stream closes · New

What changed in this PR

Adds opt-in Prometheus fleet-health metrics to the controller, complementing the existing token and cost reporting.

Changes:

• Adds a separate, unauthenticated /metrics listener configured through metricsListen.
• Exposes database-backed fleet gauges and in-memory connection, telemetry, and error metrics.
• Documents endpoint security and replica behavior, with configuration and metrics tests.

File	Description
schema/​controller-config.md	Documents the optional metrics listener.
schema/​controller-config.json	Adds the metrics listener to the configuration schema.
README.md	Documents metrics, access restrictions, and replica behavior.
crates/​core/​src/​config.rs	Adds metricsListen and configuration tests.
crates/​controller/​src/​service.rs	Instruments connections, telemetry storage, and message errors.
crates/​controller/​src/​metrics.rs	Implements the exporter, counters, gauges, and tests.
crates/​controller/​src/​main.rs	Wires shared metrics and starts the optional listener.
crates/​controller/​src/​lib.rs	Exports the metrics module.
crates/​controller/​src/​database.rs	Adds inventory totals and returns stored telemetry types.

_{Review effort: Balanced}