` | 数字；状态为 （100-599）的响应的非零数量 |
| `xxx` | 数字；其他状态代码的响应的非零数量 |
| `data` | 对象；数据统计信息 |
| `received` | 数字；从客户端接收的总字节数 |
| `sent` | 数字；发送到客户端的总字节数 |
示例：
```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/`
要收集 `location` 指标，请在 [location](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#location) 或 [if in location](https://cn.angie.software//angie/docs/configuration/modules/http/http_rewrite.md#if) 上下文中设置 [status_zone](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#status-zone) 指令：
```nginx
location / {
root /usr/share/angie/html;
status_zone location_zone;
if ($request_uri ~* "^/condition") {
# ...
status_zone if_location_zone;
}
}
```
要按自定义值对指标进行分组，请使用替代语法。
在这里，指标按 [$host](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#v-host) 聚合，每个组作为独立区域报告：
```nginx
status_zone $host zone=server_zone:5;
```
指定的共享内存区域将收集以下统计信息：
| `requests` | 对象；请求统计信息 |
|--------------|------------------------------|
| `total` | 数字；客户端请求总数 |
| `discarded` | 数字；未发送响应而完成的客户端请求总数 |
| `responses` | 对象；响应统计信息 |
| `` | 数字；状态为 （100-599）的非零响应数 |
| `xxx` | 数字；其他状态代码的非零响应数 |
| `data` | 对象；数据统计信息 |
| `received` | 数字；从客户端接收的字节总数 |
| `sent` | 数字；发送给客户端的字节总数 |
示例：
```json
{
"requests": {
"total": 4158,
"discarded": 0
},
"responses": {
"200": 4157,
"304": 1
},
"data": {
"received": 538200,
"sent": 177606236
}
}
```
#### `/status/http/metric_zones/`
由 `http` 上下文中的 [metric_zone](https://cn.angie.software//angie/docs/configuration/modules/http/http_metric.md#metric-zone) 或 [metric_complex_zone](https://cn.angie.software//angie/docs/configuration/modules/http/http_metric.md#metric-complex-zone)
定义的自定义指标。指标通过 [metric](https://cn.angie.software//angie/docs/configuration/modules/http/http_metric.md#id5)
指令或模块变量更新。
| `discarded` | 数字；因区域内存不足而丢弃的指标条目数。 |
|---------------|------------------------------------------------------------------------|
| `metrics` | 对象；按键的指标。对于单指标区域，值为数字。
对于复杂区域，值为带有指标名称的对象。对于直方图
模式，值为带有桶名称的对象。 |
如果设置了 `discard_key` 并且某些条目已过期，
它们的聚合指标将在此键下公开。
示例：
```json
{
"discarded": 3,
"metrics": {
"example.com": {
"count": 42,
"max": 8
}
"expired": {
"count": 10,
"max": 3.2
}
}
}
```
### Stream 服务器
#### `/status/stream/server_zones/`
要收集 `server` 指标，
请在 [server](https://cn.angie.software//angie/docs/configuration/modules/stream/index.md#s-server) 上下文中设置 [status_zone](https://cn.angie.software//angie/docs/configuration/modules/stream/index.md#s-status-zone) 指令：
```nginx
server {
...
status_zone server_zone;
}
```
要按自定义值对指标进行分组，请使用替代语法。
此处，指标按 [$host](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#v-host) 聚合，
每个组作为独立区域报告：
```nginx
status_zone $host zone=server_zone:5;
```
指定的共享内存区域将收集以下统计信息：
| `ssl` | 对象；SSL 统计信息。
当 `server` 设置 `listen ssl;` 时出现 |
|-----------------------|----------------------------------------------------|
| `handshaked` | 数字；成功 SSL 握手的总次数 |
| `reuses` | 数字；SSL 握手期间会话重用的总次数 |
| `timedout` | 数字；超时 SSL 握手的总次数 |
| `failed` | 数字；失败 SSL 握手的总次数 |
| `connections` | 对象；连接统计信息 |
| `total` | 数字；客户端连接的总数 |
| `processing` | 数字；当前正在处理的客户端连接数 |
| `discarded` | 数字；未创建会话即完成的客户端连接总数 |
| `passed` | 数字；通过 `pass` 指令中继到另一个监听端口的客户端连接总数 |
| `sessions` | 对象；会话统计信息 |
| `success` | 数字；以代码 200 完成的会话数，表示成功完成 |
| `invalid` | 数字；以代码 400 完成的会话数，当无法解析客户端数据时发生，例如 PROXY 协议头 |
| `forbidden` | 数字；以代码 403 完成的会话数，当访问被禁止时，例如当某些客户端地址的访问受到限制时 |
| `internal_error` | 数字；以代码 500 完成的会话数，内部服务器错误 |
| `bad_gateway` | 数字；以代码 502 完成的会话数，错误网关，例如无法选择或访问上游服务器时 |
| `service_unavailable` | 数字；以代码 503 完成的会话数，服务不可用，例如当访问受连接数限制时 |
| `data` | 对象；数据统计信息 |
| `received` | 数字；从客户端接收的总字节数 |
| `sent` | 数字；发送到客户端的总字节数 |
示例：
```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 缓存
```nginx
proxy_cache cache_zone;
proxy_cache_valid 200 10m;
```
#### `/status/http/caches/`
对于使用 [proxy_cache](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache) 配置的每个区域，存储以下数据：
```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` | 数字；缓存的当前大小 |
|---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `max_size` | 数字；配置的缓存最大大小限制 |
| `cold` | 布尔值；当 cache loader 从磁盘加载数据时为 `true` |
| `hit` | 对象；有效缓存响应的统计信息 ([proxy_cache_valid](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-valid)) |
| `responses` | 数字；从缓存读取的响应总数 |
| `bytes` | 数字；从缓存读取的总字节数 |
| `stale` | 对象；从缓存获取的过期响应的统计信息 ([proxy_cache_use_stale](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-use-stale)) |
| `responses` | 数字；从缓存读取的响应总数 |
| `bytes` | 数字；从缓存读取的总字节数 |
| `updating` | 对象；在响应更新期间从缓存获取的过期响应的统计信息 ([proxy_cache_use_stale](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-use-stale) updating) |
| `responses` | 数字；从缓存读取的响应总数 |
| `bytes` | 数字；从缓存读取的总字节数 |
| `revalidated` | 对象；从缓存获取的已过期并重新验证的响应的统计信息 ([proxy_cache_revalidate](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-revalidate)) |
| `responses` | 数字；从缓存读取的响应总数 |
| `bytes` | 数字；从缓存读取的总字节数 |
| `miss` | 对象；在缓存中未找到的响应的统计信息 |
| `responses` | 数字；相应响应的总数 |
| `bytes` | 数字；从代理服务器读取的总字节数 |
| `responses_written` | 数字；写入缓存的响应总数 |
| `bytes_written` | 数字；写入缓存的总字节数 |
| `expired` | 对象；未从缓存获取的已过期响应的统计信息 |
| `responses` | 数字；相应响应的总数 |
| `bytes` | 数字；从代理服务器读取的总字节数 |
| `responses_written` | 数字；写入缓存的响应总数 |
| `bytes_written` | 数字；写入缓存的总字节数 |
| `bypass` | 对象；未在缓存中查找的响应的统计信息 ([proxy_cache_bypass](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-bypass)) |
| `responses` | 数字；相应响应的总数 |
| `bytes` | 数字；从代理服务器读取的总字节数 |
| `responses_written` | 数字；写入缓存的响应总数 |
| `bytes_written` | 数字；写入缓存的总字节数 |
在 Angie PRO 中，如果使用 [proxy_cache_path](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-path) 指令启用了 cache sharding，
各个分片将作为 `shards` 对象的对象成员公开：
| `shards` | 对象；将各个分片列为成员 |
|------------|-------------------------------------|
| `` | 对象；表示单个分片，其缓存路径作为名称 |
| `size` | 数字；分片的当前大小 |
| `max_size` | 数字；最大分片大小（如果已配置） |
| `cold` | 布尔值；当 cache loader 从磁盘加载数据时为 `true` |
```json
{
"name_zone": {
"shards": {
"/path/to/shard1": {
"size": 0,
"cold": false
},
"/path/to/shard2": {
"size": 0,
"cold": false
}
}
}
```
### ACME 客户端
#### `/status/http/acme_clients/`
对于 `http` 块中配置的每个 [acme_client](https://cn.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client)，返回当前客户端和证书状态：
```json
{
"state": "ready",
"certificate": "valid",
"details": "The client is ready to request a certificate.",
"next_run": "|sampledateshort|T16:15:43.805Z"
}
```
| `state` | 字符串；ACME 客户端状态。可能的值：`ready`、
`requesting`、`disabled`、`failed`。 |
|---------------|--------------------------------------------------------------------------|
| `certificate` | 字符串；证书状态。可能的值：`valid`、
`expired`、`missing`、`mismatch`、`error`。 |
| `details` | 字符串；上次 ACME 操作的简短状态详情。 |
| `next_run` | 日期；下次计划请求或续订证书的尝试时间。
当 `state` 为 `disabled` 或
`requesting` 时不返回。 |
### limit_conn
```nginx
limit_conn_zone $binary_remote_addr zone=limit_conn_zone:10m;
```
#### `/status/http/limit_conns/`，`/status/stream/limit_conns/`
每个配置的 [http 中的 limit_conn](#limit-conn) 或 [stream 中的 limit_conn](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_limit_conn.md#s-limit-conn) 上下文的对象，包含以下字段：
```json
{
"passed": 73,
"skipped": 0,
"rejected": 0,
"exhausted": 0
}
```
| `passed` | 数字；通过的连接总数 |
|-------------|------------------------------|
| `skipped` | 数字；使用零长度键或键超过 255 字节而通过的连接总数 |
| `rejected` | 数字；超过配置限制的连接总数 |
| `exhausted` | 数字；由于区域存储耗尽而拒绝的连接总数 |
### limit_req
```nginx
limit_req_zone $binary_remote_addr zone=limit_req_zone:10m rate=1r/s;
```
#### `/status/http/limit_reqs/`
每个配置的 [limit_req](#limit-req) 的对象，包含以下字段：
```json
{
"passed": 54816,
"skipped": 0,
"delayed": 65,
"rejected": 26,
"exhausted": 0
}
```
| `passed` | 数字；通过的请求总数 |
|-------------|------------------------------|
| `skipped` | 数字；使用零长度键或键超过 255 字节而通过的请求总数 |
| `delayed` | 数字；延迟的请求总数 |
| `rejected` | 数字；拒绝的请求总数 |
| `exhausted` | 数字；由于区域存储耗尽而拒绝的请求总数 |
### HTTP 上游
要启用以下指标的收集，
请在 [upstream](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) 上下文中设置 [zone](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone) 指令，
例如：
```nginx
upstream upstream {
zone upstream 256k;
server backend.example.com service=_example._tcp resolve max_conns=5;
keepalive 4;
}
```
#### `/status/http/upstreams/`
其中 是使用 [zone](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone) 指令指定的任何 [upstream](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) 的名称
```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` | 对象；包含上游节点的指标作为子对象，
子对象的名称是节点地址的规范表示。
每个子对象的成员： |
|-----------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `server` | 字符串；[server](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) 指令的参数 |
| `service` | 字符串；在 [server](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) 指令中指定的服务名称（如果已配置） |
| `backup` | 布尔值；备份服务器为 `true` |
| `weight` | 数字；配置的 [权重](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) |
| `state` | 字符串；节点的当前状态以及发送给它的请求：
- `busy`：表示发送到服务器的请求数量
已达到 [max_conns](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) 设置的限制，
不再向其发送新请求；
- `down`：手动禁用，不发送请求；
- `recovering`：根据 [slow_start](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#slow-start) 从故障中恢复，
随着时间推移发送越来越多的请求；
- `unavailable`：达到 [max_fails](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails) 限制，
仅在 [fail_timeout](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#fail-timeout) 定义的间隔内
发送试探性客户端请求；
- `up`：正常运行，正常发送请求；
Angie PRO 中的附加状态：
- `checking`：配置为 `essential` 并正在检查中，
仅发送 [探测请求](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe)；
- `draining`：类似于 `down`，
但来自先前绑定会话的请求
（通过 [sticky](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky)）仍会发送；
- `unhealthy`：不可操作，
仅发送 [探测请求](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe)。 |
| `selected` | 对象；节点选择统计信息 |
| `current` | 数字；当前到节点的连接数 |
| `total` | 数字；转发到节点的请求总数 |
| `last` | 字符串或数字；节点最后被选择的时间，
格式为 [日期](#api-date-format) |
| `max_conns` | 数字；配置的到节点的同时活动连接的 [最大](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) 数量（如果指定） |
| `responses` | 对象；响应统计信息 |
| `` | 数字；状态码为 (100-599) 的响应的非零数量 |
| `xxx` | 数字；其他状态码响应的非零数量 |
| `data` | 对象；数据统计信息 |
| `received` | 数字；从节点接收的字节总数 |
| `sent` | 数字；发送到节点的字节总数 |
| `health` | 对象；健康统计信息 |
| `fails` | 数字；与节点通信失败的尝试总数 |
| `unavailable` | 数字；由于达到 [max_fails](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails) 限制而导致节点变为 `unavailable` 的次数 |
| `downtime` | 数字；节点 `unavailable` 无法选择的总时间（以毫秒为单位） |
| `downstart` | 字符串或数字；节点变为 `unavailable` 的时间，
格式为 [日期](#api-date-format) |
| `header_time`
(PRO 1.3.0+) | 数字；从服务器接收响应头的平均时间（以毫秒为单位）；
参见 [response_time_factor (PRO)](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-response-time-factor) |
| `response_time`
(PRO 1.3.0+) | 数字；从服务器接收完整响应的平均时间（以毫秒为单位）；
参见 [response_time_factor (PRO)](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-response-time-factor) |
| `sid` | 字符串；上游组中服务器的 [配置 id](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#reresolve) |
| `keepalive` | 数字；当前缓存连接数 |
| `backup_switch` | 对象；包含活动备份逻辑的当前状态，
如果为上游配置了 [backup_switch (PRO)](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-backup-switch) 则存在 |
| `active` | 数字；当前用于负载均衡请求的活动组级别。
如果活动组是主组，则值为 0 |
| `timeout` | 数字；剩余等待时间（以毫秒为单位），
之后负载均衡器将重新检查较低级别组中的健康节点，
从主组开始，而不检查较高级别的组；
主组（级别 0）不显示 |
##### `health/probes` (PRO)
#### Versionchanged
在 1.2.0 版本发生变更: PRO
如果上游配置了 [upstream_probe (PRO)](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe) 探测，
`health` 对象还有一个 `probes` 子对象
用于存储服务器的健康探测计数器，
而 `state` 除了上表中列出的值外，
还可以是 `checking` 和 `unhealthy`：
```json
{
"192.168.16.4:80": {
"state": "unhealthy",
"...": "...",
"health": {
"...": "...",
"probes": {
"count": 10,
"fails": 10,
"last": "|sampledateshort|T09:56:07Z"
}
}
}
}
```
`state` 的 `checking` 值不计入 `downtime`，
表示配置了 `essential` 探测的服务器尚未被检查；
`unhealthy` 值表示服务器出现故障。
这两种状态都意味着服务器不包含在负载均衡中。
有关健康探测的详细信息，请参见 [upstream_probe](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe)。
`probes` 中的计数器：
| `count` | 数字；此服务器的探测总数 |
|-----------|-----------------------------------------------|
| `fails` | 数字；失败探测总数 |
| `last` | 字符串或数字；最后探测时间，
格式为 [日期](#api-date-format) |
##### `queue` (PRO)
#### Versionchanged
在 1.4.0 版本发生变更: PRO
如果为上游配置了 [请求队列](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-queue)，
上游对象还包含一个嵌套的 `queue` 对象，
其中包含请求队列计数器：
```json
{
"queue": {
"queued": 20112,
"waiting": 1011,
"dropped": 6031,
"timedout": 560,
"overflows": 13
}
}
```
计数器值在所有工作进程中求和：
| `queued` | 数字；进入队列的请求总数 |
|-------------|---------------------------|
| `waiting` | 数字；队列中当前的请求数 |
| `dropped` | 数字；因客户端过早关闭连接而从队列中移除的请求总数 |
| `timedout` | 数字；因超时而从队列中移除的请求总数 |
| `overflows` | 数字；队列溢出发生的总次数 |
### Stream 上游
要启用以下指标的收集，
请在 [upstream](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-upstream) 上下文中设置 [zone](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-zone) 指令，
例如：
```nginx
upstream upstream {
zone upstream 256k;
server backend.example.com service=_example._tcp resolve max_conns=5;
keepalive 4;
}
```
#### `/status/stream/upstreams/`
其中 是使用 [zone](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone) 指令配置的 [upstream](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) 的名称。
```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` | 对象；包含上游服务器组中各对等节点的指标，作为子对象，
其名称是对等节点地址的规范表示形式。
每个子对象的成员： |
|-----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `server` | 字符串；由 [server](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server) 指令设置的地址 |
| `service` | 字符串；在 [server](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server) 指令中指定的服务名称（如果已配置） |
| `backup` | 布尔值；备份服务器为 `true` |
| `weight` | 数字；为对等节点设置的 [权重](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server) |
| `state` | 字符串；对等节点的当前状态以及发送给它的请求：
- `busy`：表示发送到服务器的请求数
已达到 [max_conns](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server) 设置的限制，
不再向其发送新请求
- `down`：手动禁用，不发送请求
- `recovering`：根据 [slow_start](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-slow-start) 从故障中恢复，
随着时间推移发送越来越多的请求
- `unavailable`：达到 [max_fails](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-max-fails) 限制，
仅以 [fail_timeout](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-fail-timeout) 定义的间隔发送试探性客户端请求
- `up`：正常运行，照常发送请求
Angie PRO 中的附加状态：
- `checking`：配置为 `essential` 并正在检查中，
仅发送 [探测请求](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#s-u-upstream-probe)
- `draining`：类似于 `down`，
但来自先前绑定会话的请求
（通过 [sticky](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky)）仍会发送
- `unhealthy`：不可用，
仅发送 [探测请求](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#s-u-upstream-probe) |
| `selected` | 对象；选择此对等节点进行连接的统计信息 |
| `current` | 数字；当前到对等节点的连接数 |
| `total` | 数字；转发到对等节点的连接总数 |
| `last` | 字符串或数字；上次选择对等节点的时间，
格式为 [日期](#api-date-format) |
| `max_conns` | 数字；到对等节点的同时活动连接的 [最大](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server) 数量（如果已设置） |
| `data` | 对象；数据传输统计信息 |
| `received` | 数字；从对等节点接收的总字节数 |
| `sent` | 数字；发送到对等节点的总字节数 |
| `health` | 对象；对等节点健康统计信息 |
| `fails` | 数字；尝试到达对等节点失败的总次数 |
| `unavailable` | 数字；由于达到 [max_fails](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-max-fails) 值，对等节点变为 `unavailable` 的总次数 |
| `downtime` | 数字；对等节点处于 `unavailable` 状态（无法被选择）的总时间（以毫秒为单位） |
| `downstart` | 字符串或数字；对等节点上次变为 `unavailable` 的时间，
格式为 [日期](#api-date-format) |
| `connect_time` | 数字；与服务器建立连接的平均时间（以毫秒为单位）；
参见 [response_time_factor (PRO)](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-response-time-factor) 指令 |
| `first_byte_time` | 数字；从服务器接收第一个字节的平均时间（以毫秒为单位）；
参见 [response_time_factor (PRO)](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-response-time-factor) 指令 |
| `last_byte_time` | 数字；从服务器接收完整响应的平均时间（以毫秒为单位）；
参见 [response_time_factor (PRO)](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-response-time-factor) 指令 |
| `backup_switch`
(PRO 1.10.0+) | 对象；包含活动备份逻辑的当前状态，
如果为上游配置了 [backup_switch (PRO)](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-backup-switch) 则显示 |
| `active` | 数字；当前用于负载均衡的活动组的级别。
如果活动组是主组，则值为 0 |
| `timeout` | 数字；剩余等待时间（以毫秒为单位），
之后负载均衡器将重新检查较低级别组中的健康节点，
从主组开始，
而不检查较高级别的组；
主组（级别 0）不显示 |
#### Versionchanged
在 1.4.0 版本发生变更: PRO
在 Angie PRO 中，如果上游配置了 [upstream_probe (PRO)](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#s-u-upstream-probe) 探测，
`health` 对象还包含一个 `probes` 子对象，
用于存储服务器的健康探测计数器，
而 `state` 除了上表中列出的值外，
还可以是 `checking` 和 `unhealthy`：
```json
{
"192.168.16.4:80": {
"state": "unhealthy",
"...": "...",
"health": {
"...": "...",
"probes": {
"count": 2,
"fails": 2,
"last": "|sampledateshort|T11:03:54Z"
}
}
}
}
```
`state` 的 `checking` 值表示配置了 `essential` 参数探测的服务器尚未被检查；
`unhealthy` 值表示服务器不可用。
这两种状态还意味着服务器不包含在负载均衡中。
有关健康探测的详细信息，请参见 [upstream_probe](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#s-u-upstream-probe)。
`probes` 中的计数器：
| `count` | 数字；此服务器的探测总数 |
|-----------|------------------------------------------------|
| `fails` | 数字；失败的探测数 |
| `last` | 字符串或数字；上次探测的时间，
格式为 [日期](#api-date-format) |
## 动态配置 API (PRO)
该 API 包含一个 `/config` 节，可通过 `PUT`、`PATCH` 和 `DELETE` HTTP 请求
以 JSON 格式动态更新 Angie 的配置。
所有更新都是原子性的：新设置作为一个整体应用，
或者完全不应用。
出错时，Angie 会报告原因。
### `/config` 的子节
目前，`/config` 节中可用于 [HTTP](#api-config-http-upstreams-servers) 和 [stream](#api-config-stream-upstreams-servers) 模块的上游内各个服务器的配置；
可进行动态配置的设置数量正在稳步增加。
#### `/config/http/upstreams//servers/`
允许配置单个上游对等节点，
包括删除现有对等节点或添加新对等节点。
URI 路径参数：
| `` | 上游的名称；要通过 `/config` 进行配置，必须配置
[zone](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone) 指令，定义一个共享内存区域。 |
|----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `` | 上游中对等节点的名称，定义为
`@`，其中：
- `@` 是可选的服务名称，用于
SRV 记录解析。
- `` 是服务的域名（如果存在 `resolve`）
或其 IP 地址；可以在此定义可选的端口。 |
例如，以下配置：
```nginx
upstream backend {
server backend.example.com service=_http._tcp resolve;
server 127.0.0.1;
zone backend 1m;
}
```
允许以下对等节点名称：
```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/
```
此 API 子节允许设置 `weight`、`max_conns`、
`max_fails`、`fail_timeout`、`slow_start`、`backup`、`down` 和
`sid` 参数，如 [server](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) 中所述。
#### NOTE
这里没有单独的 `drain` (PRO) 参数；
要启用 `drain`，
将 `down` 设置为字符串值 `drain`：
```console
$ curl -X PUT -d \"drain\" \
http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com/down
```
示例：
```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": ""
}
```
实际可用的参数仅限于 [upstream](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) 当前负载均衡方法所支持的参数。
因此，如果上游配置了 `random` 方法：
```nginx
upstream backend {
zone backend 256k;
server backend.example.com resolve max_conns=5;
random;
}
```
您将无法添加定义了 `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
即使使用兼容的负载均衡方法，`backup` 参数
也只能在添加新对等节点时设置。
#### `/config/stream/upstreams//servers/`
允许配置单个上游对等节点，
包括删除现有对等节点或添加新对等节点。
URI 路径参数：
| `` | `upstream` 块的名称；
要通过 `/config` 进行配置，
必须配置 [zone](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-zone) 指令，
定义一个共享内存区域。 |
|----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `` | 上游中对等节点的名称，定义为
`@`，其中：
- `@` 是可选的服务名称，用于
SRV 记录解析。
- `` 是服务的域名（如果存在 `resolve`）
或其 IP 地址；可以在此定义可选的端口。 |
例如，以下配置：
```nginx
upstream backend {
server backend.example.com:8080 service=_example._tcp resolve;
server 127.0.0.1:12345;
zone backend 1m;
}
```
允许以下对等节点名称：
```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/
```
此 API 子部分允许设置 `weight`、
`max_conns`、`max_fails`、`fail_timeout`、`slow_start`、`backup` 和
`down` 参数，如 [server](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server) 中所述。
#### NOTE
这里没有单独的 `drain`（PRO）参数；
要启用 :samp:`drain` 模式，
将 `down` 设置为字符串值 `drain`：
```console
$ curl -X PUT -d \"drain\" \
http://127.0.0.1/config/stream/upstreams/backend/servers/backend.example.com/down
```
示例：
```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,
}
```
实际可用的参数仅限于 [upstream](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-upstream) 当前负载均衡方法所支持的参数。
因此，如果上游配置了 `random` 方法：
```nginx
upstream backend {
zone backend 256k;
server backend.example.com resolve max_conns=5;
random;
}
```
您将无法添加定义了 `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
即使使用兼容的负载均衡方法，`backup` 参数
也只能在添加新对等节点时设置。
删除对等节点时，您可以设置
`connection_drop=` 参数（PRO）来覆盖
[proxy_connection_drop](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-connection-drop) 设置：
```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 方法
让我们以下面的上游配置为例，来考虑适用于本节的每个 HTTP 方法的语义：
```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
`GET` HTTP 方法查询 `/config` 中任何现有路径上的实体，
就像它对其他 API 部分所做的那样。
例如，
`/config/http/upstreams/backend/servers/`
上游服务器分支支持以下查询：
```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
```
您可以使用 `defaults=on` 参数获取默认参数值：
```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
`PUT` HTTP 方法在指定路径创建一个新的 JSON 实体，
或\*完全\*替换现有实体。
例如，要向 `backend` 上游中的 `backend.example.com` 服务器
添加之前未指定的 `max_fails` 参数：
```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."
}
```
验证更改：
```console
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com
```
```json
{
"max_conns": 5,
"max_fails": 2
}
```
#### DELETE
`DELETE` HTTP 方法删除指定路径上\*先前定义\*的设置；
这样做时，如果存在默认值，它会恢复默认值。
例如，要删除 `backend` 上游中 `backend.example.com` 服务器
之前修改的 `max_fails` 参数：
```console
$ curl -X DELETE \
http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com/max_fails
```
```json
{
"success": "Reset",
"description": "Configuration API entity \"/config/http/upstreams/backend/servers/backend.example.com/max_fails\" was reset to default."
}
```
使用 `defaults=on` 参数验证更改：
```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": ""
}
```
`max_fails` 参数已恢复为其默认值。
删除服务器时，您可以设置 `connection_drop=` 参数
（PRO）来覆盖 [proxy_connection_drop](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-connection-drop)、[grpc_connection_drop](https://cn.angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-connection-drop)、
[fastcgi_connection_drop](https://cn.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-connection-drop)、[scgi_connection_drop](https://cn.angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-connection-drop) 和
[uwsgi_connection_drop](https://cn.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-connection-drop) 设置：
```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
`PATCH` HTTP 方法在指定路径创建一个新实体，
或部分替换或补充现有实体
（[RFC 7386](https://datatracker.ietf.org/doc/html/rfc7396)），
通过在其有效负载中提供 JSON 定义。
该方法的操作如下：如果新定义中的实体
存在于配置中，则会被覆盖；否则，它们会被添加。
例如，要更改 `backend` 上游中 `backend.example.com` 服务器的
`down` 参数，同时保持其余部分不变：
```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."
}
```
验证更改：
```console
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com
```
```json
{
"max_conns": 5,
"down": true
}
```
请注意，随 `PATCH` 请求提供的 JSON 对象\*被合并\*到现有对象中，
而不是像 `PUT` 那样完全替换它。
`null` 值是一种特殊情况；它们用于在此类合并期间
删除特定的配置项。
#### NOTE
此删除与 `DELETE` 相同；
特别是，它会恢复默认值。
例如，要删除之前添加的 `down` 参数
并同时更新 `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."
}
```
验证更改：
```console
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com
```
```json
{
"max_conns": 6
}
```
提供了 `null` 值的 `down` 参数已被删除；
`max_conns` 值已更新。