61 lines
2.4 KiB
Markdown
61 lines
2.4 KiB
Markdown
# Architecture
|
|
|
|
## Request Path
|
|
|
|
The module registers two HTTP phase handlers:
|
|
|
|
- content phase: handles `/monitor`, `/monitor/api*`, `/monitor/live`, `/monitor/metrics`, and `/monitor/health`
|
|
- log phase: accounts completed application requests
|
|
|
|
Monitoring endpoints are excluded from request accounting to avoid dashboard polling skewing the service metrics.
|
|
|
|
## Shared Memory
|
|
|
|
The module allocates one shared memory zone named `ngx_http_monitoring`. The zone contains:
|
|
|
|
- global request, response, connection, and system counters
|
|
- fixed-size top URL and user-agent tables
|
|
- fixed-size upstream peer table
|
|
- per-worker metric slots keyed by `ngx_process_slot`
|
|
- fixed-size historical ring buffer
|
|
- collector lock and API rate-limit counters
|
|
|
|
Hot request-path updates use Nginx atomic operations. The shared slab mutex is used only for rare top-N slot creation or replacement and rate-limit window resets.
|
|
|
|
## Collection
|
|
|
|
Each worker owns a timer, but collection is guarded by an atomic shared lock, so only one worker performs a collection pass at a time. Collection reads:
|
|
|
|
- `/proc/stat`
|
|
- `/proc/loadavg`
|
|
- `/proc/meminfo`
|
|
- `/proc/net/dev`
|
|
- `/proc/diskstats`
|
|
- `/proc/uptime`
|
|
- `/proc/net/tcp`
|
|
- `/proc/net/tcp6`
|
|
- `/proc/net/sockstat`
|
|
- `/proc/mounts`
|
|
- `/proc/self/status`
|
|
- `/proc`
|
|
- `statvfs()`
|
|
- `getifaddrs()`
|
|
|
|
The collector computes deltas and moving averages, then appends a sample to the ring buffer according to `monitor_resolution`.
|
|
|
|
## Serialization
|
|
|
|
JSON and Prometheus responses are generated from shared-memory snapshots only. API handlers do not read `/proc`, do not allocate persistent state, and use one request-pool buffer per response.
|
|
|
|
## SSE
|
|
|
|
`/monitor/live` is a long-lived request. Each client owns two reusable output buffers and a timer. The writer skips a tick if the connection still has pending buffered output, preventing slow clients from accumulating unbounded memory.
|
|
|
|
## Upstreams
|
|
|
|
Upstream metrics are passively observed from Nginx upstream state recorded on proxied requests. This avoids active backend probing in workers. Failures are counted from zero or `5xx` upstream statuses.
|
|
|
|
## Compatibility
|
|
|
|
The module is designed as an Nginx dynamic HTTP module and should be built with `--with-compat` against the target Nginx source tree. Stub-status counters are compiled in when the target Nginx build includes `--with-http_stub_status_module`; otherwise request counters still work but low-level active/reading/writing/waiting counters remain zero.
|