Модуль 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#

Для включения сбора следующих данных необходимо сконфигурировать 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
  }
}

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; текущее число кэшированных соединений