Metrics Engine Service

The Metrics Engine (started with webstream.exe -me) is the deployment's central telemetry sink. Every streamer, gateway, and backend POSTs metrics and activity to it; it is the sole writer of the metrics and activity databases, runs retention and rollup maintenance, and serves the query API that powers the Operations and Reports sections of the admin console — plus usage metering for billing.

Function

Metrics ingestion. Receives aggregated performance flushes (FPS, latency, CPU, bandwidth, session context) from every node and writes them to the webstream_metrics database.
Activity logging. Buffers and persists the user activity audit trail — session lifecycle, file operations, clipboard, print, and batched input blocks — into the webstream_activity database. Producers stay database-free; a future database change never touches the streamers.
Retention and rollups. An hourly maintenance timer prunes raw metrics past retentionDays and maintains hourly/daily rollups for long-term trends.
Query API. Serves nodes, sessions, activity, and metering reports to the admin console (directly, or via the gateway's /mcp/api/* proxy for the Ops MCP server).
Usage metering. Slices session usage into 15-minute billing records, rolls them up hourly, and submits them to the configured billing provider (AWS Marketplace, CSV, or native).

Ports and endpoints

Listener	Port	Purpose
HTTP	`metricsEngine.httpPort` (default 9009), bound to `bindAddress` (default `0.0.0.0`)	Ingestion, query API, admin panel. Internal service — no SSL, no API keys; secured by network isolation.

Message contracts

Inbound — ingestion (from streamers, gateways, backends)

Endpoint	Method	Frequency	Payload
`/metrics/streamer/flush`	POST	Every 10/30/60 s per node (`metrics.server.flushIntervalSeconds` on the producer)	`{ nodeId, hostName, environment, region, userName, sessionId, tsUtc, intervalSecs, summary{…}, events[], instanceType, processorCount, totalMemoryGB, sessionContext? }`
`/activity/log`	POST	Immediate for session/file/clipboard/print events; 10 s batches for input blocks	`{ type, nodeId, sessionId, username, timestamp, iamUsername?, workspaceName?, data }`

Inbound — query API (admin console and MCP proxy)

Endpoint	Method	Purpose
`/api/nodes`, `/api/nodes/{id}/metrics`, `/api/nodes/{id}/latest`	GET	Registered node list and per-node time series / latest snapshot.
`/api/sessions/active`, `/api/sessions/recent`, `/api/sessions/{id}/metrics`	GET	Live and historical session data for Operations.
`/api/sessions/{id}/disconnect`	POST	Fans a termination request out to the session's streamer.
`/api/activity/sessions\|inputs\|clipboard\|report`	GET	Audit and compliance reporting.
`/api/metering/usage-report`, `/metering/meterUsage`, `/metering/status`	GET / POST	Billing usage reports and metering submission.
`/health`	GET	`{ status: "ok", timestamp, retentionDays }`

When accessed through the gateway, these routes are exposed as /mcp/api/* and require a valid X-MCP-Key header; the Metrics Engine itself does not enforce keys.

Configuration

Property	Purpose
`metricsEngine.httpPort / bindAddress`	Listener settings (default 9009 on all interfaces).
`metricsEngine.database.metrics / activity`	PostgreSQL connection strings (+ `passwordRef`) for the two databases it owns. See Persistence Layer.
`metricsEngine.database.retentionDays`	Raw metrics retention (default 10 days).
`metricsEngine.database.rollupEnabled`	Hourly/daily rollups for long-term trends.
`metricsEngine.adminPanel`	Admin panel enable, default time range, refresh interval.

Command-line overrides are available when launching with -me: --http-port, --metrics-conn, --activity-conn, --retention-days, --admin-enabled.

Aligned settings on peer services (the producers)

Every node's metrics section: enabled = true, mode = server, and server.baseUrl pointing at this service. flushIntervalSeconds (10/30/60) sets the ingestion cadence per node.
Every node's activityLogging section: serverUrl pointing here, with batchIntervalSeconds (default 10) controlling input batching.
The gateway's /mcp/api/* proxy assumes this service at http://localhost:9009 (or the configured URL) and gates access with <mcpApiKeys>.
nodeInfo.nodeId on producers (auto-generated as {hostname}-Streamer if empty) is the key the Metrics Engine registers each node under.

Sizing

The Metrics Engine is deliberately lightweight — ingestion is buffered and writes are batched — but as node and session counts grow it should move to its own small instance so telemetry writes never compete with session I/O. See Services for shared-versus-dedicated guidance.