89d5e27874
* 实现周期采集、快照缓存、本地 HTTP API 和主动上报 * 补齐 Linux 和 Windows 主机、网络、资源、进程和 TCP 采集 * 添加服务生命周期管理、配置加载、构建脚本和测试覆盖 BREAKING CHANGE: network.ips 拆分为 network.ipv4s 和 network.ipv6s。
78 lines
4.5 KiB
Markdown
78 lines
4.5 KiB
Markdown
# MFD Monitor Agent Completion Design
|
|
|
|
## Objective
|
|
|
|
Bring the current Go single-binary host monitoring agent into alignment with `AGENTS.md`: complete missing host status behavior, preserve cached snapshots, support Linux and Windows service lifecycle, add reporter retry/backoff, improve partial-success handling, and raise comments/tests to the repository standard.
|
|
|
|
## Current Gaps
|
|
|
|
- Package-level Go types, functions, methods, and interfaces are mostly undocumented.
|
|
- Linux collection misses CPU usage percent, process start time, and process CPU percent.
|
|
- TCP listener mapping does not clearly report permission-related partial mappings.
|
|
- Windows collector and service runtime are incomplete; current service install only shells out to `sc.exe`.
|
|
- Linux service install does not explicitly require root and does not preserve `-config` in the systemd unit.
|
|
- Reporter logs failures but has no retry or bounded backoff.
|
|
- Tests do not cover enough collector parsing, partial/error statuses, service guards, reporter retry, or HTTP edge cases.
|
|
|
|
## Architecture
|
|
|
|
Keep the existing single-process architecture and package boundaries:
|
|
|
|
- `cmd/agent`: CLI and process lifecycle.
|
|
- `config`: defaults, JSON file loading, environment overrides.
|
|
- `collector`: platform collection into `status.HostStatus`.
|
|
- `snapshot`: collector aggregation and in-memory cache.
|
|
- `httpapi`: `GET /health` and `GET /status`, cache reads only.
|
|
- `reporter`: periodic POST of the cached `HostStatus`.
|
|
- `service`: Windows/Linux service install, uninstall, start, and stop.
|
|
|
|
No historical storage, pagination, auth, UDP collection, thread lists, process handles, or trend analysis are included.
|
|
|
|
## Behavior Design
|
|
|
|
Collection remains immediate-on-start and periodic afterward. HTTP and reporter paths both read the same cached snapshot and never trigger a live scan.
|
|
|
|
Each collector writes only its own section. If one collector fails, `snapshot.Cache` records a `StatusError`, marks `agent.snapshot_status` as `partial`, and keeps successful sections.
|
|
|
|
Linux should be the first complete collection implementation:
|
|
|
|
- CPU usage percent from `/proc/stat` with a bounded sample and context cancellation.
|
|
- Process start time from `/proc/<pid>/stat`.
|
|
- Process CPU percent best-effort; if exact calculation is unavailable, keep the field stable and do not fail the process collector.
|
|
- TCP listeners from `/proc/net/tcp`, `/proc/net/tcp6`, and `/proc/<pid>/fd`; unreadable process fd data should degrade listener status to `partial`.
|
|
|
|
Windows should expose a real service runtime path without NSSM. If full Windows metric collection would require a larger dependency decision, platform files should keep unsupported subsections explicit with `partial`/`error` statuses and tests around those contracts.
|
|
|
|
## Service Design
|
|
|
|
Linux install should require root before writing `/etc/systemd/system`, render a systemd unit for the configured service name, include `agent run`, preserve `-config <path>` when supplied, run `daemon-reload`, and enable the service. Errors should include the failed operation.
|
|
|
|
Windows install/start/stop/uninstall should remain behind Windows build tags and avoid NSSM. Administrator requirements should be checked where practical.
|
|
|
|
## Reporter Design
|
|
|
|
Reporter POST payload remains exactly the `HostStatus` JSON used by `/status`. Failed reports are logged and retried once after a short delay or handled with a simple bounded backoff. Retry/backoff must respect context cancellation and never terminate the process or block the local HTTP server.
|
|
|
|
## Comments And Tests
|
|
|
|
All Go package-level types, structs, interfaces, functions, and methods need concise comments. Comments should explain behavior, side effects, units, platform assumptions, and permission-sensitive degradation.
|
|
|
|
Tests should be written before behavior changes and cover:
|
|
|
|
- Linux parser helpers for CPU, memory, process stat/status, and TCP listeners.
|
|
- Snapshot partial aggregation and timeout behavior.
|
|
- HTTP not-ready and method-not-allowed behavior.
|
|
- Reporter HTTP errors, retry/backoff, payload structure, and cancellation.
|
|
- Linux service unit rendering, root guard, and config path propagation.
|
|
- Windows build-tagged service contracts where compile-testable.
|
|
|
|
## Verification
|
|
|
|
Completion requires:
|
|
|
|
- `go test ./...` passes.
|
|
- Current Linux build passes.
|
|
- `GOOS=windows GOARCH=amd64 go test ./...` is attempted and either passes or any blocker is documented with the exact failure.
|
|
- A final audit maps each `AGENTS.md` requirement touched by this pass to code, tests, or a documented remaining platform limitation.
|
|
|