` | Number; a non-zero number of responses with status (100-599) |
| `xxx` | Number; a non-zero number of responses with other status codes |
| `data` | Object; data statistics |
| `received` | Number; the total number of bytes received from clients |
| `sent` | Number; the total number of bytes sent to clients |
Example:
```json
{
"ssl":{
"handshaked":4174,
"reuses":0,
"timedout":0,
"failed":0
},
"requests":{
"total":4327,
"processing":0,
"discarded":0
},
"responses":{
"200":4305,
"302":6,
"304":12,
"404":4
},
"data":{
"received":733955,
"sent":59207757
}
}
```
#### `/status/http/location_zones/`
To collect the `location` metrics, set the [status_zone](https://en.angie.software//angie/docs/configuration/modules/http/index.md#status-zone) directive
in the context of [location](https://en.angie.software//angie/docs/configuration/modules/http/index.md#location) or [if in location](https://en.angie.software//angie/docs/configuration/modules/http/http_rewrite.md#if):
```nginx
location / {
root /usr/share/angie/html;
status_zone location_zone;
if ($request_uri ~* "^/condition") {
# ...
status_zone if_location_zone;
}
}
```
To group the metrics by a custom value, use the alternative syntax.
Here, the metrics are aggregated by [$host](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-host),
with each group reported as a standalone zone:
```nginx
status_zone $host zone=server_zone:5;
```
The specified shared memory zone will collect the following statistics:
| `requests` | Object; requests statistics |
|--------------|----------------------------------------------------------------------------------|
| `total` | Number; the total number of client requests |
| `discarded` | Number; the total number of client requests completed without sending a response |
| `responses` | Object; responses statistics |
| `` | Number; a non-zero number of responses with status (100-599) |
| `xxx` | Number; a non-zero number of responses with other status codes |
| `data` | Object; data statistics |
| `received` | Number; the total number of bytes received from clients |
| `sent` | Number; the total number of bytes sent to clients |
Example:
```json
{
"requests": {
"total": 4158,
"discarded": 0
},
"responses": {
"200": 4157,
"304": 1
},
"data": {
"received": 538200,
"sent": 177606236
}
}
```
#### `/status/http/metric_zones/`
Custom metrics defined by [metric_zone](https://en.angie.software//angie/docs/configuration/modules/http/http_metric.md#metric-zone) or [metric_complex_zone](https://en.angie.software//angie/docs/configuration/modules/http/http_metric.md#metric-complex-zone)
in the `http` context. Metrics are updated with the [metric](https://en.angie.software//angie/docs/configuration/modules/http/http_metric.md#id3)
directive or the module variables.
| `discarded` | Number; the number of metric entries discarded because the zone ran out
of memory. |
|---------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `metrics` | Object; metrics per key. For single-metric zones, values are numbers.
For complex zones, values are objects with metric names. For histogram
mode, values are objects with bucket names. |
If `discard_key` is set and some entries have been expired,
their aggregated metrics are exposed under this key.
Example:
```json
{
"discarded": 3,
"metrics": {
"example.com": {
"count": 42,
"max": 8
}
"expired": {
"count": 10,
"max": 3.2
}
}
}
```
### Stream server
#### `/status/stream/server_zones/`
To collect the `server` metrics,
set the [status_zone](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#s-status-zone) directive in the [server](https://en.angie.software//angie/docs/configuration/modules/stream/index.md#s-server) context:
```nginx
server {
...
status_zone server_zone;
}
```
To group the metrics by a custom value, use the alternative syntax.
Here, the metrics are aggregated by [$host](https://en.angie.software//angie/docs/configuration/modules/http/index.md#v-host),
with each group reported as a standalone zone:
```nginx
status_zone $host zone=server_zone:5;
```
The specified shared memory zone will collect the following statistics:
| `ssl` | Object; SSL statistics.
Present if `server` sets `listen ssl;` |
|-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|
| `handshaked` | Number; the total number of successful SSL handshakes |
| `reuses` | Number; the total number of session reuses during SSL handshake |
| `timedout` | Number; the total number of timed out SSL handshakes |
| `failed` | Number; the total number of failed SSL handshakes |
| `connections` | Object; connections statistics |
| `total` | Number; the total number of client connections |
| `processing` | Number; the number of currently being processed client connections |
| `discarded` | Number; the total number of client connections
completed without creating a session |
| `passed` | Number; the total number of client connections
relayed to another listening port with `pass` directives |
| `sessions` | Object; sessions statistics |
| `success` | Number; the number of sessions completed with code 200, which means successful completion |
| `invalid` | Number; the number of sessions completed with code 400, which happens when client data could not be parsed, e.g. the PROXY protocol header |
| `forbidden` | Number; the number of sessions completed with code 403, when access was forbidden, for example, when access is limited for certain client addresses |
| `internal_error` | Number; the number of sessions completed with code 500, the internal server error |
| `bad_gateway` | Number; the number of sessions completed with code 502, bad gateway, for example, if an upstream server could not be selected or reached |
| `service_unavailable` | Number; the number of sessions completed with code 503, service unavailable, for example, when access is limited by the number of connections |
| `data` | Object; data statistics |
| `received` | Number; the total number of bytes received from clients |
| `sent` | Number; the total number of bytes sent to clients |
Example:
```json
{
"ssl": {
"handshaked": 24,
"reuses": 0,
"timedout": 0,
"failed": 0
},
"connections": {
"total": 24,
"processing": 1,
"discarded": 0,
"passed": 2
},
"sessions": {
"success": 24,
"invalid": 0,
"forbidden": 0,
"internal_error": 0,
"bad_gateway": 0,
"service_unavailable": 0
},
"data": {
"received": 2762947,
"sent": 53495723
}
}
```
### HTTP caches
```nginx
proxy_cache cache_zone;
proxy_cache_valid 200 10m;
```
#### `/status/http/caches/`
For each zone configured with [proxy_cache](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache), the following data is
stored:
```json
{
"name_zone": {
"size": 0,
"cold": false,
"hit": {
"responses": 0,
"bytes": 0
},
"stale": {
"responses": 0,
"bytes": 0
},
"updating": {
"responses": 0,
"bytes": 0
},
"revalidated": {
"responses": 0,
"bytes": 0
},
"miss": {
"responses": 0,
"bytes": 0,
"responses_written": 0,
"bytes_written": 0
},
"expired": {
"responses": 0,
"bytes": 0,
"responses_written": 0,
"bytes_written": 0
},
"bypass": {
"responses": 0,
"bytes": 0,
"responses_written": 0,
"bytes_written": 0
}
}
}
```
| `size` | Number; the current size of the cache |
|---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `max_size` | Number; configured limit on the maximum size of the cache |
| `cold` | Boolean; `true` while the cache loader loads data from disk |
| `hit` | Object; statistics of valid cached responses ([proxy_cache_valid](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-valid)) |
| `responses` | Number; the total number of responses read from the cache |
| `bytes` | Number; the total number of bytes read from the cache |
| `stale` | Object; statistics of stale responses taken from the cache ([proxy_cache_use_stale](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-use-stale)) |
| `responses` | Number; the total number of responses read from the cache |
| `bytes` | Number; the total number of bytes read from the cache |
| `updating` | Object; statistics of stale responses taken from the cache while responses were being updated ([proxy_cache_use_stale](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-use-stale) updating) |
| `responses` | Number; the total number of responses read from the cache |
| `bytes` | Number; the total number of bytes read from the cache |
| `revalidated` | Object; statistics of expired and revalidated responses taken from the cache ([proxy_cache_revalidate](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-revalidate)) |
| `responses` | Number; the total number of responses read from the cache |
| `bytes` | Number; the total number of bytes read from the cache |
| `miss` | Object; statistics of responses not found in the cache |
| `responses` | Number; the total number of corresponding responses |
| `bytes` | Number; the total number of bytes read from the proxied server |
| `responses_written` | Number; the total number of responses written to the cache |
| `bytes_written` | Number; the total number of bytes written to the cache |
| `expired` | Object; statistics of expired responses not taken from the cache |
| `responses` | Number; the total number of corresponding responses |
| `bytes` | Number; the total number of bytes read from the proxied server |
| `responses_written` | Number; the total number of responses written to the cache |
| `bytes_written` | Number; the total number of bytes written to the cache |
| `bypass` | Object; statistics of responses not looked up in the cache ([proxy_cache_bypass](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-bypass)) |
| `responses` | Number; the total number of corresponding responses |
| `bytes` | Number; the total number of bytes read from the proxied server |
| `responses_written` | Number; the total number of responses written to the cache |
| `bytes_written` | Number; the total number of bytes written to the cache |
In Angie PRO, if cache sharding is enabled with [proxy_cache_path](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-path) directives,
individual shards are exposed as object members of a `shards` object:
| `shards` | Object; lists individual shards as members |
|------------|---------------------------------------------------------------------|
| `` | Object; represents an individual shard with its cache path for name |
| `size` | Number; the shard's current size |
| `max_size` | Number; maximum shard size, if configured |
| `cold` | Boolean; `true` while the cache loader loads data from disk |
```json
{
"name_zone": {
"shards": {
"/path/to/shard1": {
"size": 0,
"cold": false
},
"/path/to/shard2": {
"size": 0,
"cold": false
}
}
}
```
### ACME clients
#### `/status/http/acme_clients/`
For each configured [acme_client](https://en.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) in the `http` block, returns the
current client and certificate status:
```json
{
"state": "ready",
"certificate": "valid",
"details": "The client is ready to request a certificate.",
"next_run": "|sampledateshort|T16:15:43.805Z"
}
```
| `state` | String; ACME client state. Possible values: `ready`,
`requesting`, `disabled`, `failed`. |
|---------------|------------------------------------------------------------------------------------------------------------------------------------|
| `certificate` | String; certificate status. Possible values: `valid`,
`expired`, `missing`, `mismatch`, `error`. |
| `details` | String; short status details from the last ACME operation. |
| `next_run` | Date; next scheduled attempt to request or renew the certificate.
Not returned when `state` is `disabled` or
`requesting`. |
### limit_conn
```nginx
limit_conn_zone $binary_remote_addr zone=limit_conn_zone:10m;
```
#### `/status/http/limit_conns/`, `/status/stream/limit_conns/`
Objects for each configured [limit_conn in http](#limit-conn) or [limit_conn in stream](https://en.angie.software//angie/docs/configuration/modules/stream/stream_limit_conn.md#s-limit-conn) contexts with the following fields:
```json
{
"passed": 73,
"skipped": 0,
"rejected": 0,
"exhausted": 0
}
```
| `passed` | Number; the total number of passed connections |
|-------------|-------------------------------------------------------------------------------------------------|
| `skipped` | Number; the total number of connections passed with zero-length key, or key exceeding 255 bytes |
| `rejected` | Number; the total number of connections exceeding the configured limit |
| `exhausted` | Number; the total number of connections rejected due to exhaustion of zone storage |
### limit_req
```nginx
limit_req_zone $binary_remote_addr zone=limit_req_zone:10m rate=1r/s;
```
#### `/status/http/limit_reqs/`
Objects for each configured [limit_req](#limit-req) with the following fields:
```json
{
"passed": 54816,
"skipped": 0,
"delayed": 65,
"rejected": 26,
"exhausted": 0
}
```
| `passed` | Number; the total number of passed requests |
|-------------|----------------------------------------------------------------------------------------------|
| `skipped` | Number; the total number of requests passed with zero-length key, or key exceeding 255 bytes |
| `delayed` | Number; the total number of delayed requests |
| `rejected` | Number; the total number of rejected requests |
| `exhausted` | Number; the total number of requests rejected due to exhaustion of zone storage |
### HTTP upstream
To enable collection of the following metrics,
set the [zone](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone) directive in the [upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) context,
for instance:
```nginx
upstream upstream {
zone upstream 256k;
server backend.example.com service=_example._tcp resolve max_conns=5;
keepalive 4;
}
```
#### `/status/http/upstreams/`
where is the name of any [upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) specified with the [zone](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone) directive
```json
{
"peers": {
"192.168.16.4:80": {
"server": "backend.example.com",
"service": "_example._tcp",
"backup": false,
"weight": 5,
"state": "up",
"selected": {
"current": 2,
"total": 232
},
"max_conns": 5,
"responses": {
"200": 222,
"302": 12
},
"data": {
"sent": 543866,
"received": 27349934
},
"health": {
"fails": 0,
"unavailable": 0,
"downtime": 0
},
"sid": ""
}
},
"keepalive": 2
}
```
| `peers` | Object; contains the metrics of the upstream's peers as subobjects
whose names are canonical representations of the peers' addresses.
Members of each subobject: |
|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `server` | String; the parameter of the [server](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) directive |
| `service` | String; name of service as it's specified in [server](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) directive, if configured |
| `backup` | Boolean; `true` for backup servers |
| `weight` | Number; configured [weight](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) |
| `state` | String; the current state of the peer and what requests are sent to it:
- `busy`: indicates that the number of requests to the server
has reached the limit set by [max_conns](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server),
and no new requests are sent to it;
- `down`: manually disabled, no requests are sent;
- `recovering`: recovering after a failure
according to [slow_start](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#slow-start),
more and more requests are sent over time;
- `unavailable`: reached the [max_fails](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails) limit,
only trial client requests are sent
at intervals defined by [fail_timeout](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#fail-timeout);
- `up`: operational, requests are sent as usual;
Additional states in Angie PRO:
- `checking`: configured as `essential` and being checked,
only [probe requests](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe) are sent;
- `draining`: similar to `down`,
but requests from previously bound sessions
(via [sticky](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky)) are still sent;
- `unhealthy`: non-operational,
only [probe requests](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe) are sent. |
| `selected` | Object; peer selection statistics |
| `current` | Number; the current number of connections to the peer |
| `total` | Number; total number of requests forwarded to the peer |
| `last` | String or number; time when the peer was last selected,
formatted as a [date](#api-date-format) |
| `max_conns` | Number; the configured [maximum](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) number of simultaneous active connections to the peer, if specified |
| `responses` | Object; response statistics |
| `` | Number; a non-zero number of responses with status (100-599) |
| `xxx` | Number; a non-zero number of responses with other status codes |
| `data` | Object; data statistics |
| `received` | Number; the total number of bytes received from the peer |
| `sent` | Number; the total number of bytes sent to the peer |
| `health` | Object; health statistics |
| `fails` | Number; the total number of unsuccessful attempts to communicate with the peer |
| `unavailable` | Number; how many times the peer became `unavailable` due to reaching the [max_fails](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails) limit |
| `downtime` | Number; the total time (in milliseconds) when the peer was `unavailable` for selection |
| `downstart` | String or number; time when the peer became `unavailable`,
formatted as a [date](#api-date-format) |
| `header_time`
| Number; average time (in milliseconds)
to receive the response headers from the server;
see [response_time_factor (PRO)](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-response-time-factor) |
| `response_time`
| Number; average time (in milliseconds)
to receive the entire response from the server;
see [response_time_factor (PRO)](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-response-time-factor) |
| `sid` | String; [configured id](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#reresolve) of the server in the upstream group |
| `keepalive` | Number; the current number of cached connections |
| `backup_switch` | Object; contains the current state of the active backup logic,
present if [backup_switch (PRO)](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-backup-switch) is configured for the upstream |
| `active` | Number; the level of the active group
that is currently used for load balancing requests.
If the active group is the primary one, the value is 0 |
| `timeout` | Number; remaining wait time in milliseconds,
after which the balancer will re-check for healthy nodes
in groups with lower levels, starting from the primary group,
while groups with higher levels are not checked;
not displayed for the primary group (level 0) |
##### `health/probes` (PRO)
#### Versionchanged
Changed in version 1.2.0: PRO
If the upstream has [upstream_probe (PRO)](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe) probes configured,
the `health` object also has a `probes` subobject
that stores the server's health probe counters,
while `state`, apart from the values listed in the table above,
can also be `checking` and `unhealthy`:
```json
{
"192.168.16.4:80": {
"state": "unhealthy",
"...": "...",
"health": {
"...": "...",
"probes": {
"count": 10,
"fails": 10,
"last": "|sampledateshort|T09:56:07Z"
}
}
}
}
```
The `checking` value of `state` isn't counted as `downtime`
and means that the server, which has a probe configured as `essential`,
hasn't been checked yet;
the `unhealthy` value means that the server is malfunctioning.
Both states also imply that the server isn't included in load balancing.
For details of health probes, see [upstream_probe](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe).
Counters in `probes`:
| `count` | Number; total probes for this server |
|-----------|--------------------------------------------------------------------------------|
| `fails` | Number; total failed probes |
| `last` | String or number; last probe time,
formatted as a [date](#api-date-format) |
##### `queue` (PRO)
#### Versionchanged
Changed in version 1.4.0: PRO
If a [request queue](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-queue) is configured for the upstream,
the upstream object also contains a nested `queue` object
with request queue counters:
```json
{
"queue": {
"queued": 20112,
"waiting": 1011,
"dropped": 6031,
"timedout": 560,
"overflows": 13
}
}
```
Counter values are summed across all worker processes:
| `queued` | Number; total number of requests that entered the queue |
|-------------|------------------------------------------------------------------------------------------------------------------|
| `waiting` | Number; current number of requests in the queue |
| `dropped` | Number; total number of requests removed from the queue
because the client prematurely closed the connection |
| `timedout` | Number; total number of requests removed from the queue due to timeout |
| `overflows` | Number; total number of queue overflow occurrences |
### Stream upstream
To enable collection of the following metrics,
set the [zone](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-zone) directive in the [upstream](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-upstream) context,
for instance:
```nginx
upstream upstream {
zone upstream 256k;
server backend.example.com service=_example._tcp resolve max_conns=5;
keepalive 4;
}
```
#### `/status/stream/upstreams/`
Here, is the name of an [upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) that is
configured with a [zone](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone) directive.
```json
{
"peers": {
"192.168.16.4:1935": {
"server": "backend.example.com",
"service": "_example._tcp",
"backup": false,
"weight": 5,
"state": "up",
"selected": {
"current": 2,
"total": 232
},
"max_conns": 5,
"data": {
"sent": 543866,
"received": 27349934
},
"health": {
"fails": 0,
"unavailable": 0,
"downtime": 0
}
}
}
}
```
| `peers` | Object; contains the metrics of the upstream's peers as subobjects
whose names are canonical representations of the peers' addresses.
Members of each subobject: |
|-----------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `server` | String; address set by the [server](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server) directive |
| `service` | String; service name, if set by the [server](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server) directive |
| `backup` | Boolean; `true` for backup servers |
| `weight` | Number; the [weight](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server) set for the peer |
| `state` | String; the current state of the peer and what requests are sent to it:
- `busy`: indicates that the number of requests to the server
has reached the limit set by [max_conns](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server),
and no new requests are sent to it
- `down`: manually disabled, no requests are sent
- `recovering`: recovering after a failure
according to [slow_start](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-slow-start),
more and more requests are sent over time
- `unavailable`: reached the [max_fails](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-max-fails) limit,
only trial client requests are sent
at intervals defined by [fail_timeout](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-fail-timeout)
- `up`: operational, requests are sent as usual
Additional states in Angie PRO:
- `checking`: configured as `essential` and being checked,
only [probe requests](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#s-u-upstream-probe) are sent
- `draining`: similar to `down`,
but requests from previously bound sessions
(via [sticky](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky)) are still sent
- `unhealthy`: non-operational,
only [probe requests](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#s-u-upstream-probe) are sent |
| `selected` | Object; statistics on selecting this peer for connections |
| `current` | Number; current number of connections to the peer |
| `total` | Number; total number of connections forwarded to the peer |
| `last` | String or number; time when the peer was last selected,
formatted as a [date](#api-date-format) |
| `max_conns` | Number;
[maximum](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server)
number of simultaneous active connections to the peer, if set |
| `data` | Object; data transfer statistics |
| `received` | Number; total bytes received from the peer |
| `sent` | Number; total bytes sent to the peer |
| `health` | Object; peer health statistics |
| `fails` | Number; total failed attempts to reach the peer |
| `unavailable` | Number; total number of times the peer became `unavailable` due to
reaching the [max_fails](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-max-fails) value |
| `downtime` | Number; total time (in milliseconds) that the peer was
`unavailable` (unavailable for selection) |
| `downstart` | String or number; time when the peer last became `unavailable`,
formatted as a [date](#api-date-format) |
| `connect_time`
| Number; average time (in milliseconds)
to establish a connection with the server;
see the [response_time_factor (PRO)](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-response-time-factor) directive |
| `first_byte_time`
| Number; average time (in milliseconds)
to receive the first byte of the response from the server;
see the [response_time_factor (PRO)](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-response-time-factor) directive |
| `last_byte_time`
| Number; average time (in milliseconds)
to receive the complete response from the server;
see the [response_time_factor (PRO)](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-response-time-factor) directive |
| `backup_switch`
(PRO 1.10.0+) | Object; contains the current state of active backup logic,
present if [backup_switch (PRO)](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-backup-switch) is configured for the upstream |
| `active` | Number; level of the active group
currently used for load balancing.
If the active group is the primary group, the value is 0 |
| `timeout` | Number; remaining wait time in milliseconds
after which the load balancer will recheck for healthy nodes
in groups with lower levels, starting from the primary group,
while groups with higher levels are not checked;
not displayed for the primary group (level 0) |
#### Versionchanged
Changed in version 1.4.0: PRO
In Angie PRO, if the upstream has [upstream_probe (PRO)](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#s-u-upstream-probe) probes configured,
the `health` object also has a `probes` subobject
that stores the server's health probe counters,
while `state`, in addition to the values from the table above,
can also be `checking` and `unhealthy`:
```json
{
"192.168.16.4:80": {
"state": "unhealthy",
"...": "...",
"health": {
"...": "...",
"probes": {
"count": 2,
"fails": 2,
"last": "|sampledateshort|T11:03:54Z"
}
}
}
}
```
The `checking` value of `state` means that the server,
which has a probe configured with the `essential` parameter,
hasn't been checked yet;
the `unhealthy` value means that the server is non-operational.
Both states also mean that the server isn't included in load balancing.
For details of health probes, see [upstream_probe](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#s-u-upstream-probe).
Counters in `probes`:
| `count` | Number; total number of probes for this server |
|-----------|---------------------------------------------------------------------------------------|
| `fails` | Number; number of failed probes |
| `last` | String or number; time of the last probe,
formatted as a [date](#api-date-format) |
## Dynamic Configuration API (PRO)
The API includes a `/config` section that enables dynamic updates
to Angie's configuration in JSON format
with `PUT`, `PATCH`, and `DELETE` HTTP requests.
All updates are atomic: new settings are applied as a whole,
or none are applied at all.
On error, Angie reports the reason.
### Subsections of `/config`
Currently, configuration of individual servers within upstreams is available
in the `/config` section for the [HTTP](#api-config-http-upstreams-servers) and [stream](#api-config-stream-upstreams-servers) modules; the number of settings
eligible for dynamic configuration is steadily increasing.
#### `/config/http/upstreams//servers/`
Enables configuring individual upstream peers,
including deleting existing peers or adding new ones.
URI path parameters:
| `` | Name of the upstream; to be configurable via `/config`, it must
have a [zone](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone) directive configured, defining a shared
memory zone. |
|----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `` | The peer's name within the upstream, defined as
`@`, where:
- `@` is an optional service name, used for
SRV record resolution.
- `` is the domain name of the service (if `resolve`
is present) or its IP; an optional port can be defined here. |
For example, the following configuration:
```nginx
upstream backend {
server backend.example.com service=_http._tcp resolve;
server 127.0.0.1;
zone backend 1m;
}
```
Allows the following peer names:
```console
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/_http._tcp@backend.example.com/
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/127.0.0.1:80/
```
This API subsection enables setting the `weight`, `max_conns`,
`max_fails`, `fail_timeout`, `slow_start`, `backup`, `down` and
`sid` parameters, as described in [server](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server).
#### NOTE
There is no separate `drain` (PRO) parameter here;
to enable `drain`,
set `down` to the string value `drain`:
```console
$ curl -X PUT -d \"drain\" \
http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com/down
```
Example:
```console
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com?defaults=on
```
```json
{
"weight": 1,
"max_conns": 0,
"max_fails": 1,
"fail_timeout": 10,
"slow_start": 0,
"backup": true,
"down": false,
"sid": ""
}
```
Actually available parameters are limited to the ones supported by the
current load balancing method of the [upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream).
So, if the upstream is configured with the `random` method:
```nginx
upstream backend {
zone backend 256k;
server backend.example.com resolve max_conns=5;
random;
}
```
You will be unable to add a new peer that defines `backup`:
```console
$ curl -X PUT -d '{ "backup": true }' \
http://127.0.0.1/config/http/upstreams/backend/servers/backend1.example.com
```
```json
{
"error": "FormatError",
"description": "The \"backup\" field is unknown."
}
```
#### NOTE
Even with a compatible load balancing method, the `backup` parameter
can only be set when adding a new peer.
#### `/config/stream/upstreams//servers/`
Enables configuring individual upstream peers,
including deleting existing peers or adding new ones.
URI path parameters:
| `` | Name of the `upstream` block;
to be configurable via `/config`,
it must have a [zone](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-zone) directive configured,
defining a shared memory zone. |
|----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `` | The peer's name within the upstream, defined as
`@`, where:
- `@` is an optional service name, used for
SRV record resolution.
- `` is the domain name of the service (if `resolve`
is present) or its IP; an optional port can be defined here. |
For example, the following configuration:
```nginx
upstream backend {
server backend.example.com:8080 service=_example._tcp resolve;
server 127.0.0.1:12345;
zone backend 1m;
}
```
Allows the following peer names:
```console
$ curl http://127.0.0.1/config/stream/upstreams/backend/servers/_example._tcp@backend.example.com:8080/
$ curl http://127.0.0.1/config/stream/upstreams/backend/servers/127.0.0.1:12345/
```
This API subsection enables setting the `weight`,
`max_conns`, `max_fails`, `fail_timeout`, `slow_start`, `backup`, and
`down` parameters, as described in [server](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server).
#### NOTE
There is no separate `drain` (PRO) parameter here;
to enable `drain` mode,
set `down` to the string value `drain`:
```console
$ curl -X PUT -d \"drain\" \
http://127.0.0.1/config/stream/upstreams/backend/servers/backend.example.com/down
```
Example:
```console
curl http://127.0.0.1/config/stream/upstreams/backend/servers/backend.example.com?defaults=on
```
```json
{
"weight": 1,
"max_conns": 0,
"max_fails": 1,
"fail_timeout": 10,
"slow_start": 0,
"backup": true,
"down": false,
}
```
Actually available parameters are limited to the ones supported by the
current load balancing method of the [upstream](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-upstream).
So, if the upstream is configured with the `random` method:
```nginx
upstream backend {
zone backend 256k;
server backend.example.com resolve max_conns=5;
random;
}
```
You will be unable to add a new peer that defines `backup`:
```console
$ curl -X PUT -d '{ "backup": true }' \
http://127.0.0.1/config/stream/upstreams/backend/servers/backend1.example.com
```
```json
{
"error": "FormatError",
"description": "The \"backup\" field is unknown."
}
```
#### NOTE
Even with a compatible load balancing method, the `backup` parameter
can only be set when adding a new peer.
When deleting peers, you can set the
`connection_drop=` argument (PRO) to override the
[proxy_connection_drop](https://en.angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-connection-drop) settings:
```console
$ curl -X DELETE \
http://127.0.0.1/config/stream/upstreams/backend/servers/backend1.example.com?connection_drop=off
$ curl -X DELETE \
http://127.0.0.1/config/stream/upstreams/backend/servers/backend2.example.com?connection_drop=on
$ curl -X DELETE \
http://127.0.0.1/config/stream/upstreams/backend/servers/backend3.example.com?connection_drop=1000
```
### HTTP Methods
Let's consider the semantics of each HTTP method applicable to this section
using the following upstream configuration as an example:
```nginx
http {
# ...
upstream backend {
zone upstream 256k;
server backend.example.com resolve max_conns=5;
# ...
}
server {
# ...
location /config/ {
api /config/;
allow 127.0.0.1;
deny all;
}
}
}
```
#### GET
The `GET` HTTP method queries an entity at any existing path within
`/config`, just as it does for other API sections.
For example, the
`/config/http/upstreams/backend/servers/`
upstream server branch enables these queries:
```console
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com/max_conns
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com
$ curl http://127.0.0.1/config/http/upstreams/backend/servers
$ # ...
$ curl http://127.0.0.1/config
```
You can obtain default parameter values with the `defaults=on` argument:
```console
$ curl http://127.0.0.1/config/http/upstreams/backend/servers?defaults=on
```
```json
{
"backend.example.com": {
"weight": 1,
"max_conns": 5,
"max_fails": 1,
"fail_timeout": 10,
"slow_start": 0,
"backup": false,
"down": false,
"sid": ""
}
}
```
#### PUT
The `PUT` HTTP method creates a new JSON entity at the specified path
or *entirely* replaces an existing one.
For example, to add the `max_fails` parameter, not specified earlier,
to the `backend.example.com` server within the `backend` upstream:
```console
$ curl -X PUT -d '2' \
http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com/max_fails
```
```json
{
"success": "Updated",
"description": "Existing configuration API entity \"/config/http/upstreams/backend/servers/backend.example.com/max_fails\" was updated with replacing."
}
```
Verify the changes:
```console
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com
```
```json
{
"max_conns": 5,
"max_fails": 2
}
```
#### DELETE
The `DELETE` HTTP method deletes *previously defined* settings at the specified path;
in doing so, it restores the default values if there are any.
For example, to delete the previously modified `max_fails` parameter
of the `backend.example.com` server within the `backend` upstream:
```console
$ curl -X DELETE \
http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com/max_fails
```
```console
{
"success": "Reset",
"description": "Configuration API entity \"/config/http/upstreams/backend/servers/backend.example.com/max_fails\" was reset to default."
}
```
Verify the changes using the `defaults=on` argument:
```console
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com?defaults=on
```
```json
{
"weight": 1,
"max_conns": 5,
"max_fails": 1,
"fail_timeout": 10,
"slow_start": 0,
"backup": false,
"down": false,
"sid": ""
}
```
The `max_fails` parameter has returned to its default value.
When deleting servers, you can set the `connection_drop=` argument
(PRO) to override the [proxy_connection_drop](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-connection-drop), [grpc_connection_drop](https://en.angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-connection-drop),
[fastcgi_connection_drop](https://en.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-connection-drop), [scgi_connection_drop](https://en.angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-connection-drop), and
[uwsgi_connection_drop](https://en.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-connection-drop) settings:
```console
$ curl -X DELETE \
http://127.0.0.1/config/http/upstreams/backend/servers/backend1.example.com?connection_drop=off
$ curl -X DELETE \
http://127.0.0.1/config/http/upstreams/backend/servers/backend2.example.com?connection_drop=on
$ curl -X DELETE \
http://127.0.0.1/config/http/upstreams/backend/servers/backend3.example.com?connection_drop=1000
```
#### PATCH
The `PATCH` HTTP method creates a new entity at the specified path
or partially replaces or complements an existing one
([RFC 7386](https://datatracker.ietf.org/doc/html/rfc7396))
by supplying a JSON definition in its payload.
The method operates as follows: if the entities from the new definition
exist in the configuration, they are overwritten; otherwise, they are added.
For example, to change the `down` parameter of the
`backend.example.com` server within the `backend` upstream,
leaving the rest intact:
```console
$ curl -X PATCH -d '{ "down": true }' \
http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com
```
```json
{
"success": "Updated",
"description": "Existing configuration API entity \"/config/http/upstreams/backend/servers/backend.example.com\" was updated with merging."
}
```
Verify the changes:
```console
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com
```
```json
{
"max_conns": 5,
"down": true
}
```
Note that the JSON object supplied with the `PATCH` request *was merged* with the
existing one instead of replacing it entirely, as would be the case with `PUT`.
The `null` values are a special case; they are used to delete
specific configuration items during such a merge.
#### NOTE
This deletion is identical to `DELETE`;
in particular, it restores the default values.
For example, to delete the `down` parameter added earlier
and simultaneously update `max_conns`:
```console
$ curl -X PATCH -d '{ "down": null, "max_conns": 6 }' \
http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com
```
```json
{
"success": "Updated",
"description": "Existing configuration API entity \"/config/http/upstreams/backend/servers/backend.example.com\" was updated with merging."
}
```
Verify the changes:
```console
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com
```
```json
{
"max_conns": 6
}
```
The `down` parameter, for which a `null` value was supplied, was deleted;
the `max_conns` value was updated.