# API Модуль `API` реализует HTTP RESTful интерфейс для получения базовой информации о веб-сервере в формате JSON, а также [статистики](#metrics) по клиентским соединениям, зонам разделяемой памяти, DNS-запросам, HTTP-запросам, кэшу HTTP-ответов, сессиям модуля [stream](https://angie.software//angie/docs/configuration/modules/stream/index.md#stream-core) и зонам модулей [limit_conn http](https://angie.software//angie/docs/configuration/modules/http/http_limit_conn.md#http-limit-conn), [limit_conn stream](https://angie.software//angie/docs/configuration/modules/stream/stream_limit_conn.md#stream-limit-conn), [limit_req](https://angie.software//angie/docs/configuration/modules/http/http_limit_req.md#http-limit-req) и [http upstream](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream). Интерфейс принимает HTTP-методы `GET` и `HEAD`; запрос с другим методом вызовет ошибку: ```json { "error": "MethodNotAllowed", "description": "The POST method is not allowed for the requested API element \"/\"." } ``` В Angie PRO в этом интерфейсе есть раздел [динамической конфигурации](#api-config), позволяющий менять настройки без перезагрузки конфигурации или перезапуска; сейчас доступна конфигурация отдельных серверов в составе [upstream](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream). ## Директивы ### api | [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `api` путь; | |------------------------------------------------------------------------------------------|---------------| | По умолчанию | — | | [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | location | Включает HTTP RESTful интерфейс в `location`. Параметр путь является обязательным. Подобно директиве [alias](https://angie.software//angie/docs/configuration/modules/http/index.md#alias), задает путь для замены указанного в `location`, но по дереву API, а не файловой системы. Если указан в префиксном `location`: ```nginx location /stats/ { api /status/http/server_zones/; } ``` часть URI запроса, совпадающая с префиксом /stats/, будет заменена на путь, указанный в параметре путь: /status/http/server_zones/. К примеру, по запросу /stats/foo/ будет доступен элемент API `/status/http/server_zones/foo/`. Допускается использование переменных: api /status/$module/server_zones/$name/ и использование внутри regex location: ```nginx location ~^/api/([^/]+)/(.*)$ { api /status/http/$1_zones/$2; } ``` Здесь параметр путь определяет полный путь к элементу API; так, из запроса к `/api/location/data/` будут выделены переменные: ```console $1 = "location" $2 = "data/" ``` И конечный запрос будет иметь вид `/status/http/location_zones/data/`. #### NOTE В Angie PRO можно разделить [API динамической конфигурации](#api-config) и неизменяемый [API статуса](#metrics), отражающий текущее состояние: ```nginx location /config/ { api /config/; } location /status/ { api /status/; } ``` Также параметр путь позволяет управлять доступом к API: ```nginx location /status/ { api /status/; allow 127.0.0.1; deny all; } ``` Или же: ```nginx location /blog/requests/ { api /status/http/server_zones/blog/requests/; auth_basic "blog"; auth_basic_user_file conf/htpasswd; } ``` #### NOTE Если `api` стоит в `location` с косой чертой в конце префикса (например, `location /name/`), и при этом в директиве [auto_redirect](https://angie.software//angie/docs/configuration/modules/http/index.md#auto-redirect) указано `default`, запросы без косой черты в конце будут перенаправляться (`/name -> /name/`). ### api_config_files | [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `api_config_files` `on` | `off`; | |------------------------------------------------------------------------------------------|------------------------------------| | По умолчанию | off | | [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | location | Включает или отключает добавление объекта `config_files`, перечисляющего содержимое всех файлов конфигурации Angie, загруженных сейчас экземпляром сервера, в состав раздела API [/status/angie/](#status-angie). Например, при такой конфигурации: ```nginx location /status/ { api /status/; api_config_files on; } ``` Запрос к `/status/angie/` возвращает приблизительно следующее: ```json { "version":"|version|", "address":"192.168.16.5", "generation":1, "load_time":"|sampledateshort|T12:58:39.789Z", "config_files": { "/etc/angie/angie.conf": "...", "/etc/angie/mime.types": "..." } } ``` По умолчанию вывод отключен, так как файлы конфигурации могут содержать особо чувствительные, конфиденциальные сведения. ## Метрики Angie публикует статистику использования в разделе API `/status/`; открыть доступ к ней можно, задав соответствующий `location`. Полный доступ: ```nginx location /status/ { api /status/; } ``` Пример частичного доступа, уже приводившийся выше: ```nginx location /stats/ { api /status/http/server_zones/; } ``` ### Пример конфигурации С конфигурацией, включающей `location /status/`, зоны `resolver`, `http` в `upstream`, `http server`, `location`, `cache`, `limit_conn` в `http` и `limit_req`: ```nginx http { resolver 127.0.0.53 status_zone=resolver_zone; proxy_cache_path /var/cache/angie/cache keys_zone=cache_zone:2m; limit_conn_zone $binary_remote_addr zone=limit_conn_zone:10m; limit_req_zone $binary_remote_addr zone=limit_req_zone:10m rate=1r/s; upstream upstream { zone upstream 256k; server backend.example.com service=_example._tcp resolve max_conns=5; keepalive 4; } server { server_name www.example.com; listen 443 ssl; status_zone http_server_zone; proxy_cache cache_zone; proxy_cache_valid 200 10m; access_log /var/log/access.log main; location / { root /usr/share/angie/html; status_zone location_zone; limit_conn limit_conn_zone 1; limit_req zone=limit_req_zone burst=5; } location /status/ { api /status/; allow 127.0.0.1; deny all; } } } ``` В ответ на запрос `curl https://www.example.com/status/` Angie возвращает: ### дерево JSON ```json { "angie": { "version":"|version|", "address":"192.168.16.5", "generation":1, "load_time":"|sampledateshort|T12:58:39.789Z" }, "connections": { "accepted":2257, "dropped":0, "active":3, "idle":1 }, "slabs": { "cache_zone": { "pages": { "used":2, "free":506 }, "slots": { "64": { "used":1, "free":63, "reqs":1, "fails":0 }, "512": { "used":1, "free":7, "reqs":1, "fails":0 } } }, "limit_conn_zone": { "pages": { "used":2, "free":2542 }, "slots": { "64": { "used":1, "free":63, "reqs":74, "fails":0 }, "128": { "used":1, "free":31, "reqs":1, "fails":0 } } }, "limit_req_zone": { "pages": { "used":2, "free":2542 }, "slots": { "64": { "used":1, "free":63, "reqs":1, "fails":0 }, "128": { "used":2, "free":30, "reqs":3, "fails":0 } } } }, "http": { "server_zones": { "http_server_zone": { "ssl": { "handshaked":4174, "reuses":0, "timedout":0, "failed":0 }, "requests": { "total":4327, "processing":0, "discarded":8 }, "responses": { "200":4305, "302":12, "404":4 }, "data": { "received":733955, "sent":59207757 } } }, "location_zones": { "location_zone": { "requests": { "total":4158, "discarded":0 }, "responses": { "200":4157, "304":1 }, "data": { "received":538200, "sent":177606236 } } }, "caches": { "cache_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 } } }, "limit_conns": { "limit_conn_zone": { "passed":73, "skipped":0, "rejected":0, "exhausted":0 } }, "limit_reqs": { "limit_req_zone": { "passed":54816, "skipped":0, "delayed":65, "rejected":26, "exhausted":0 } }, "upstreams": { "upstream": { "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 } } }, "resolvers": { "resolver_zone": { "queries": { "name":442, "srv":2, "addr":0 }, "responses": { "success":440, "timedout":1, "format_error":0, "server_failure":1, "not_found":1, "unimplemented":0, "refused":1, "other":0 } } } } ``` Набор метрик можно запросить по отдельной ветви JSON, построив соответствующий запрос. Например: ```console $ curl https://www.example.com/status/angie $ curl https://www.example.com/status/connections $ curl https://www.example.com/status/slabs $ curl https://www.example.com/status/slabs/<зона>/slots $ curl https://www.example.com/status/slabs/<зона>/slots/64 $ curl https://www.example.com/status/http/ $ curl https://www.example.com/status/http/acme_clients $ curl https://www.example.com/status/http/acme_clients/<клиент> $ curl https://www.example.com/status/http/metric_zones $ curl https://www.example.com/status/http/metric_zones/<зона>/metrics $ curl https://www.example.com/status/http/server_zones $ curl https://www.example.com/status/http/server_zones/ $ curl https://www.example.com/status/http/server_zones//ssl ``` #### NOTE По умолчанию модуль использует для дат строки в формате ISO 8601; чтобы вместо этого использовать целочисленный формат эпохи UNIX, добавьте параметр `date=epoch` к строке запроса: ```console $ curl https://www.example.com/status/angie/load_time "2024-04-01T00:59:59+01:00" $ curl https://www.example.com/status/angie/load_time?date=epoch 1711929599 ``` ### Состояние сервера #### `/status/angie` ```json { "version": "|version|", "build_time": "|sampledateshort|T16:05:43.805Z", "address": "192.168.16.5", "generation": 1, "load_time": "|sampledateshort|T16:15:43.805Z" "config_files": { "/etc/angie/angie.conf": "...", "/etc/angie/mime.types": "..." } } ``` | `version` | Строка; версия запущенного сервера Angie | |----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `build` | Строка; сборка, если указана при компиляции | | `build_time` | Строка; время сборки исполняемого файла Angie
в формате [даты](#api-date-format) | | `address` | Строка; адрес сервера, принявшего запрос к API | | `generation` | Число; версия (поколение) конфигурации,
отсчитываемая с последнего запуска Angie | | `load_time` | Строка; время последней перезагрузки конфигурации
в формате [даты](#api-date-format);
строковые значения даются с миллисекундным разрешением | | `config_files` | Объект; его члены — абсолютные имена всех файлов конфигурации Angie,
загруженных сейчас экземпляром сервера,
а их значения — строковые представления содержимого файлов, например:

```json
{
"/etc/angie/angie.conf": "server {\n listen 80;\n # ...\n\n}\n"
}
```

#### WARNING
Объект `config_files` есть в `/status/angie/`,
только если включена директива
[api_config_files](#a-api-config-files). | #### `/status/angie/license` (PRO) ```json { "path": "/etc/angie/license.pem", "status": "valid", "owner": "Example Corp", "days_left": 30, "since": "2024-01-01", "until": "2025-01-01", "limits": { "worker_processes": 16, "worker_connections": 65535 } } ``` | `path` | Строка; полный путь к файлу лицензии | |-------------|-----------------------------------------------------------------------------------------------------------------------------------------------------| | `status` | Строка; статус лицензии: `missing`, `invalid`, `valid`,
`grace`, `expired` или `pending` | | `owner` | Строка; владелец лицензии из subject сертификата | | `days_left` | Число; дни до смены состояния лицензии. Отрицательное значение означает,
что лицензия истекла, и значение показывает число дней после истечения | | `since` | Строка; дата начала действия лицензии | | `until` | Строка; дата окончания действия лицензии | | `limits` | Объект; лимиты лицензии для текущего экземпляра | ### Соединения #### `/status/connections` ```json { "accepted": 2257, "dropped": 0, "active": 3, "idle": 1 } ``` | `accepted` | Число; суммарное количество принятых клиентских соединений | |--------------|----------------------------------------------------------------| | `dropped` | Число; суммарное количество сброшенных клиентских соединений | | `active` | Число; текущее количество активных клиентских соединений | | `idle` | Число; текущее количество бездействующих клиентских соединений | ### Зоны разделяемой памяти с распределением slab #### `/status/slabs/<зона>` Статистика для зон разделяемой памяти с [распределением slab](https://ru.wikipedia.org/wiki/Slab), таких как [limit_conn](#limit-conn), [limit_req](#limit-req) и [HTTP cache](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache): ```nginx limit_conn_zone $binary_remote_addr zone=limit_conn_zone:10m; limit_req_zone $binary_remote_addr zone=limit_req_zone:10m rate=1r/s; proxy_cache cache_zone; proxy_cache_valid 200 10m; ``` В указанной таким образом зоне разделяемой памяти будет собираться следующая статистика: | `pages` | Объект; статистика по страницам памяти | |-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `used` | Число; текущее количество используемых страниц памяти | | `free` | Число; текущее количество свободных страниц памяти | | `slots` | Объект; статистика по слотам памяти, по каждому из размеров. `slots` содержит данные по размеру слота памяти ( `8`, `16`, `32`, и т.д., вплоть до половины размера страницы памяти в байтах) | | `used` | Число; текущее количество используемых слотов памяти заданного размера | | `free` | Число; текущее количество свободных слотов памяти заданного размера | | `reqs` | Число; суммарное количество попыток выделения памяти указанного размера | | `fails` | Число; количество неудавшихся попыток выделения памяти указанного размера | Пример: ```json { "pages": { "used": 2, "free": 506 }, "slots": { "64": { "used": 1, "free": 63, "reqs": 1, "fails": 0 } } ``` ### DNS-запросы к резолверу #### `/status/resolvers/<зона>` Для сбора статистики в директиве [resolver](https://angie.software//angie/docs/configuration/modules/http/index.md#resolver) нужно задать параметр `status_zone` ([HTTP](https://angie.software//angie/docs/configuration/modules/http/index.md#resolver-status) или [Stream](https://angie.software//angie/docs/configuration/modules/stream/index.md#s-resolver-status)): ```nginx resolver 127.0.0.53 status_zone=resolver_zone; ``` В указанной таким образом зоне разделяемой памяти будет собираться следующая статистика: | `queries` | Объект; статистика запросов | |------------------|------------------------------------------------------------------------------------| | `name` | Число; количество запросов на преобразование имен в адреса
(A- и AAAA-запросы) | | `srv` | Число; количество запросов на преобразование сервисов в адреса
(SRV запросы) | | `addr` | Число; количество запросов на преобразование адресов в имена
(PTR-запросы) | | `responses` | Объект; статистика ответов | | `success` | Число; количество успешных ответов | | `timedout` | Число; количество запросов, не дождавшихся ответа | | `format_error` | Число; количество ответов с кодом 1 (Format Error) | | `server_failure` | Число; количество ответов с кодом 2 (Server Failure) | | `not_found` | Число; количество ответов с кодом 3 (Name Error) | | `unimplemented` | Число; количество ответов с кодом 4 (Not Implemented) | | `refused` | Число; количество ответов с кодом 5 (Refused) | | `other` | Число; количество запросов, завершенных с другим ненулевым кодом | | `sent` | Объект; статистика отправленных DNS-запросов | | `a` | Число; количество запросов типа A | | `aaaa` | Число; количество запросов типа AAAA | | `ptr` | Число; количество запросов типа PTR | | `srv` | Число; количество запросов типа SRV | #### NOTE `queries` и `responses` учитывают каждый запрос на разрешение имён, который Angie выполняет внутренне, включая ответы из TTL-кэша. `sent` учитывает пакеты, фактически отправленные на сервер имён; разница между ними отражает обращения к кэшу. Коды ответов описаны в [RFC 1035](https://datatracker.ietf.org/doc/html/rfc1035.html), часть [4.1.1](https://datatracker.ietf.org/doc/html/rfc1035.html#section-4.1.1). Различные типы DNS-записей описаны в [RFC 1035](https://datatracker.ietf.org/doc/html/rfc1035.html), [RFC 2782](https://datatracker.ietf.org/doc/html/rfc2782.html) и [RFC 3596](https://datatracker.ietf.org/doc/html/rfc3596.html). Пример: ```json { "queries": { "name": 442, "srv": 2, "addr": 0 }, "responses": { "success": 440, "timedout": 1, "format_error": 0, "server_failure": 1, "not_found": 1, "unimplemented": 0, "refused": 1, }, "sent": { "a": 185, "aaaa": 245, "srv": 2, "ptr": 12 } } ``` ### HTTP server и location #### `/status/http/server_zones/<зона>` Для сбора статистики в контексте [server](https://angie.software//angie/docs/configuration/modules/http/index.md#server) нужно задать директиву [status_zone](https://angie.software//angie/docs/configuration/modules/http/index.md#status-zone): ```nginx server { ... status_zone server_zone; } ``` Для группировки метрик по пользовательскому значению используйте альтернативный синтаксис. В этом примере метрики агрегируются по [$host](https://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-сессий во время SSL-рукопожатий | | `timedout` | Число; суммарное количество SSL-рукопожатий с истекшим таймаутом | | `failed` | Число; суммарное количество неуспешных SSL-рукопожатий | | `requests` | Объект; метрики запросов | | `total` | Число; суммарное количество клиентских запросов | | `processing` | Число; текущее количество обслуживаемых клиентских запросов | | `discarded` | Число; суммарное количество запросов завершенных без отправки ответа | | `responses` | Объект; метрики ответов | | `` | Число; ненулевое количество ответов со статусом (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](https://angie.software//angie/docs/configuration/modules/http/index.md#location) или [if в location](https://angie.software//angie/docs/configuration/modules/http/http_rewrite.md#if) нужно задать директиву [status_zone](https://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://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/<зона>` Пользовательские метрики, созданные директивами [metric_zone](https://angie.software//angie/docs/configuration/modules/http/http_metric.md#metric-zone) или [metric_complex_zone](https://angie.software//angie/docs/configuration/modules/http/http_metric.md#metric-complex-zone) в контексте `http`. Метрики обновляются через директиву [metric](https://angie.software//angie/docs/configuration/modules/http/http_metric.md#id5) или переменные модуля. | `discarded` | Число; количество отброшенных записей метрик из-за нехватки памяти в зоне. | |---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `metrics` | Объект; метрики по ключам. Для зон с одной метрикой значения — числа.
Для сложных зон значения — объекты с именами метрик. Для режима
`histogram` значения — объекты с именами бакетов. | Если задан `discard_key` и часть записей была истекшей, агрегированные метрики доступны под этим ключом. Пример: ```json { "discarded": 3, "metrics": { "example.com": { "count": 42, "max": 8 } "expired": { "count": 10, "max": 3.2 } } } ``` ### Stream server #### `/status/stream/server_zones/<зона>` Для сбора статистики в контексте [server](https://angie.software//angie/docs/configuration/modules/stream/index.md#s-server) нужно задать директиву [status_zone](https://angie.software//angie/docs/configuration/modules/stream/index.md#s-status-zone): ```nginx server { ... status_zone server_zone; } ``` Для группировки метрик по пользовательскому значению используйте альтернативный синтаксис. В этом примере метрики агрегируются по [$host](https://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-сессий во время SSL-рукопожатий | | `timedout` | Число; суммарное количество SSL-рукопожатий с истекшим таймаутом | | `failed` | Число; суммарное количество неуспешных SSL-рукопожатий | | `connections` | Объект; метрики соединений | | `total` | Число; суммарное количество клиентских соединений | | `processing` | Число; текущее количество обслуживаемых клиентских соединений | | `discarded` | Число; суммарное количество клиентских соединений,
завершенных без создания сессии | | `passed` | Число; суммарное количество клиентских соединений,
переданных на другой прослушивающий порт директивами `pass` | | `sessions` | Объект; метрики сессий | | `success` | Число; количество сессий, завершенных с кодом 200, что означает успешное завершение | | `invalid` | Число; количество сессий, завершенных с кодом 400, случается, когда сервер не может прочитать данные от клиента, например, заголовок PROXY protocol | | `forbidden` | Число; количество сессий, завершенных с кодом 403, когда доступ запрещен, например, ограничен для определенного адреса клиента | | `internal_error` | Число; количество сессий, завершенных с кодом 500, внтуренняя ошибка сервера | | `bad_gateway` | Число; количество сессий, завершенных с кодом 502, Bad Gateway, если, например, сервер в upstream недоступен или не может быть выбран | | `service_unavailable` | Число; количество сессий, завершенных с кодом 503, Service Unavailable, если, например, доступ ограничен числом входящих соединений | | `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 caches ```nginx proxy_cache cache_zone; proxy_cache_valid 200 10m; ``` #### `/status/http/caches/` Для каждой зоны, сконфигурированной в [proxy_cache](https://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` | Логическое значение; `true`, пока загрузчик кэша подгружает данные с диска | | `hit` | Объект; метрики возвращенных из кэша ответов ([proxy_cache_valid](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-valid)) | | `responses` | Число; суммарное количество ответов, прочитанных из кэша | | `bytes` | Число; суммарное количество байт, прочитанных из кэша | | `stale` | Объект; метрики просроченных ответов, возвращенных из кэша ([proxy_cache_use_stale](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-use-stale)) | | `responses` | Число; суммарное количество ответов, прочитанных из кэша | | `bytes` | Число; суммарное количество байт, прочитанных из кэша | | `updating` | Объект; метрики просроченных ответов, возвращенных из кэша, пока данные в кэше обновляются ([proxy_cache_use_stale](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-use-stale) updating) | | `responses` | Число; суммарное количество ответов, прочитанных из кэша | | `bytes` | Число; суммарное количество байт, прочитанных из кэша | | `revalidated` | Объект; метрики просроченных и ревалидированных ответов, возвращенных из кэша ([proxy_cache_revalidate](https://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://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://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-path) отдельные шарды указываются как объекты-члены в объекте `shards`: | `shards` | Объект; его члены — отдельные шарды | |------------|----------------------------------------------------------------------------| | `` | Объект; представляет отдельный шард, а имя объекта — путь кэша | | `size` | Число; текущий размер шарда | | `max_size` | Число; максимальный размер шарда, если задан в конфигурации | | `cold` | Логическое значение; `true`, пока загрузчик кэша подгружает данные с диска | ```json { "name_zone": { "shards": { "/path/to/shard1": { "size": 0, "cold": false }, "/path/to/shard2": { "size": 0, "cold": false } } } ``` ### ACME-клиенты #### `/status/http/acme_clients/<клиент>` Для каждого настроенного [acme_client](https://angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) в блоке `http` возвращается текущее состояние клиента и сертификата: ```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/<зона>` Каждая из сконфигурированных зон: [limit_conn в http](#limit-conn) или [limit_conn в stream](https://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) cодержит следующие данные: ```json { "passed": 54816, "skipped": 0, "delayed": 65, "rejected": 26, "exhausted": 0 } ``` | `passed` | Число; суммарное количество проксированых соединений | |-------------|-----------------------------------------------------------------------------------------------| | `skipped` | Число; суммарное количество соединений, переданных с нулевым или превосходящим 255 байт | | `delayed` | Число; суммарное количество задержанных соединений | | `rejected` | Число; суммарное количество сброшенных соединений | | `exhausted` | Число; суммарное количество соединений, сброшенных из-за переполнения хранилища зоны | ### HTTP upstream Чтобы включить сбор следующих метрик, задайте директиву [zone](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone) в контексте [upstream](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream), например: ```nginx upstream upstream { zone upstream 256k; server backend.example.com service=_example._tcp resolve max_conns=5; keepalive 4; } ``` #### `/status/http/upstreams/` где — имя [апстрима](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream), в конфигурации которого указана директива [zone](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone). ```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://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) | | `service` | Строка; имя сервиса, указанное в директиве [server](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server), если сконфигурировано | | `backup` | Логическое значение; `true` для backup серверов | | `weight` | Число; сконфигурированный [weight](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) | | `state` | Строка; текущее состояние пира, и какие запросы ему отправляются:

- `busy`: указывает, что число запросов на сервер
достигло ограничения, заданного [max_conns](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server),
и новые запросы на него не отправляются;
- `down`: отключен вручную, не отправляются никакие запросы;
- `recovering`: восстанавливается после сбоя
согласно [slow_start](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#slow-start),
отправляется все больше запросов;
- `unavailable`: достиг предела [max_fails](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails),
отправляются пробные клиентские запросы
с интервалом [fail_timeout](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#fail-timeout);
- `up`: работоспособен, запросы отправляются как обычно;

Дополнительные состояния в Angie PRO:

- `checking`: настроен как `essential` и проверяется,
отправляются только [проверочные запросы](https://angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe);
- `draining`: аналогичен `down`,
но отправляются запросы сессий,
привязанных ранее через [sticky](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky);
- `unhealthy`: неработающий,
отправляются только [проверочные запросы](https://angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe). | | `selected` | Объект; статистика выбора пиров | | `current` | Число; текущее количество соединений к пиру | | `total` | Число; общее количество запросов переданных пиру | | `last` | Строка или число; время последнего выбора пира
в формате [даты](#api-date-format) | | `max_conns` | Число; [максимальное](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) количество одновременных активных соединений к пиру, если сконфигурировано | | `responses` | Объект; статистика ответов | | `` | Число; ненулевое количество ответов со статусом (100-599) | | `xxx` | Число; ненулевое количество ответов с другим кодом статуса | | `data` | Объект; метрики данных | | `received` | Число; суммарное количество байт, полученное от пира | | `sent` | Число; суммарное количество байт, отправленное пиру | | `health` | Объект; статистика по состоянию пира | | `fails` | Число; общее количество неудачных попыток работы с пиром | | `unavailable` | Число; столько раз пир становился `unavailable` по достижении значения [max_fails](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails) | | `downtime` | Число; суммарное время (в миллисекундах), в течение которого пир был недоступен для выбора как `unavailable` | | `downstart` | Строка или число; время, когда пир стал `unavailable`,
в формате [даты](#api-date-format) | | `header_time`
| Число; среднее время (в миллисекундах)
получения заголовков ответа от сервера;
см. директиву [response_time_factor (PRO)](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-response-time-factor) | | `response_time`
| Число; среднее время (в миллисекундах) получения ответа от сервера;
см. директиву [response_time_factor (PRO)](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-response-time-factor) | | `sid` | Строка; [id сервера](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#reresolve), указанный в конфигурации апстрима | | `keepalive` | Число; текущее количество кэшированных соединений | | `backup_switch` | Объект; содержит текущее состояние логики активного резервирования,
присутствует, если для апстрима настроен [backup_switch (PRO)](https://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://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" } } } } ``` Значение `checking` у `state` не учитывается в `downtime` и означает, что сервер, проверка которого настроена с параметром `essential`, еще не проверялся; значение `unhealthy` — что сервер неработающий. Оба эти состояния также означают, что сервер не участвует в балансировке. Детали проверок см. в описании [upstream_probe](https://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://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 Чтобы включить сбор следующих метрик, задайте директиву [zone](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-zone) в контексте [upstream](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-upstream), например: ```nginx upstream upstream { zone upstream 256k; server backend.example.com service=_example._tcp resolve max_conns=5; keepalive 4; } ``` #### `/status/stream/upstreams/` Здесь — имя [апстрима](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream), в конфигурации которого использована директива [zone](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone). ```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://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server) | | `service` | Строка; имя сервиса, если оно указано в директиве [server](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server) | | `backup` | Логическое значение; `true` для запасных серверов | | `weight` | Число; заданный для пира [вес](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server) | | `state` | Строка; текущее состояние пира, и какие запросы ему отправляются:

- `busy`: указывает, что число запросов на сервер
достигло ограничения, заданного [max_conns](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server),
и новые запросы на него не отправляются;
- `down`: отключен вручную, не отправляются никакие запросы;
- `recovering`: восстанавливается после сбоя
согласно [slow_start](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-slow-start),
отправляется все больше запросов;
- `unavailable`: достиг предела [max_fails](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-max-fails),
отправляются пробные клиентские запросы
с интервалом [fail_timeout](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-fail-timeout);
- `up`: работоспособен, запросы отправляются как обычно.

Дополнительные состояния в Angie PRO:

- `checking`: настроен как `essential` и проверяется,
отправляются только [проверочные запросы](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#s-u-upstream-probe);
- `draining`: аналогичен `down`,
но отправляются запросы сессий,
привязанных ранее через [sticky](https://angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky);
- `unhealthy`: неработающий,
отправляются только [проверочные запросы](https://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://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server)
количество одновременных активных подключений к пиру, если оно задано | | `data` | Объект; статистика передачи данных | | `received` | Число; общее количество байт, полученное от пира | | `sent` | Число; общее количество байт, отправленное пиру | | `health` | Объект; статистика по состоянию пира | | `fails` | Число; общее количество неудачных попыток связаться с пиром | | `unavailable` | Число; общее количество переходов в состояние `unavailable`
по достижении значения [max_fails](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-max-fails) | | `downtime` | Число; общее время в миллисекундах,
в течение которого пир находился в состоянии `unavailable`
(недоступен для выбора) | | `downstart` | Строка или число; время, когда пир последний раз стал `unavailable`,
в формате [даты](#api-date-format) | | `connect_time`
| Число; среднее время (в миллисекундах)
установления соединения с сервером;
см. директиву [response_time_factor (PRO)](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-response-time-factor) | | `first_byte_time`
| Число; среднее время (в миллисекундах)
получения первого байта ответа от сервера;
см. директиву [response_time_factor (PRO)](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-response-time-factor) | | `last_byte_time`
| Число; среднее время (в миллисекундах)
получения полного ответа от сервера;
см. директиву [response_time_factor (PRO)](https://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://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://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" } } } } ``` Значение `checking` у `state` означает, что сервер, проверка которого настроена с параметром `essential`, еще не проверялся; значение `unhealthy` — что сервер неработающий. Оба эти состояния также означают, что сервер не участвует в балансировке. Детали проверок см. в описании [upstream_probe](https://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`, позволяющий динамически менять конфигурацию Angie в формате JSON с помощью HTTP-запросов `PUT`, `PATCH` и `DELETE`. Все изменения атомарны: новые настройки применяются целиком либо не применяются вовсе. При ошибке Angie сообщит, в чем причина. ### Подразделы `/config` Cейчас в разделе `/config` доступна настройка отдельных серверов в составе апстримов для модулей [HTTP](#api-config-http-upstreams-servers) и [stream](#api-config-stream-upstreams-servers); число настроек, к которым применима динамическая конфигурация, планомерно увеличивается. #### `/config/http/upstreams//servers/<имя>` Позволяет настраивать отдельные серверы в составе апстрима, в том числе добавлять новые и удалять настроенные. Параметры в составе пути URI: | `` | Имя блока `upstream`;
чтобы настраивать его через `/config`,
в нем должна быть задана директива [zone](https://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://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": "" } ``` Фактически доступны будут только те параметры, которые поддерживает текущий метод балансировки нагрузки [апстрима](https://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://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://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server). #### NOTE Отдельного параметра `drain` (PRO) здесь нет; включить режим `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, } ``` Фактически доступны будут только те параметры, которые поддерживает текущий метод балансировки нагрузки [апстрима](https://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://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 HTTP-метод `GET` позволяет запросить сущность по любому существующему пути в пределах `/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 HTTP-метод `PUT` позволяет создать новую JSON-сущность по указанному пути или *полностью* заменить существующую. Например, чтобы добавить не заданный ранее параметр `max_fails` у сервера `backend.example.com` в апстриме `backend`: ```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 HTTP-метод `DELETE` удаляет *ранее заданные* настройки по указанному пути; при этом восстанавливаются значения по умолчанию, если они есть. Например, чтобы удалить измененный ранее параметр `max_fails` у сервера `backend.example.com` в апстриме `backend`: ```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." } ``` Проверим изменения с аргументом `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://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-connection-drop), [grpc_connection_drop](https://angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-connection-drop), [fastcgi_connection_drop](https://angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-connection-drop), [scgi_connection_drop](https://angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-connection-drop) и [uwsgi_connection_drop](https://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 HTTP-метод `PATCH` позволяет создать новую сущность по указанному пути либо частично заменить или дополнить существующую ([RFC 7386](https://datatracker.ietf.org/doc/html/rfc7396)), отправив в данных JSON-определение. Метод работает так: если сущности, указанные в новом определении, уже есть в конфигурации, они будут перезаписаны; если их нет, то они будут добавлены. Например, чтобы поменять значение параметра `down` у сервера `backend.example.com` в апстриме `backend`, оставив прочее без изменений: ```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 } ``` Параметр `down`, для которого было передано значение `null`, удален; значение `max_conns` изменено.