Модуль API

Содержание

Модуль `API`#

Добавлено в версии 1.0.0.

Модуль API реализует HTTP RESTful интерфейс для получения базовой информации о веб-сервере в формате JSON, а также статистики по клиентским соединениям, зонам разделяемой памяти, DNS-запросам, HTTP-запросам, кэшу HTTP-ответов, сессиям модуля stream и зонам модулей limit_conn http, limit_conn stream, limit_req и http upstream.

Интерфейс принимает HTTP-методы GET и HEAD; запрос с другим методом вызовет ошибку:

{
    "error": "MethodNotAllowed",
    "description": "The POST method is not allowed for the requested API element \"/\"."
}

Директивы#

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/data/ будут выделены переменные:

$1 = "location"
$2 = "data/"

И конечный запрос будет иметь вид /status/http/location_zones/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;
}

api_config_files#

Синтаксис:: api_config_files on | off;
Умолчание:: off
Контекст:: location

Включает или отключает добавление объекта config_files, перечисляющего содержимое всех файлов конфигурации Angie, загруженных сейчас экземпляром сервера, в состав раздела API /status/angie/. Например, при такой конфигурации:

location /status/ {
    api /status/;
    api_config_files on;
}

Запрос к /status/angie/ возвращает приблизительно следующее:

{
    "version":"1.5.0",
    "address":"192.168.16.5",
    "generation":1,
    "load_time":"2024-03-27T12:58:39.789Z",
    "config_files": {
        "/etc/angie/angie.conf": "...",
        "/etc/angie/mime.types": "..."
    }
}

По умолчанию вывод отключен, так как файлы конфигурации могут содержать особо чувствительные, конфиденциальные сведения.

Метрики#

Angie публикует статистику использования в разделе API /status/; открыть доступ к ней можно, задав соответствующий location. Полный доступ:

location /status/ {
    api /status/;
}

Пример частичного доступа, уже приводившийся выше:

location /stats/ {
    api /status/http/server_zones/;
}

Пример конфигурации#

С конфигурацией, включающей location /status/, зоны resolver, http в upstream, http server, location, cache, limit_conn в http и limit_req:

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;

        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

{
    "angie": {
        "version":"1.5.0",
        "address":"192.168.16.5",
        "generation":1,
        "load_time":"2024-03-27T12: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":"<server_id>"
                    }
                },

                "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

Примечание

По умолчанию модуль использует для дат строки в формате ISO 8601; чтобы вместо этого использовать целочисленный формат эпохи UNIX, добавьте параметр date=epoch к строке запроса:

$ 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`#

{
    "version": "1.5.0",
    "address": "192.168.16.5",
    "generation": 1,
    "load_time": "2024-03-27T16:15:43.805Z"
    "config_files": {
        "/etc/angie/angie.conf": "...",
        "/etc/angie/mime.types": "..."
    }
}

`version`	Строка; версия запущенного сервера Angie
`build` (PRO)	Строка; сборка, если указана при компиляции
`address`	Строка; адрес сервера, принявшего запрос к API
`generation`	Число; версия (поколение) конфигурации, отсчитываемая с последнего запуска Angie
`load_time`	Строка; время последней перезагрузки конфигурации в формате даты; строковые значения даются с миллисекундным разрешением
`config_files`	Объект; его члены — абсолютные имена всех файлов конфигурации Angie, загруженных сейчас экземпляром сервера, а их значения — строковые представления содержимого файлов, например: { "/etc/angie/angie.conf": "server {\n listen 80;\n # ...\n\n}\n" } Осторожно Объект `config_files` есть в `/status/angie/`, только если включена директива api_config_files.

Соединения#

`/status/connections`#

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

`accepted`	Число; суммарное количество принятых клиентских соединений
`dropped`	Число; суммарное количество сброшенных клиентских соединений
`active`	Число; текущее количество активных клиентских соединений
`idle`	Число; текущее количество бездействующих клиентских соединений

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

DNS запросы#

Сбор статистики запросов к серверу в зоне разделяемой памяти DNS включается указанием имени в параметре status_zone=<name> (status_zone) директивы resolver

resolver 127.0.0.53 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`	Объект; статистика запросов
`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`	Число; количество запросов, завершенных с другим ненулевым кодом

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

