63 lines
3.6 KiB
Markdown
63 lines
3.6 KiB
Markdown
## Context
|
|
|
|
The current frontend calls `/metrics/platform`, `/metrics/server-instances`, and `/server-instances/{id}/config`, but the backend router does not implement them. HomePage falls back to partial data or error states, and ServerDetailPage uses a hardcoded `server.properties` sample when config read fails.
|
|
|
|
This change is deliberately read-only. It creates the observability/config read surface needed by later config write, AI suggestion, and run execution changes without introducing file mutation or process orchestration.
|
|
|
|
## Goals / Non-Goals
|
|
|
|
**Goals:**
|
|
|
|
- Implement platform resource usage and per-server metrics API routes.
|
|
- Implement safe server config read route with role-scoped access.
|
|
- Keep response contracts bounded and free of secrets, host paths, direct sockets, and raw run credentials.
|
|
- Update frontend pages to consume real API data and demote local samples to explicit fallback.
|
|
- Add service/API/frontend tests and browser walkthrough evidence.
|
|
|
|
**Non-Goals:**
|
|
|
|
- No config write, file write, or diff approval routes.
|
|
- No external metrics collector or long-term metrics storage backend.
|
|
- No browser log tail, artifact transfer UI, or AI log analysis.
|
|
- No run worker changes beyond existing data sources.
|
|
|
|
## Decisions
|
|
|
|
### Decision 1: Keep metrics as platform-owned read models
|
|
|
|
The service will expose platform and server metrics through platform DTOs. Initial values may be derived from existing run endpoint/server/job metadata or stored in the in-memory repository, but callers see stable read contracts.
|
|
|
|
Alternative considered: let the frontend compute all metrics locally from server lists. Rejected because the console already has API client methods and future run workers need a platform-owned metrics surface.
|
|
|
|
### Decision 2: Server config read returns logical content only
|
|
|
|
The config read response returns server instance ID, config version, content, format/key metadata, and timestamps. It must not include host filesystem paths or run-local socket details.
|
|
|
|
Alternative considered: return a host path for browser editing. Rejected because run paths must not leak to platform_web or plugins.
|
|
|
|
### Decision 3: Role-scoped access applies to config and server metrics
|
|
|
|
Platform administrators can read all metrics/config. Server owners and administrators can read only their server instances. This reuses the existing bearer session and ACL behavior.
|
|
|
|
### Decision 4: Frontend fallback remains visibly non-production
|
|
|
|
Local sample config can remain only as an explicit fallback state for API-unavailable development/demo flows. Production rendering must prefer API data and show errors/empty states honestly.
|
|
|
|
## Risks / Trade-offs
|
|
|
|
- [Risk] Derived metrics can look less live than future run telemetry. Mitigation: expose source/timestamp fields and keep later real-time collectors as a separate change.
|
|
- [Risk] Config content may be stale relative to actual files until run worker integration exists. Mitigation: include config version and source metadata.
|
|
- [Risk] Server detail can still show fallback config if backend is unavailable. Mitigation: label fallback clearly and add tests that API success suppresses fallback.
|
|
|
|
## Migration Plan
|
|
|
|
1. Add metrics/config domain, DTO, validators, and service methods in `platform/`.
|
|
2. Add API handlers/routes and route documentation updates.
|
|
3. Update `platform_web` API types/views to render API metrics/config.
|
|
4. Add tests and browser walkthrough.
|
|
|
|
## Open Questions
|
|
|
|
- Whether future metrics persistence should be a repository table or a projection from run heartbeats/logs.
|
|
- Whether config format should start as plain text only or include structured sections after file dispatch is implemented.
|