Metrics Aggregation & Logging
Relevant source files
The following files were used as context for generating this wiki page:
Metrics Aggregation & Logging provides real-time and historical visibility into the network traffic, resource utilization, and operational status of the HX-ProxyGroup control plane and its managed data plane. The system collects data from the Mihomo data plane and the host operating system, aggregates these statistics in memory, and persists them to an SQLite database for long-term analysis.
The system serves three primary functions:
- Traffic Monitoring: Tracking upload/download rates and active connections for listeners, nodes, and residential channels.
- System Observation: Monitoring CPU, memory, and disk usage for the host and specific managed processes (
hx-proxygroupdandmihomo). - Real-time Streaming: Delivering live updates to the web interface via Server-Sent Events (SSE) for low-latency dashboards.
Architecture and Data Flow
The metrics system follows a decoupled architecture where data collection is separated from persistence and presentation. The metrics.Service acts as the central coordinator, orchestrating periodic collection from runtime sources and flushing aggregated results to the repository.
The control plane aggregates statistics in memory before performing batch writes to SQLite to minimize disk I/O overhead.
Sources: AGENTS.md:120-121, internal/metrics/service_test.go:49-60
Traffic Aggregation Logic
The service calculates traffic deltas by comparing consecutive snapshots of active connections. If a database flush fails, the service preserves pending counters and retries in the next cycle to ensure no data loss.
Sources: internal/metrics/service_test.go:27-46, internal/metrics/service_test.go:78-95
Traffic Metrics Components
Traffic metrics are tracked across different resource types, allowing users to analyze performance at various granularities.
| Resource Type | Description |
|---|---|
listener | Traffic entering the system through specific ports/protocols. |
node | Traffic routed through individual proxy servers (outbounds). |
residential_channel | Traffic specific to dynamic residential IP sessions. |
Sources: internal/metrics/service_test.go:102-103, internal/api/traffic_test.go:76-80, web/src/pages/overview-page.tsx:57-60
Data Models
The system utilizes specific structures for reporting traffic summaries and time-series data:
- TrafficSummary: Contains total
upload_bytes,download_bytes, and metadata for a specific resource. - OverviewSample: A point-in-time record containing global rates (e.g.,
upload_bytes_per_second) and a list of resource-specific metrics.
Sources: web/src/pages/overview-page.tsx:23-30, internal/api/overview.go:114-124
System Resource Monitoring
The system monitors host-level resources and specific受管进程 (managed processes). This monitoring is coarse-grained (typically 3s to 10s intervals) to ensure negligible overhead.
Monitored Metrics
- CPU: Total system usage percentage and core-specific counts.
- Memory: Total, used, and cached bytes.
- Disk: Filesystem usage, mount points, and available space.
- Network: Host-level
net_rx_bytes_per_secandnet_tx_bytes_per_sec. - Processes: Resource consumption specifically for
hx-proxygroupd(Control Plane) andmihomo(Data Plane).
Sources: web/src/components/host-resources.tsx:7-12, web/src/components/terminal/ops-page.tsx:10-15, web/src/components/terminal/host-monitor.tsx:79-84
Real-time Metrics Streaming
Real-time visibility is implemented using Server-Sent Events (SSE). This allows the frontend to receive updates as they are collected without polling overhead.
Overview Stream
The /api/v1/overview/stream endpoint provides a continuous flow of traffic samples. When a client connects, the server first sends a "history" event containing the last 120 samples, followed by "sample" events for every new collection cycle.
Terminal Host Monitor
A specialized SSE stream is used for the terminal interface, providing per-second updates of host metrics to emulate a "FinalShell-style" resource panel.
Sources: web/src/components/terminal/host-monitor.tsx:7-12
API Endpoints and Parameters
The Metrics API provides endpoints for querying both total summaries and historical time-series data.
| Endpoint | Method | Parameters | Description |
|---|---|---|---|
/api/v1/traffic | GET | resource_type, limit, from, to | Lists traffic summaries for resources. |
/api/v1/traffic | GET | resource_type, resource_id, max_points | Queries time-series data for a specific resource. |
/api/v1/system/resources | GET | - | Returns current host and process resource usage. |
/api/v1/system/disk | GET | - | Returns disk usage for all filesystems. |
Sources: internal/api/traffic_test.go:43-47, internal/api/traffic_test.go:94-98, web/src/components/terminal/ops-page.tsx:26-30
Query Constraints
To protect system performance, historical queries are subject to the following limits:
- Time Range: Maximum 30 days per query.
- Resolution: Maximum 500 data points per response.
- Resolution Logic: The system automatically chooses between 1-minute, 5-minute, and 1-hour resolutions based on the requested time span.
Sources: internal/metrics/service_test.go:193-200, internal/metrics/service_test.go:204-210
Logging and Operational Security
As a management control plane, HX-ProxyGroup enforces strict logging rules to prevent sensitive data leakage.
- Structured Logging: Logs are output in structured formats (e.g., for
journald). - Redaction: Logs must not contain
Authorizationheaders, cookies, subscription tokens, or node passwords. - API Error Redaction: Internal repository errors (e.g., SQLite specific details) are redacted before being returned to the API client to prevent information disclosure.
Sources: AGENTS.md:50-51, AGENTS.md:98-100, internal/api/traffic_test.go:87-92
Conclusion
The Metrics Aggregation & Logging system provides a robust framework for monitoring proxy operations. By combining efficient in-memory aggregation, structured database persistence, and low-latency SSE streaming, the system ensures that administrators have accurate, real-time data for troubleshooting and performance optimization while maintaining the security and stability of the control plane.