MeghdadFadaee/ngx_http_monitoring_module
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Updated skills/ngx-http-monitoring-client/SKILL.md:45 with API response structures.

Browse Source
This commit is contained in:
Meghdad Fadaee
2026-05-12 16:23:04 +03:30
parent b6501f14b0
commit 564d5afbfb
1 changed files with 395 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

396
skills/ngx-http-monitoring-client/SKILL.md
View File

@@ -1,6 +1,6 @@
--- ---
name: ngx-http-monitoring-client name: ngx-http-monitoring-client
description: Use this skill when connecting clients or agents to an ngx_http_monitoring_module service, querying its JSON/SSE/Prometheus endpoints, debugging access problems, or integrating dashboards/health checks. Supports deployments protected by Nginx Basic Auth and/or monitor_api_token. description: Use this skill when connecting clients or agents to an ngx_http_monitoring_module service, querying its JSON/SSE/Prometheus endpoints, reading API response structures, debugging access problems, or integrating dashboards/health checks. Supports deployments protected by Nginx Basic Auth and/or monitor_api_token.
--- ---
# ngx_http_monitoring_module Client # ngx_http_monitoring_module Client
@@ -42,6 +42,400 @@ MONITOR_BASIC_AUTH=user:password
- `GET /monitor/metrics` - Prometheus text format - `GET /monitor/metrics` - Prometheus text format
- `GET /monitor/health` - lightweight JSON health check - `GET /monitor/health` - lightweight JSON health check
## API Structures
All JSON API responses are compact, versioned, and timestamped. Treat unknown fields as forward-compatible additions, and treat missing sections as disabled collectors, unsupported Nginx build options, or unavailable Linux `/proc` data.
Common envelope:
```json
{
"version": 1,
"module": "1.0.0",
"timestamp": 1710000000,
"msec": 123,
"scope": "full",
"pid": 12345
}
```
Endpoint-specific API routes such as `/monitor/api/system` return the common envelope plus one top-level field matching the route. The examples below show that section's value unless explicitly shown as a complete response.
`GET /monitor/api` returns the envelope plus:
```json
{
"system": {},
"nginx": {},
"network": {},
"disk": {},
"processes": {},
"upstreams": [],
"connections": {},
"requests": {},
"history": []
}
```
`GET /monitor/api/system`:
```json
{
"cpu": {
"usage": 12.5,
"cores": 8,
"load": [0.12, 0.20, 0.30]
},
"memory": {
"total": 16777216,
"available": 8388608,
"free": 4194304,
"used": 8388608,
"used_pct": 50.0
},
"swap": {
"total": 2097152,
"free": 1048576,
"used_pct": 50.0
},
"uptime": 123456
}
```
`GET /monitor/api/nginx`:
```json
{
"connections": {
"accepted": 1000,
"handled": 1000,
"active": 20,
"reading": 1,
"writing": 4,
"waiting": 15
},
"requests": {
"total": 50000,
"responses": 49990,
"requests_per_sec": 125.5,
"responses_per_sec": 125.3
},
"ssl": {
"requests": 100,
"handshakes": 20
},
"keepalive": {
"requests": 250
},
"workers": []
}
```
`GET /monitor/api/network`:
```json
{
"rx_bytes": 123456789,
"tx_bytes": 987654321,
"rx_packets": 10000,
"tx_packets": 12000,
"rx_errors": 0,
"tx_errors": 0,
"interfaces": [
{
"name": "eth0",
"rx_bytes": 123456789,
"tx_bytes": 987654321,
"rx_packets": 10000,
"tx_packets": 12000,
"rx_errors": 0,
"tx_errors": 0,
"up": true
}
]
}
```
`GET /monitor/api/disk`:
```json
{
"reads": 1000,
"writes": 2000,
"read_bytes": 4096000,
"write_bytes": 8192000,
"devices": [
{
"name": "sda",
"reads": 1000,
"writes": 2000,
"read_bytes": 4096000,
"write_bytes": 8192000,
"io_ms": 120
}
],
"filesystems": [
{
"path": "/",
"type": "ext4",
"total": 107374182400,
"used": 53687091200,
"free": 53687091200,
"avail": 53687091200,
"files": 1000000,
"files_free": 750000
}
]
}
```
`GET /monitor/api/processes`:
```json
{
"process_count": 140,
"tcp": {
"established": 20,
"listen": 8
},
"sockets": {
"used": 512,
"tcp": 120,
"udp": 16
},
"workers": []
}
```
`GET /monitor/api/connections`:
```json
{
"accepted": 1000,
"handled": 1000,
"active": 20,
"reading": 1,
"writing": 4,
"waiting": 15,
"ssl_requests": 100,
"ssl_handshakes": 20,
"keepalive_requests": 250,
"sse_clients": 2,
"sse_events": 500,
"rate_limited": 0
}
```
`GET /monitor/api/requests`:
```json
{
"total": 50000,
"responses": 49990,
"bytes": 104857600,
"requests_per_sec": 125.5,
"responses_per_sec": 125.3,
"error_rate": 0.0078,
"latency": {
"avg": 8.4,
"p50": 4,
"p90": 15,
"p95": 22,
"p99": 80
},
"status": {
"1xx": 0,
"2xx": 49000,
"3xx": 600,
"4xx": 300,
"5xx": 90
},
"methods": {
"GET": 45000,
"POST": 4000,
"PUT": 100,
"DELETE": 50,
"HEAD": 500,
"OPTIONS": 200,
"PATCH": 50,
"OTHER": 100
},
"latency_histogram": [
{
"le": 1,
"count": 100
},
{
"le": "+Inf",
"count": 50000
}
],
"size_histogram": [
{
"le": 512,
"count": 10000
},
{
"le": "+Inf",
"count": 50000
}
],
"top_urls": [],
"user_agents": []
}
```
`GET /monitor/api/upstreams`:
```json
[
{
"peer": "127.0.0.1:9000",
"requests": 1000,
"failures": 2,
"status_4xx": 10,
"status_5xx": 2,
"avg_latency": 12.5,
"last_seen": 1710000000
}
]
```
History samples in `GET /monitor/api`:
```json
[
{
"timestamp": 1710000000,
"cpu": 12.5,
"memory": 50.0,
"swap": 0.0,
"rps": 125.5,
"responses_per_sec": 125.3,
"network_rx_per_sec": 1024,
"network_tx_per_sec": 2048,
"disk_read_per_sec": 0,
"disk_write_per_sec": 4096,
"latency_p95": 22,
"requests_total": 50000,
"status_4xx": 300,
"status_5xx": 90
}
]
```
Shared nested structures:
```json
{
"worker": {
"slot": 0,
"pid": 12345,
"active": true,
"requests": 10000,
"bytes": 10485760,
"errors": 3,
"vm_size": 102400,
"vm_rss": 20480,
"voluntary_ctxt": 100,
"nonvoluntary_ctxt": 5,
"last_seen": 1710000000
},
"top_url": {
"url": "/api/orders",
"hits": 1000,
"errors": 3,
"bytes": 1048576,
"avg_latency": 7.8,
"last_seen": 1710000000
},
"user_agent": {
"user_agent": "curl/8.0.1",
"hits": 100,
"errors": 0,
"bytes": 20480,
"avg_latency": 2.1,
"last_seen": 1710000000
}
}
```
SSE `GET /monitor/live` sends `metrics` events whose `data` payload has this structure:
```json
{
"version": 1,
"timestamp": 1710000000,
"sequence": 42,
"system": {
"cpu": {
"usage": 12.5,
"cores": 8
},
"memory": {
"used_pct": 50.0,
"total": 16777216,
"available": 8388608
}
},
"requests": {
"total": 50000,
"requests_per_sec": 125.5,
"responses_per_sec": 125.3,
"latency": {
"p95": 22,
"p99": 80
},
"status": {
"4xx": 300,
"5xx": 90
}
},
"connections": {
"active": 20,
"reading": 1,
"writing": 4,
"waiting": 15,
"sse_clients": 2,
"keepalive_requests": 250
},
"network": {
"rx_bytes": 123456789,
"tx_bytes": 987654321
},
"disk": {
"read_bytes": 4096000,
"write_bytes": 8192000
}
}
```
`GET /monitor/metrics` exposes Prometheus text metrics including:
```text
nginx_monitor_requests_total
nginx_monitor_active_connections
nginx_monitor_cpu_usage_ratio
nginx_monitor_memory_used_ratio
nginx_monitor_latency_p95_ms
```
`GET /monitor/health` returns a complete health response:
```json
{
"version": 1,
"module": "1.0.0",
"timestamp": 1710000000,
"msec": 123,
"scope": "health",
"pid": 12345,
"status": "ok",
"generation": 100,
"sse_clients": 2
}
```
## Auth Rules ## Auth Rules
If the service is behind Nginx Basic Auth, include Basic Auth on every request, including `/monitor`, `/monitor/live`, and `/monitor/metrics`. If the service is behind Nginx Basic Auth, include Basic Auth on every request, including `/monitor`, `/monitor/live`, and `/monitor/metrics`.