Директива 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`	Объект; SSL метрики
`handshaked`	Число; суммарное количество успешных SSL-рукопожатий
`reuses`	Число; суммарное количество повторных использований SSL-сессий во время SSL-рукопожатий
`timedout`	Число; суммарное количество SSL-рукопожатий с истекшим таймаутом
`failed`	Число; суммарное количество неуспешных SSL-рукопожатий
`connections`	Объект; метрики соединений
`total`	Число; суммарное количество клиентских соединений
`processing`	Число; текущее количество обслуживаемых клиентских соединений
`discarded`	Number: суммарное количество клиентских соединений, завершенных без создания сессии
`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`	Число; суммарное количество байт, отправленное клиентам

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

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

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

HTTP upstream#

Добавлено в версии 1.1.0.

Чтобы включить сбор следующих метрик, задайте директиву zone в контексте upstream, например:

upstream upstream {
    zone upstream 256k;
    server backend.example.com service=_example._tcp resolve max_conns=5;
    keepalive 4;
}

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

где <upstream> — имя апстрима, в конфигурации которого указана директива zone.

{
    "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": "<server_id>"
        }
    },

    "keepalive": 2
}

`peers`	Объект; содержит метрики всех пиров апстрима во вложенных объектах, имена которых — канонические представления адресов этих пиров. Внутри каждого вложенного объекта:
`server`	Строка; сервер, как он указан в директиве server
`service`	Строка; имя сервиса, указанное в директиве server, если сконфигурировано
`slow_start` (PRO 1.4.0+)	Число; заданное для сервера значение slow_start, выраженное в секундах. При задании значения через соответствующий подраздел API динамической конфигурации можно указать не только число секунд, но и время с точностью до миллисекунд.
`backup`	Логическое значение; `true` для backup серверов
`weight`	Число; сконфигурированный weight
`state`	Строка; текущее состояние пира, и какие запросы ему отправляются: `checking` (PRO): настроен как `essential` и проверяется, отправляются только проверочные запросы; `down`: отключен вручную, не отправляются никакие запросы; `draining` (PRO): аналогичен `down`, но отправляются запросы сессий, привязанных ранее через sticky; `recovering`: восстанавливается после сбоя согласно slow_start, отправляется все больше запросов; `unavailable`: достиг предела max_fails, отправляются пробные клиентские запросы с интервалом fail_timeout; `unhealthy` (PRO): неработающий, отправляются только проверочные запросы; `up`: работоспособен, запросы отправляются как обычно.
`selected`	Объект; статистика выбора пиров
`current`	Число; текущее количество соединений к пиру
`total`	Число; общее количество запросов переданных пиру
`last`	Строка или число; время последнего выбора пира в формате даты
`max_conns`	Число; максимальное количество одновременных активных соединений к пиру, если сконфигурировано
`responses`	Объект; статистика ответов
`<code>`	Число; ненулевое количество ответов со статусом <code> (100-599)
`xxx`	Число; ненулевое количество ответов с другим кодом статуса
`data`	Объект; метрики данных
`received`	Число; суммарное количество байт, полученное от пира
`sent`	Число; суммарное количество байт, отправленное пиру
`health`	Объект; статистика по состоянию пира
`fails`	Число; общее количество неудачных попыток работы с пиром
`unavailable`	Число; столько раз пир становился `unavailable` по достижении значения max_fails
`downtime`	Число; суммарное время (в миллисекундах), в течение которого пир был недоступен для выбора как `unavailable`
`downstart`	Строка или число; время, когда пир стал `unavailable`, в формате даты
`header_time` (PRO 1.3.0+)	Число; среднее время (в миллисекундах) получения заголовков ответа от сервера; см. директиву response_time_factor
`response_time` (PRO 1.3.0+)	Число; среднее время (в миллисекундах) получения ответа от сервера; см. директиву response_time_factor
`sid`	Строка; id сервера, указанный в конфигурации апстрима
`keepalive`	Число; текущее количество кэшированных соединений

Stream upstream#

Чтобы включить сбор следующих метрик, задайте директиву zone в контексте upstream, например:

upstream upstream {
    zone upstream 256k;
    server backend.example.com service=_example._tcp resolve max_conns=5;
    keepalive 4;
}

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

Здесь <upstream> — имя апстрима, в конфигурации которого использована директива zone.

{
    "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
`service`	Строка; имя сервиса, если оно указано в директиве server
`slow_start` (PRO 1.4.0+)	Число; заданное для сервера значение slow_start, выраженное в секундах. При задании значения через соответствующий подраздел API динамической конфигурации можно указать не только число секунд, но и время с точностью до миллисекунд.
`backup`	Логическое значение; `true` для запасных серверов
`weight`	Число; заданный для пира вес
`state`	Строка; текущее состояние пира: `up`: работоспособен, запросы отправляются как обычно; `down`: отключен вручную, не отправляются никакие запросы; `unavailable`: достиг предела max_fails, отправляются пробные клиентские запросы с интервалом fail_timeout; `recovering`: восстанавливается после сбоя согласно slow_start, отправляется все больше запросов; `checking` (PRO): настроен как `essential` и проверяется, отправляются только проверочные запросы; `unhealthy` (PRO): неработающий, отправляются только проверочные запросы.
`selected`	Объект; статистика выбора этого пира для подключения
`current`	Число; текущее количество подключений к пиру
`total`	Число; общее количество подключений, направленных этому пиру
`last`	Строка или число; время, когда пир был выбран в последний раз, в формате даты
`max_conns`	Число; максимальное количество одновременных активных подключений к пиру, если оно задано
`data`	Объект; статистика передачи данных
`received`	Число; общее количество байт, полученное от пира
`sent`	Число; общее количество байт, отправленное пиру
`health`	Объект; статистика по состоянию пира
`fails`	Число; общее количество неудачных попыток связаться с пиром
`unavailable`	Число; общее количество переходов в состояние `unavailable` по достижении значения max_fails
`downtime`	Число; общее время в миллисекундах, в течение которого пир находился в состоянии `unavailable` (недоступен для выбора)
`downstart`	Строка или число; время, когда пир последний раз стал `unavailable`, в формате даты
`connect_time` (PRO 1.4.0+)	Число; среднее время (в миллисекундах) установления соединения с сервером; см. директиву response_time_factor
`first_byte_time` (PRO 1.4.0+)	Число; среднее время (в миллисекундах) получения первого байта ответа от сервера; см. директиву response_time_factor
`last_byte_time` (PRO 1.4.0+)	Число; среднее время (в миллисекундах) получения полного ответа от сервера; см. директиву response_time_factor

API динамической конфигурации (только PRO)#

Добавлено в версии 1.2.0.

В составе API есть раздел /config, позволяющий динамически менять конфигурацию Angie в формате JSON с помощью HTTP-запросов PUT, PATCH и DELETE. Все изменения атомарны: новые настройки применяются целиком либо не применяются вовсе. При ошибке Angie сообщит, в чем причина.

Подразделы `/config`#

Cейчас в разделе /config доступна настройка отдельных серверов в составе апстримов для модулей HTTP и stream <api_config_stream_upstreams_servers>; число настроек, к которым применима динамическая конфигурация, планомерно увеличивается.

`/config/http/upstreams/<upstream>/servers/<name>`#

Позволяет настраивать отдельные серверы в составе апстрима, в том числе добавлять новые и удалять настроенные.

Параметры в составе пути URI:

<upstream>

Имя блока upstream; чтобы настраивать его через /config, в нем должна быть задана директива zone, определяющая зону разделяемой памяти.

<name>

Имя конкретного сервера в составе указанного <upstream>; задается в формате <service>@<host>, где:

<service>@ — необязательная часть, задающая имя сервиса в целях разрешения SRV-записей.
<host> — доменное имя сервиса (при наличии resolve) или IP-адрес; также можно указать порт.

Например, для следующей конфигурации:

upstream backend {
    server backend.example.com:8080 service=_http._tcp resolve;
    server 127.0.0.1;
    zone backend 1m;
}

Допустимы такие имена серверов:

$ curl http://127.0.0.1/config/http/upstreams/backend/servers/_http._tcp@backend.example.com:8080/
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/127.0.0.1/

Этот подраздел API позволяет задавать параметры weight, max_conns, max_fails, fail_timeout, backup, down и sid, описанные в разделе server.

Примечание

Отдельного параметра drain здесь нет; включить режим drain можно, задав для down строковое значение drain:

$ curl -X PUT -d "drain" \
  http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com/down

Пример:

$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com?defaults=on

{
    "weight": 1,
    "max_conns": 0,
    "max_fails": 1,
    "fail_timeout": 10,
    "backup": true,
    "down": false,
    "sid": ""
}

Фактически доступны будут только те параметры, которые поддерживает текущий метод балансировки нагрузки апстрима. Так, если апстрим настроен с методом балансировки random:

upstream backend {
    zone backend 256k;
    server backend.example.com resolve max_conns=5;
    random;
}

То добавить в него новый сервер с параметром backup невозможно:

$ curl -X PUT -d '{ "backup": true }' \
    http://127.0.0.1/config/http/upstreams/backend/servers/backend1.example.com

{
    "error": "FormatError",
    "description": "The \"backup\" field is unknown."
}

Примечание

Даже с совместимым методом балансировки параметр backup можно задать лишь при добавлении нового сервера.

`/config/stream/upstreams/<upstream>/servers/<name>`#

Параметры в составе пути URI:

<upstream>

<name>

Имя конкретного сервера в составе указанного <upstream>; задается в формате <service>@<host>, где:

<service>@ — необязательная часть, задающая имя сервиса в целях разрешения SRV-записей.
<host> — доменное имя сервиса (при наличии resolve) или IP-адрес; также можно указать порт.

Например, для следующей конфигурации:

upstream backend {
    server backend.example.com:8080 service=_example._tcp resolve;
    server 127.0.0.1:12345;
    zone backend 1m;
}

Допустимы такие имена серверов:

$ 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, backup и down, описанные в разделе server:

curl http://127.0.0.1/config/stream/upstreams/backend/servers/backend.example.com?defaults=on

{
    "weight": 1,
    "max_conns": 0,
    "max_fails": 1,
    "fail_timeout": 10,
    "backup": true,
    "down": false,
}

upstream backend {
    zone backend 256k;
    server backend.example.com resolve max_conns=5;
    random;
}

То добавить в него новый сервер с параметром backup невозможно:

$ curl -X PUT -d '{ "backup": true }' \
    http://127.0.0.1/config/stream/upstreams/backend/servers/backend1.example.com

{
    "error": "FormatError",
    "description": "The \"backup\" field is unknown."
}

Примечание

Даже с совместимым методом балансировки параметр backup можно задать лишь при добавлении нового сервера.

HTTP-методы#

Рассмотрим семантику каждого из применимых к этому разделу HTTP-методов на примере следующей конфигурации апстрима:

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/ допустимы такие запросы:

$ 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:

$ curl http://127.0.0.1/config/http/upstreams/backend/servers?defaults=on

{
    "backend.example.com": {
        "weight": 1,
        "max_conns": 5,
        "max_fails": 1,
        "fail_timeout": 10,
        "backup": false,
        "down": false,
        "sid": ""
    }
}

PUT#

HTTP-метод PUT позволяет создать новую JSON-сущность по указанному пути или полностью заменить существующую.

Например, чтобы добавить не заданный ранее параметр max_fails у сервера backend.example.com в апстриме backend:

$ curl -X PUT -d '2' \
    http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com/max_fails

{
    "success": "Updated",
    "description": "Existing configuration API entity \"/config/http/upstreams/backend/servers/backend.example.com/max_fails\" was updated with replacing."
}

Проверим изменения:

$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com

{
    "max_conns": 5,
    "max_fails": 2
}

DELETE#

HTTP-метод DELETE удаляет ранее заданные настройки по указанному пути; при этом восстанавливаются значения по умолчанию, если они есть.

Например, чтобы удалить измененный ранее параметр max_fails у сервера backend.example.com в апстриме backend:

$ curl -X DELETE \
    http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com/max_fails

{
    "success": "Reset",
    "description": "Configuration API entity \"/config/http/upstreams/backend/servers/backend.example.com/max_fails\" was reset to default."
}

Проверим изменения с аргументом defaults=on:

$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com?defaults=on

{
    "weight": 1,
    "max_conns": 5,
    "max_fails": 1,
    "fail_timeout": 10,
    "backup": false,
    "down": false,
    "sid": ""
}

Параметр max_fails вернулся к значению по умолчанию.

PATCH#

HTTP-метод PATCH позволяет создать новую сущность по указанному пути либо частично заменить или дополнить существующую (RFC 7386), отправив в данных JSON-определение.

Метод работает так: если сущности, указанные в новом определении, уже есть в конфигурации, они будут перезаписаны; если их нет, то они будут добавлены.

Например, чтобы поменять значение параметра down у сервера backend.example.com в апстриме backend, оставив прочее без изменений:

$ curl -X PATCH -d '{ "down": true }' \
    http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com

{
    "success": "Updated",
    "description": "Existing configuration API entity \"/config/http/upstreams/backend/servers/backend.example.com\" was updated with merging."
}

Проверим изменения:

$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com

{
    "max_conns": 5,
    "down": true
}

Обратите внимание, что переданный с запросом PATCH JSON-объект слился с уже существующим, а не заменил его целиком, как было бы с PUT.

Особый случай представляют значения null; они используются для удаления отдельных элементов конфигурации в ходе такого слияния.

Примечание

Такое удаление аналогично действию DELETE; в частности, восстанавливаются значения по умолчанию.

Например, чтобы удалить добавленный ранее параметр down и одновременно с этим изменить max_conns:

$ curl -X PATCH -d '{ "down": null, "max_conns": 6 }' \
    http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com

{
    "success": "Updated",
    "description": "Existing configuration API entity \"/config/http/upstreams/backend/servers/backend.example.com\" was updated with merging."
}

Проверим изменения:

$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com

{
    "max_conns": 6
}

Параметр down, для которого было передано значение null, удален; значение max_conns изменено.

Модуль API

Содержание

Модуль API#

Директивы#

api#

api_config_files#

Метрики#

Пример конфигурации#

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

/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>#

Stream upstream#

/status/stream/upstreams/<upstream>#

API динамической конфигурации (только PRO)#

Подразделы /config#

/config/http/upstreams/<upstream>/servers/<name>#

/config/stream/upstreams/<upstream>/servers/<name>#

HTTP-методы#

GET#

PUT#

DELETE#

PATCH#

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

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

Подразделы `/config`#

`/config/http/upstreams/<upstream>/servers/<name>`#

`/config/stream/upstreams/<upstream>/servers/<name>`#