spec run server metric reporting

2026-08-10 18:57:07 +08:00
parent bd444f04b9
commit 89eaf1e3c6
5 changed files with 114 additions and 0 deletions
@@ -0,0 +1,2 @@
 schema: spec-driven
 created: 2026-08-10
@@ -0,0 +1,38 @@
 ## Context
 Platform already stores signed metric batches and explicitly marks a server as `run-metrics-pending` only until its generated Run reports a sample. Run has the protocol client method but no collector or caller, even when an autonomous lifecycle has started a managed process.
 ## Goals / Non-Goals
 **Goals:**
 - Report an immediate sample after the autonomous lifecycle and a refreshed sample after accepted heartbeats.
 - Use only supervised-process state for online status and generic local resource measurements for utilization fields.
 - Keep request timeouts bounded and failures non-fatal.
 **Non-Goals:**
 - Infer player count, max players, TPS, latency, or any SCUM-specific semantics.
 - Make platform lifecycle projections authoritative for process state.
 - Add a metric spool, alter the platform metrics route, or expose local filesystem paths.
 ## Decisions
 - The worker owns reporting because it owns the active registration session and calls the existing signed metric endpoint. A sample is sent once registration, reconciliation, and autonomous startup have completed, then after each successful heartbeat.
 - Online is `true` only if a persisted managed process matching the generated Run's endpoint and server is still `running` according to its supervisor. If no matching process exists or it has exited, Run reports `online=false`; it never derives this fact from the platform's stale projection.
 - A platform-independent collector reads generic host CPU, memory, and the filesystem containing the Run workspace. Collector failures omit the affected optional field rather than failing the sample. The values use percentages in the existing protocol fields.
 - Each request uses a short timeout. Errors are logged as degraded reporting and the main worker continues; the next heartbeat retries with a fresh sample. This preserves the control/jobs/logs/artifacts channel boundaries.
 ## Risks / Trade-offs
 - [Host APIs vary by OS] → isolate collection behind a runtime collector and test it with a deterministic fake; unavailable fields remain omitted.
 - [Run restart loses a prior sample] → report immediately after autonomous bootstrap and on every heartbeat; platform already retains accepted observations.
 - [A stale process record] → ask the supervisor for current status before deriving online state.
 ## Migration Plan
 No persistence migration is needed. Existing deployed Runs continue showing pending until replaced; new Runs report on their first successful registration/startup cycle. Rolling back simply stops new samples while existing platform history remains valid.
 ## Open Questions
 - None.
@@ -0,0 +1,25 @@
 ## Why
 Generated Run packages register and supervise their server process, but never submit a metric sample. The platform consequently has no observed metrics and correctly renders every such server as waiting for Run reporting.
 ## What Changes
 - Add Run-side periodic metric reporting for its bound server instance after registration.
 - Derive online state only from Run's generic supervised-process records; report no game-specific player, TPS, or latency values.
 - Include bounded host CPU, memory, and workspace-volume usage when the operating system collector can observe them, without exposing paths or credentials.
 - Keep metric delivery on an independent, bounded reporting path so failed metric uploads do not block control, lifecycle jobs, logs, or artifacts.
 ## Capabilities
 ### New Capabilities
 - `run-server-metrics`: Generic server-process and host-resource metric collection and Run-to-platform reporting.
 ### Modified Capabilities
 - None.
 ## Impact
 - Affects the independent `run/` runtime worker, its platform client contract implementation, and Run tests.
 - Uses the existing signed `POST /api/v1/run/metrics/batches` platform route; no browser or game-plugin contract changes are required.
@@ -0,0 +1,38 @@
 ## ADDED Requirements
 ### Requirement: Run reports supervised server observations
 A generated Run package SHALL submit a signed metric sample for its bound server instance after it has registered and completed autonomous lifecycle startup, and after each successful heartbeat. The sample's online field SHALL be derived from the current state of Run's matching supervised process, not from a platform lifecycle projection.
 #### Scenario: Managed server process is running
 - **WHEN** the generated Run has a current matching supervised process in the `running` state
 - **THEN** it submits a metric sample with `online=true` for its bound server instance
 #### Scenario: Managed server process is absent or exited
 - **WHEN** the generated Run has no matching supervised process or its matching process is not running
 - **THEN** it submits a metric sample with `online=false` and does not claim the server is running
 ### Requirement: Run reports only generic local utilization
 Run SHALL populate optional utilization fields only from generic local host and workspace-volume observations. It SHALL omit unavailable observations and SHALL NOT synthesize game-specific player, TPS, or latency metrics.
 #### Scenario: Host resource collector is available
 - **WHEN** CPU, memory, or workspace-volume utilization can be observed locally
 - **THEN** the corresponding percentage fields are included in the sample without any host path or credential value
 #### Scenario: Host resource collector is unavailable
 - **WHEN** an optional local resource observation cannot be collected
 - **THEN** Run still reports the process observation and omits the unavailable field
 ### Requirement: Metric delivery remains bounded and independent
 Run SHALL use a bounded report request and SHALL treat a rejected or failed metric upload as degraded telemetry rather than a control, job, log, or artifact failure.
 #### Scenario: Metric endpoint is temporarily unavailable
 - **WHEN** an upload attempt fails or times out
 - **THEN** the worker continues its lifecycle and retry occurs through a later reporting cycle
@@ -0,0 +1,11 @@
 ## 1. Run metric reporting
 - [x] 1.1 Extend the Run worker's client boundary and reporting cycle for signed metric batch ingestion with its current registration session.
 - [x] 1.2 Add generic supervised-process online-state derivation and optional local host/workspace utilization collection.
 - [x] 1.3 Invoke bounded reporting after autonomous startup and successful heartbeats without coupling failure to control, job, log, or artifact loops.
 ## 2. Verification
 - [x] 2.1 Add deterministic runtime coverage for session-scoped requests, running/exited process state, optional collector failures, and degraded upload behavior.
 - [x] 2.2 Run `go test ./...` in `run/`, `scripts/check-structure.sh`, and `openspec validate report-run-server-metrics --strict`.
 - [ ] 2.3 Build the Windows Run package, deploy it to the configured Qinghuo server, and confirm the platform receives a non-pending metric observation.