Модуль API
#
Добавлено в версии 1.0.0.
Модуль API
реализует HTTP RESTful интерфейс для получения базовой информации о веб-сервере в формате JSON, а также статистики по клиентским соединениям, зонам разделяемой памяти, DNS-запросам, HTTP-запросам, кэшу HTTP-ответов, сессиям модуля stream и зонам модулей limit_conn http, limit_conn stream, limit_req и http upstream.
API принимает GET и HEAD HTTP-запросы, запрос другим методом вызовет ошибку:
{
"error": "MethodNotAllowed",
"description": "The POST method is not allowed for the requested API element \"/\"."
}
С конфигурацией Angie, включающей location /status/, зоны resolver, http upstream, http server, location, cache, limit_conn в http и limit_req для примера:
http {
#...
resolver 8.8.8.8 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 64k;
server backend.example.com service=_http._tcp resolve max_conns=5;
keepalive 4;
}
server {
server_name www.example.com;
listen 443 ssl http2;
status_zone http_server_zone;
proxy_cache cache_zone;
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/
возвращает дерево JSON
{
"status": {
"angie": {
"version": "1.0.0",
"address": "192.168.1.1",
"generation": 1,
"load_time": "2022-10-19T12: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": 6,
"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.24.1:80": {
"server": "backend.example.com",
"service": "_http._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
}
}
},
"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, построив соответствующий запрос. Например:
$ 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/<zone>/slots
$ curl https://www.example.com/status/slabs/<zone>/slots/64
$ curl https://www.example.com/status/http/
$ curl https://www.example.com/status/http/server_zones
$ curl https://www.example.com/status/http/server_zones/<http_server_zone>
$ curl https://www.example.com/status/http/server_zones/<http_server_zone>/ssl
Директивы#
api#
- Синтаксис:
api
путь;- Умолчание:
—
- Контекст:
location
Включает HTTP RESTful интерфейс в location.
Параметр путь является обязательным. Подобно директиве alias, задаёт путь для замены указанного в location, но по дереву API, а не файловой системы.
Если указан в префиксном location:
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:
location ~^/api/([^/]+)/(.*)$ {
api /status/http/$1_zones/$2;
}
Здесь параметр путь определяет полный путь к элементу API, из запроса /api/location/bar/data/ будут определены переменные:
$1 = "location"
$2 = "bar/data/"
и запрос к API будет /status/http/location_zones/bar/data/
Также, параметр путь позволяет управлять доступом к API:
location /status/ {
api /status/;
allow 127.0.0.1;
deny all;
}
или
location /blog/requests/ {
api /status/http/server_zones/blog/requests/;
auth_basic "blog";
auth_basic_user_file conf/htpasswd;
}
Метрики#
Состояние сервера#
/status/angie
#
{
"version": "1.2.0",
"address": "192.168.0.1",
"generation": 1,
"load_time": "2022-10-24T16:15:43.805Z"
}
|
String; версия запущенного сервера Angie |
|
String; сборка, если указана при компиляции |
|
String; адрес сервера, принявшего запрос к API |
|
Number; количество перезагрузок конфигурации, полное от последнего старта |
|
String; время последней перезагрузки конфигурации в формате ISO 8601 с миллисекундным разрешением |
Соединения#
/status/connections
#
{
"accepted": 2257,
"dropped": 0,
"active": 3,
"idle": 1
}
|
Number; суммарное число принятых клиентских соединений |
|
Number; суммарное число сброшенных клиентских соединений |
|
Number: текущее число активных клиентских соединений |
|
Number; текущее число бездействующих клиентских соединений |
Зоны разделяемой памяти, использующие распределение slab#
Статистика использования сконфигурированных зон разделяемой памяти, таких как, например: limit_conn, limit_req и HTTP cache
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;
/status/slabs/<zone>
#
где <zone> — имя любой из сконфигурированных зон разделяемой памяти, использующей распределение slab
{
"pages": {
"used": 2,
"free": 506
},
"slots": {
"64": {
"used": 1,
"free": 63,
"reqs": 1,
"fails": 0
}
}
|
Object; статистика по страницам памяти |
|
Number; текущее число используемых страниц памяти |
|
Number; текущее число свободных страниц памяти |
|
Object; статистика по слотам памяти, по каждому из размеров. slots содержит данные по размеру слота памяти ( 8, 16, 32, и т.д., вплоть до половины размера страницы памяти в байтах) |
|
Number; текущее число используемых слотов памяти заданного размера |
|
Number; текущее число свободных слотов памяти заданного размера |
|
Number; суммарное число попыток выделения памяти указанного размера |
|
Number; число неудавшихся попыток выделения памяти указанного размера |
DNS запросы#
Сбор статистики запросов к серверу в зоне разделяемой памяти DNS включается указанием имени в параметре status_zone=<name> (status_zone) директивы resolver
resolver 8.8.8.8 status_zone=resolver_zone;
/status/resolvers/<zone>
#
где <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
}
}
|
Object; статистика запросов |
|
Number; число запросов на преобразование имён в адреса (A и AAAA запросы) |
|
Number; число запросов на преобразование сервисов в адреса (SRV запросы) |
|
Number; число запросов на преобразование адресов в имена (PTR запросы) |
|
Object; статистика ответов |
|
Number; число успешных ответов |
|
Number; число запросов, не дождавшихся ответа |
|
Number; число ответов с кодом 1 (Format error) |
|
Number; число ответов с кодом 2 (Server failure) |
|
Number; число ответов с кодом 3 (Name Error) |
|
Number; число ответов с кодом 4 (Not Implemented) |
|
Number; число ответов с кодом 5 (Refused) |
|
Number; число запросов, завершённых с другим ненулевым кодом |
HTTP server и location#
Для включения сбора следующих данных необходимо сконфигурировать status_zone <zone> (status_zone) в контексте server. Объект ssl наполняется данными только в случае когда server сконфигурирован c listen ssl;
server {
...
status_zone http_server_zone;
/status/http/server_zones/<zone>
#
где <zone> — имя зоны разделяемой памяти для сбора server статистики
"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
}
|
Object; SSL метрики |
|
Number; суммарное число успешных SSL handshakes |
|
Number; суммарное число повторных использований SSL-сессий во время операций SSL handshake |
|
Number; суммарное число timed out SSL handshakes |
|
Number; суммарное число неуспешных SSL handshakes |
|
Object; метрики запросов |
|
Number; суммарное число клиентских запросов |
|
Number; текущее число обслуживаемых клиентских запросов |
|
Number; суммарное число запросов завершённых без отправки ответа |
|
Object; метрики ответов |
|
Number; ненулевое число ответов со статусом <code> (100-599) |
|
Number; ненулевое число ответов с другим кодом статуса |
|
Object; метрики данных |
|
Number; суммарное количество байт, полученное от клиентов |
|
Number; суммарное количество байт, отправленное клиентам |
Директива status_zone <zone> (status_zone), определённая в контексте location и if в location, включает сбор статистики в указанной зоне разделяемой памяти. Значение off
выключает сбор данных во вложенных блоках location. Набор данных для зоны location не включает объект ssl и метрику requests/processing
location / {
root /usr/share/angie/html;
status_zone location_zone;
}
/status/http/location_zones/<zone>
#
{
"requests": {
"total": 4158,
"discarded": 0
},
"responses": {
"200": 4157,
"304": 1
},
"data": {
"received": 538200,
"sent": 177606236
}
}
Stream server#
Для включения сбора следующих данных необходимо сконфигурировать status_zone <zone> (status_zone) в контексте server. Объект ssl наполняется данными только в случае когда server сконфигурирован c listen ssl;
server {
...
status_zone stream_server_zone;
/status/stream/server_zones/<zone>
#
где <zone> — имя зоны разделяемой памяти для сбора server статистики
{
"ssl": {
"handshaked": 24,
"reuses": 0,
"timedout": 0,
"failed": 0
},
"connections": {
"total": 24,
"processing": 1,
"discarded": 0
},
"sessions": {
"success": 24,
"invalid": 0,
"forbidden": 0,
"internal_error": 0,
"bad_gateway": 0,
"service_unavailable": 0
},
"data": {
"received": 2762947,
"sent": 53495723
}
}
|
Object; SSL метрики |
|
Number; суммарное число успешных SSL handshakes |
|
Number; суммарное число повторных использований SSL-сессий во время операций SSL handshake |
|
Number; суммарное число timed out SSL handshakes |
|
Number; суммарное число неуспешных SSL handshakes |
|
Object; метрики соединений |
|
Number; суммарное число клиентских соединений |
|
Number; текущее число обслуживаемых клиентских соединений |
|
Number: суммарное число клиентских соединений, завершённых без создания сессии |
|
Object; метрики сессий |
|
Number; число сессий, завершённых с кодом 200, что означает успешное завершение |
|
Number; число сессий, завершённых с кодом 400, случается, когда сервер не может прочитать данные от клиента, например, заголовок PROXY protocol |
|
Number; число сессий, завершённых с кодом 403, когда доступ запрещён, например, ограничен для определённого адреса клиента |
|
Number; число сессий, завершённых с кодом 500, внтуренняя ошибка сервера |
|
Number; число сессий, завершённых с кодом 502, Bad Gateway, если, например, сервер в upstream недоступен или не может быть выбран |
|
Number; число сессий, завершённых с кодом 503, Service Unavailable, если, например, доступ ограничен числом входящих соединений |
|
Object; метрики данных |
|
Number; суммарное количество байт, полученное от клиентов |
|
Number; суммарное количество байт, отправленное клиентам |
HTTP caches#
proxy_cache cache_zone;
/status/http/caches/<cache>
#
Для каждой зоны, сконфигурированной в proxy_cache, хранятся следующие данные
{
"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
}
}
}
|
Number; текущий размер кэша |
|
Number; ограничение на максимальный размер кэша, если задано в конфигурации |
|
Boolean; true пока процесс cache loader подгружает данные с диска |
|
Object; метрики возвращённых из кэша ответов (proxy_cache_valid) |
|
Number; суммарное число ответов, прочитанных из кэша |
|
Number; суммарное количество байт, прочитанных из кэша |
|
Object; метрики просроченных ответов, возвращённых из кэша (proxy_cache_use_stale) |
|
Number; суммарное число ответов, прочитанных из кэша |
|
Number; суммарное количество байт, прочитанных из кэша |
|
Object; метрики просроченных ответов, возвращённых из кэша, пока данные в кэше обновляются (proxy_cache_use_stale updating) |
|
Number; суммарное число ответов, прочитанных из кэша |
|
Number; суммарное количество байт, прочитанных из кэша |
|
Object; метрики просроченных и ревалидированных ответов, возвращённых из кэша (proxy_cache_revalidate) |
|
Number; суммарное число ответов, прочитанных из кэша |
|
Number; суммарное количество байт, прочитанных из кэша |
|
Object; метрики ответов, не найденных в кэше |
|
Number; суммарное число соответствующих ответов |
|
Number; суммарное количество байт, прочитанных с проксируемого сервера |
|
Number; суммарное число ответов, записанных в кэш |
|
Number; суммарное количество байт, записанных в кэш |
|
Object; число ответов, возвращённых не из кэша, т.к. просрочены |
|
Number; суммарное число соответствующих ответов |
|
Number; суммарное количество байт, прочитанных с проксируемого сервера |
|
Number; суммарное число ответов, записанных в кэш |
|
Number; суммарное количество байт, записанных в кэш |
|
Object; статистика ответов, возвращённых в обход кэша (proxy_cache_bypass) |
|
Number; суммарное число соответствующих ответов |
|
Number; суммарное количество байт, прочитанных с проксируемого сервера |
|
Number; суммарное число ответов, записанных в кэш |
|
Number; суммарное количество байт, записанных в кэш |
limit_conn#
limit_conn_zone $binary_remote_addr zone=limit_conn_zone:10m;
/status/http/limit_conns/<zone>
, /status/stream/limit_conns/<zone>
#
Каждая из сконфигурированных зон: limit_conn в http или limit_conn в stream содержит следующие данные
{
"passed": 73,
"skipped": 0,
"rejected": 0,
"exhausted": 0
}
|
Number; суммарное число переданных на проксируемый сервер соединений |
|
Number; суммарное число соединений, переданных с нулевым или превосходящим 255 байт <key> |
|
Number; суммарное число соединений сверх сконфигурированного ограничения |
|
Number; суммарное число соединений, сброшенных из-за переполнения хранилища зоны |
limit_req#
limit_req_zone $binary_remote_addr zone=limit_req_zone:10m rate=1r/s;
/status/http/limit_reqs/<zone>
#
Каждая из сконфигурированных зон limit_req cодержит следующие данные
{
"passed": 54816,
"skipped": 0,
"delayed": 65,
"rejected": 26,
"exhausted": 0
}
|
Number; суммарное число проксированых соединений |
|
Number; суммарное число соединений, переданных с нулевым или превосходящим 255 байт <key> |
|
Number; суммарное число задержанных соединений |
|
Number; суммарное число сброшенных соединений |
|
Number; суммарное число соединений, сброшенных из-за переполнения хранилища зоны |
HTTP upstream#
Добавлено в версии 1.1.0.
Для включения сбора следующих данных необходимо сконфигурировать zone <zone> (zone) в контексте upstream.
upstream backend {
zone http_backend 64k;
server backend1.example.com weight=5;
server backend2.example.com;
}
/status/http/upstreams/<upstream>
#
где <upstream> — имя апстрима, в конфигурации которого указана директива zone.
{
"peers": {
"192.168.24.1:80": {
"server": "backend.example.com",
"service": "_http._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
}
}
},
"keepalive": 2
}
|
Object; метрики пиров апстрима |
|
Object; метрики пира |
|
String; сервер, как он указан в директиве server |
|
String; имя сервиса, указанное в директиве server, если сконфигурировано |
|
Boolean; |
|
Number; сконфигурированный weight |
|
String; текущее состояние пира, одно из: up, down, или unavailable (когда достигнуто установленное значение max_fails) |
|
Object; статистика выбора пиров |
|
Number; текущее число соединений к пиру |
|
Number; общее число запросов переданных пиру |
|
String; время в формате ISO 8601 последнего выбора пира |
|
Number; максимальное число одновременных активных соединений к пиру, если сконфигурировано |
|
Object; статистика ответов |
|
Number; ненулевое число ответов со статусом <code> (100-599) |
|
Number; ненулевое число ответов с другим кодом статуса |
|
Object; метрики данных |
|
Number; суммарное количество байт, полученное от пира |
|
Number; суммарное количество байт, отправленное пиру |
|
Object; статистика по состоянию пира |
|
Number; общее количество неудачных попыток работы с пиром |
|
Number; столько раз пир становился unavailable по достижении значения max_fails |
|
Number; суммарное время (в миллисекундах), в течение которого пир был недоступен для выбора как unavailable |
|
String; время в формате ISO 8601, когда пир стал unavailable |
|
Number; текущее число кэшированных соединений |