Модуль `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"
}

`version`	String; версия запущенного сервера Angie
`build`	String; сборка, если указана при компиляции
`address`	String; адрес сервера, принявшего запрос к API
`generation`	Number; количество перезагрузок конфигурации, полное от последнего старта
`load_time`	String; время последней перезагрузки конфигурации в формате ISO 8601 с миллисекундным разрешением

Соединения#

`/status/connections`#

{
  "accepted": 2257,
  "dropped": 0,
  "active": 3,
  "idle": 1
}

`accepted`	Number; суммарное число принятых клиентских соединений
`dropped`	Number; суммарное число сброшенных клиентских соединений
`active`	Number: текущее число активных клиентских соединений
`idle`	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
  }
}

`pages`	Object; статистика по страницам памяти
`used`	Number; текущее число используемых страниц памяти
`free`	Number; текущее число свободных страниц памяти
`slots`	Object; статистика по слотам памяти, по каждому из размеров. slots содержит данные по размеру слота памяти ( 8, 16, 32, и т.д., вплоть до половины размера страницы памяти в байтах)
`used`	Number; текущее число используемых слотов памяти заданного размера
`free`	Number; текущее число свободных слотов памяти заданного размера
`reqs`	Number; суммарное число попыток выделения памяти указанного размера
`fails`	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
  }
}

`queries`	Object; статистика запросов
`name`	Number; число запросов на преобразование имён в адреса (A и AAAA запросы)
`srv`	Number; число запросов на преобразование сервисов в адреса (SRV запросы)
`addr`	Number; число запросов на преобразование адресов в имена (PTR запросы)
`responses`	Object; статистика ответов
`success`	Number; число успешных ответов
`timedout`	Number; число запросов, не дождавшихся ответа
`format_error`	Number; число ответов с кодом 1 (Format error)
`server_failure`	Number; число ответов с кодом 2 (Server failure)
`not_found`	Number; число ответов с кодом 3 (Name Error)
`unimplemented`	Number; число ответов с кодом 4 (Not Implemented)
`refused`	Number; число ответов с кодом 5 (Refused)
`other`	Number; число запросов, завершённых с другим ненулевым кодом

Коды ответов описаны в RFC 1035, часть 4.1.1.

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
}

`ssl`	Object; SSL метрики
`handshaked`	Number; суммарное число успешных SSL handshakes
`reuses`	Number; суммарное число повторных использований SSL-сессий во время операций SSL handshake
`timedout`	Number; суммарное число timed out SSL handshakes
`failed`	Number; суммарное число неуспешных SSL handshakes
`requests`	Object; метрики запросов
`total`	Number; суммарное число клиентских запросов
`processing`	Number; текущее число обслуживаемых клиентских запросов
`discarded`	Number; суммарное число запросов завершённых без отправки ответа
`responses`	Object; метрики ответов
`<code>`	Number; ненулевое число ответов со статусом <code> (100-599)
`xxx`	Number; ненулевое число ответов с другим кодом статуса
`data`	Object; метрики данных
`received`	Number; суммарное количество байт, полученное от клиентов
`sent`	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#

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
  }
}

`ssl`	Object; SSL метрики
`handshaked`	Number; суммарное число успешных SSL handshakes
`reuses`	Number; суммарное число повторных использований SSL-сессий во время операций SSL handshake
`timedout`	Number; суммарное число timed out SSL handshakes
`failed`	Number; суммарное число неуспешных SSL handshakes
`connections`	Object; метрики соединений
`total`	Number; суммарное число клиентских соединений
`processing`	Number; текущее число обслуживаемых клиентских соединений
`discarded`	Number: суммарное число клиентских соединений, завершённых без создания сессии
`sessions`	Object; метрики сессий
`success`	Number; число сессий, завершённых с кодом 200, что означает успешное завершение
`invalid`	Number; число сессий, завершённых с кодом 400, случается, когда сервер не может прочитать данные от клиента, например, заголовок PROXY protocol
`forbidden`	Number; число сессий, завершённых с кодом 403, когда доступ запрещён, например, ограничен для определённого адреса клиента
`internal_error`	Number; число сессий, завершённых с кодом 500, внтуренняя ошибка сервера
`bad_gateway`	Number; число сессий, завершённых с кодом 502, Bad Gateway, если, например, сервер в upstream недоступен или не может быть выбран
`service_unavailable`	Number; число сессий, завершённых с кодом 503, Service Unavailable, если, например, доступ ограничен числом входящих соединений
`data`	Object; метрики данных
`received`	Number; суммарное количество байт, полученное от клиентов
`sent`	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
    }
  }
}

`size`	Number; текущий размер кэша
`max_size`	Number; ограничение на максимальный размер кэша, если задано в конфигурации
`cold`	Boolean; true пока процесс cache loader подгружает данные с диска
`hit`	Object; метрики возвращённых из кэша ответов (proxy_cache_valid)
`responses`	Number; суммарное число ответов, прочитанных из кэша
`bytes`	Number; суммарное количество байт, прочитанных из кэша
`stale`	Object; метрики просроченных ответов, возвращённых из кэша (proxy_cache_use_stale)
`responses`	Number; суммарное число ответов, прочитанных из кэша
`bytes`	Number; суммарное количество байт, прочитанных из кэша
`updating`	Object; метрики просроченных ответов, возвращённых из кэша, пока данные в кэше обновляются (proxy_cache_use_stale updating)
`responses`	Number; суммарное число ответов, прочитанных из кэша
`bytes`	Number; суммарное количество байт, прочитанных из кэша
`revalidated`	Object; метрики просроченных и ревалидированных ответов, возвращённых из кэша (proxy_cache_revalidate)
`responses`	Number; суммарное число ответов, прочитанных из кэша
`bytes`	Number; суммарное количество байт, прочитанных из кэша
`miss`	Object; метрики ответов, не найденных в кэше
`responses`	Number; суммарное число соответствующих ответов
`bytes`	Number; суммарное количество байт, прочитанных с проксируемого сервера
`responses_written`	Number; суммарное число ответов, записанных в кэш
`bytes_written`	Number; суммарное количество байт, записанных в кэш
`expired`	Object; число ответов, возвращённых не из кэша, т.к. просрочены
`responses`	Number; суммарное число соответствующих ответов
`bytes`	Number; суммарное количество байт, прочитанных с проксируемого сервера
`responses_written`	Number; суммарное число ответов, записанных в кэш
`bytes_written`	Number; суммарное количество байт, записанных в кэш
`bypass`	Object; статистика ответов, возвращённых в обход кэша (proxy_cache_bypass)
`responses`	Number; суммарное число соответствующих ответов
`bytes`	Number; суммарное количество байт, прочитанных с проксируемого сервера
`responses_written`	Number; суммарное число ответов, записанных в кэш
`bytes_written`	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
}

`passed`	Number; суммарное число переданных на проксируемый сервер соединений
`skipped`	Number; суммарное число соединений, переданных с нулевым или превосходящим 255 байт <key>
`rejected`	Number; суммарное число соединений сверх сконфигурированного ограничения
`exhausted`	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
}

`passed`	Number; суммарное число проксированых соединений
`skipped`	Number; суммарное число соединений, переданных с нулевым или превосходящим 255 байт <key>
`delayed`	Number; суммарное число задержанных соединений
`rejected`	Number; суммарное число сброшенных соединений
`exhausted`	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
}

`peers`	Object; метрики пиров апстрима
`address`	Object; метрики пира
`server`	String; сервер, как он указан в директиве server
`service`	String; имя сервиса, указанное в директиве server, если сконфигурировано
`backup`	Boolean; `true` для backup серверов
`weight`	Number; сконфигурированный weight
`state`	String; текущее состояние пира, одно из: up, down, или unavailable (когда достигнуто установленное значение max_fails)
`selected`	Object; статистика выбора пиров
`current`	Number; текущее число соединений к пиру
`total`	Number; общее число запросов переданных пиру
`last`	String; время в формате ISO 8601 последнего выбора пира
`max_conns`	Number; максимальное число одновременных активных соединений к пиру, если сконфигурировано
`responses`	Object; статистика ответов
`<code>`	Number; ненулевое число ответов со статусом <code> (100-599)
`xxx`	Number; ненулевое число ответов с другим кодом статуса
`data`	Object; метрики данных
`received`	Number; суммарное количество байт, полученное от пира
`sent`	Number; суммарное количество байт, отправленное пиру
`health`	Object; статистика по состоянию пира
`fails`	Number; общее количество неудачных попыток работы с пиром
`unavailable`	Number; столько раз пир становился unavailable по достижении значения max_fails
`downtime`	Number; суммарное время (в миллисекундах), в течение которого пир был недоступен для выбора как unavailable
`downstart`	String; время в формате ISO 8601, когда пир стал unavailable
`keepalive`	Number; текущее число кэшированных соединений

Оглавление

Модуль API

Содержание

Модуль `API`#

Директивы#

api#

Метрики#

Состояние сервера#

`/status/angie`#

Соединения#

`/status/connections`#

Зоны разделяемой памяти, использующие распределение slab#

`/status/slabs/<zone>`#

DNS запросы#

`/status/resolvers/<zone>`#

HTTP server и location#

`/status/http/server_zones/<zone>`#

`/status/http/location_zones/<zone>`#

Stream server#

`/status/stream/server_zones/<zone>`#

HTTP caches#

`/status/http/caches/<cache>`#

limit_conn#

`/status/http/limit_conns/<zone>`, `/status/stream/limit_conns/<zone>`#

limit_req#

`/status/http/limit_reqs/<zone>`#

HTTP upstream#

`/status/http/upstreams/<upstream>`#

Оглавление

Модуль API

Содержание

Модуль API#

Директивы#

api#

Метрики#

Состояние сервера#

/status/angie#

Соединения#

/status/connections#

Зоны разделяемой памяти, использующие распределение slab#

/status/slabs/<zone>#

DNS запросы#

/status/resolvers/<zone>#

HTTP server и location#

/status/http/server_zones/<zone>#

/status/http/location_zones/<zone>#

Stream server#

/status/stream/server_zones/<zone>#

HTTP caches#

/status/http/caches/<cache>#

limit_conn#

/status/http/limit_conns/<zone>, /status/stream/limit_conns/<zone>#

limit_req#

/status/http/limit_reqs/<zone>#

HTTP upstream#

/status/http/upstreams/<upstream>#

Модуль `API`#

`/status/angie`#

`/status/connections`#

`/status/slabs/<zone>`#

`/status/resolvers/<zone>`#

`/status/http/server_zones/<zone>`#

`/status/http/location_zones/<zone>`#

`/status/stream/server_zones/<zone>`#

`/status/http/caches/<cache>`#

`/status/http/limit_conns/<zone>`, `/status/stream/limit_conns/<zone>`#

`/status/http/limit_reqs/<zone>`#

`/status/http/upstreams/<upstream>`#