API#

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

В Angie PRO в этом интерфейсе есть раздел динамической конфигурации, позволяющий менять настройки без перезагрузки конфигурации или перезапуска; сейчас доступна конфигурация отдельных серверов в составе upstream.

Директивы#

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

Примечание

В Angie PRO можно разделить API динамической конфигурации и неизменяемый API статуса, отражающий текущее состояние:

location /config/ {
    api /config/;
}

location /status/ {
    api /status/;
}

Также параметр путь позволяет управлять доступом к 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.8.2",
    "address":"192.168.16.5",
    "generation":1,
    "load_time":"2025-02-13T12: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.8.2",
        "address":"192.168.16.5",
        "generation":1,
        "load_time":"2025-02-13T12: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/<зона>/slots
$ curl https://www.example.com/status/slabs/<зона>/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.8.2",
    "address": "192.168.16.5",
    "generation": 1,
    "load_time": "2025-02-13T16: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#

/status/slabs/<зона>#

Статистика для зон разделяемой памяти с распределением 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;

В указанной таким образом зоне разделяемой памяти будет собираться следующая статистика:

pages

Объект; статистика по страницам памяти

    used

Число; текущее количество используемых страниц памяти

    free

Число; текущее количество свободных страниц памяти

slots

Объект; статистика по слотам памяти, по каждому из размеров. slots содержит данные по размеру слота памяти ( 8, 16, 32, и т.д., вплоть до половины размера страницы памяти в байтах)

    used

Число; текущее количество используемых слотов памяти заданного размера

    free

Число; текущее количество свободных слотов памяти заданного размера

    reqs

Число; суммарное количество попыток выделения памяти указанного размера

    fails

Число; количество неудавшихся попыток выделения памяти указанного размера

Пример:

{
  "pages": {
    "used": 2,
    "free": 506
  },

  "slots": {
    "64": {
      "used": 1,
      "free": 63,
      "reqs": 1,
      "fails": 0
  }
}

DNS-запросы к резолверу#

/status/resolvers/<зона>#

Для сбора статистики в директиве resolver нужно задать параметр status_zone (HTTP или Stream):

resolver 127.0.0.53 status_zone=resolver_zone;

В указанной таким образом зоне разделяемой памяти будет собираться следующая статистика:

queries

Объект; статистика запросов

    name

Число; количество запросов на преобразование имен в адреса (A- и AAAA-запросы)

    srv

Число; количество запросов на преобразование сервисов в адреса (SRV запросы)

    addr

Число; количество запросов на преобразование адресов в имена (PTR-запросы)

responses

Объект; статистика ответов

    success

Число; количество успешных ответов

    timedout

Число; количество запросов, не дождавшихся ответа

    format_error

Число; количество ответов с кодом 1 (Format Error)

    server_failure

Число; количество ответов с кодом 2 (Server Failure)

    not_found

Число; количество ответов с кодом 3 (Name Error)

    unimplemented

Число; количество ответов с кодом 4 (Not Implemented)

    refused

Число; количество ответов с кодом 5 (Refused)

    other

Число; количество запросов, завершенных с другим ненулевым кодом

sent

Объект; статистика отправленных DNS-запросов

    a

Число; количество запросов типа A

    aaaa

Число; количество запросов типа AAAA

    ptr

Число; количество запросов типа PTR

    srv

Число; количество запросов типа SRV

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

Различные типы DNS-записей описаны в RFC 1035, RFC 2782 и RFC 3596.

Пример:

{
  "queries": {
    "name": 442,
    "srv": 2,
    "addr": 0
  },

  "responses": {
    "success": 440,
    "timedout": 1,
    "format_error": 0,
    "server_failure": 1,
    "not_found": 1,
    "unimplemented": 0,
    "refused": 1,
  },

  "sent": {
    "a": 185,
    "aaaa": 245,
    "srv": 2,
    "ptr": 12
  }
}

HTTP server и location#

/status/http/server_zones/<зона>#

Для сбора статистики в контексте server нужно задать директиву status_zone:

server {
    ...
    status_zone server_zone;
}

Для группировки метрик по пользовательскому значению используйте альтернативный синтаксис. В этом примере метрики агрегируются по $host, и каждая группа выводится как отдельная зона:

status_zone $host zone=server_zone:5;

В указанной таким образом зоне разделяемой памяти будет собираться следующая статистика:

ssl

Объект; SSL-метрики. Присутствует, если в server есть listen ssl;

    handshaked

Число; суммарное количество успешных SSL-рукопожатий

    reuses

Число; суммарное количество повторных использований SSL-сессий во время SSL-рукопожатий

    timedout

Число; суммарное количество SSL-рукопожатий с истекшим таймаутом

    failed

Число; суммарное количество неуспешных SSL-рукопожатий

requests

Объект; метрики запросов

    total

Число; суммарное количество клиентских запросов

    processing

Число; текущее количество обслуживаемых клиентских запросов

    discarded

Число; суммарное количество запросов завершенных без отправки ответа

responses

Объект; метрики ответов

    <code>

Число; ненулевое количество ответов со статусом <code> (100-599)

    xxx

Число; ненулевое количество ответов с другим кодом статуса

data

Объект; метрики данных

    received

Число; суммарное количество байт, полученное от клиентов

    sent

Число; суммарное количество байт, отправленное клиентам

Пример:

"ssl": {
  "handshaked": 4174,
  "reuses": 0,
  "timedout": 0,
  "failed": 0
},

"requests": {
  "total": 4327,
  "processing": 0,
  "discarded": 0
},

"responses": {
  "200": 4305,
  "302": 6,
  "304": 12,
  "404": 4
},

"data": {
  "received": 733955,
  "sent": 59207757
}

/status/http/location_zones/<зона>#

Для сбора статистики в контексте location или if в location нужно задать директиву status_zone:

location / {
    root /usr/share/angie/html;
    status_zone location_zone;

    if ($request_uri ~* "^/condition") {
        # ...
        status_zone if_location_zone;
    }
}

Для группировки метрик по пользовательскому значению используйте альтернативный синтаксис. В этом примере метрики агрегируются по $host, и каждая группа выводится как отдельная зона:

status_zone $host zone=server_zone:5;

В указанной таким образом зоне разделяемой памяти будет собираться следующая статистика:

requests

Объект; метрики запросов

    total

Число; суммарное количество клиентских запросов

    discarded

Число; суммарное количество запросов завершенных без отправки ответа

responses

Объект; метрики ответов

    <code>

Число; ненулевое количество ответов со статусом <code> (100-599)

    xxx

Число; ненулевое количество ответов с другим кодом статуса

data

Объект; метрики данных

    received

Число; суммарное количество байт, полученное от клиентов

    sent

Число; суммарное количество байт, отправленное клиентам

Пример:

{
  "requests": {
    "total": 4158,
    "discarded": 0
  },

  "responses": {
    "200": 4157,
    "304": 1
  },

  "data": {
    "received": 538200,
    "sent": 177606236
  }
}

Stream server#

/status/stream/server_zones/<зона>#

Для сбора статистики в контексте server нужно задать директиву status_zone:

server {
    ...
    status_zone server_zone;
}

Для группировки метрик по пользовательскому значению используйте альтернативный синтаксис. В этом примере метрики агрегируются по $host, и каждая группа выводится как отдельная зона:

status_zone $host zone=server_zone:5;

В указанной таким образом зоне разделяемой памяти будет собираться следующая статистика:

ssl

Объект; SSL-метрики. Присутствует, если в server есть listen ssl;

    handshaked

Число; суммарное количество успешных SSL-рукопожатий

    reuses

Число; суммарное количество повторных использований SSL-сессий во время SSL-рукопожатий

    timedout

Число; суммарное количество SSL-рукопожатий с истекшим таймаутом

    failed

Число; суммарное количество неуспешных SSL-рукопожатий

connections

Объект; метрики соединений

    total

Число; суммарное количество клиентских соединений

    processing

Число; текущее количество обслуживаемых клиентских соединений

    discarded

Число; суммарное количество клиентских соединений, завершенных без создания сессии

    passed

Число; суммарное количество клиентских соединений, переданных на другой прослушивающий порт директивами pass

sessions

Объект; метрики сессий

    success

Число; количество сессий, завершенных с кодом 200, что означает успешное завершение

    invalid

Число; количество сессий, завершенных с кодом 400, случается, когда сервер не может прочитать данные от клиента, например, заголовок PROXY protocol

    forbidden

Число; количество сессий, завершенных с кодом 403, когда доступ запрещен, например, ограничен для определенного адреса клиента

    internal_error

Число; количество сессий, завершенных с кодом 500, внтуренняя ошибка сервера

    bad_gateway

Число; количество сессий, завершенных с кодом 502, Bad Gateway, если, например, сервер в upstream недоступен или не может быть выбран

    service_unavailable

Число; количество сессий, завершенных с кодом 503, Service Unavailable, если, например, доступ ограничен числом входящих соединений

data

Объект; метрики данных

    received

Число; суммарное количество байт, полученное от клиентов

    sent

Число; суммарное количество байт, отправленное клиентам

Пример:

{
  "ssl": {
    "handshaked": 24,
    "reuses": 0,
    "timedout": 0,
    "failed": 0
  },

  "connections": {
    "total": 24,
    "processing": 1,
    "discarded": 0,
    "passed": 2
  },

  "sessions": {
    "success": 24,
    "invalid": 0,
    "forbidden": 0,
    "internal_error": 0,
    "bad_gateway": 0,
    "service_unavailable": 0
  },

  "data": {
    "received": 2762947,
    "sent": 53495723
  }
}

HTTP caches#

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

Число; суммарное количество байт, записанных в кэш

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

В Angie PRO при включении шардинга кэша с помощью директив proxy_cache_path отдельные шарды указываются как объекты-члены в объекте shards:

shards

Объект; его члены — отдельные шарды

    <shard>

Объект; представляет отдельный шард, а имя объекта — путь кэша

        sizes

Число; текущий размер шарда

        max_size

Число; максимальный размер шарда, если задан в конфигурации

        cold

Логическое значение; true, пока загрузчик кэша подгружает данные с диска

{
  "name_zone": {
    "shards": {
        "/path/to/shard1": {
            "size": 0,
            "cold": false
        },

        "/path/to/shard2": {
            "size": 0,
            "cold": false
        }
    }
}

limit_conn#

limit_conn_zone $binary_remote_addr zone=limit_conn_zone:10m;

/status/http/limit_conns/<зона>, /status/stream/limit_conns/<зона>#

Каждая из сконфигурированных зон: 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/<зона>#

Каждая из сконфигурированных зон 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 (PRO)

        response_time
        (PRO 1.3.0+)

Число; среднее время (в миллисекундах) получения ответа от сервера; см. директиву response_time_factor (PRO)

    sid

Строка; id сервера, указанный в конфигурации апстрима

keepalive

Число; текущее количество кэшированных соединений

health/probes (PRO)#

Изменено в версии 1.2.0: PRO

Если для апстрима настроены проверки upstream_probe (PRO), то в объекте health также есть вложенный объект probes, содержащий счетчики проверок работоспособности сервера, а state, помимо значений из таблицы выше, может принимать значения checking и unhealthy:

{
    "192.168.16.4:80": {
        "state": "unhealthy",
        "...": "...",
        "health": {
            "...": "...",
            "probes": {
                "count": 10,
                "fails": 10,
                "last": "2025-02-13T09:56:07Z"
            }
        }
    }
}

Значение checking у state не учитывается в downtime и означает, что сервер, проверка которого настроена с параметром essential, еще не проверялся; значение unhealthy — что сервер неработающий. Оба эти состояния также означают, что сервер не участвует в балансировке. Детали проверок см. в описании upstream_probe.

Счетчики в probes:

count

Число; общее количество проверок этого сервера

fails

Число; количество неуспешных проверок

last

Строка или число; время последней проверки в формате даты

queue (PRO)#

Изменено в версии 1.4.0: PRO

Если для апстрима настроена очередь запросов, то в объекте апстрима также есть вложенный объект queue, содержащий счетчики запросов в очереди:

{
    "queue": {
        "queued": 20112,
        "waiting": 1011,
        "dropped": 6031,
        "timedout": 560,
        "overflows": 13
    }
}

Значения счетчиков суммируются по всем рабочим процессам:

queued

Число; общее количество запросов, попавших в очередь

waiting

Число; текущее количество запросов в очереди

dropped

Число; общее количество запросов, удаленных из очереди из-за того, что клиент преждевременно закрыл соединение

timedout

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

overflows

Число; общее количество случаев переполнения очереди

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: отключен вручную, не отправляются никакие запросы;

  • draining (PRO): аналогичен down, но отправляются запросы сессий, привязанных ранее через sticky;

  • 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 (PRO)

        first_byte_time
        (PRO 1.4.0+)

Число; среднее время (в миллисекундах) получения первого байта ответа от сервера; см. директиву response_time_factor (PRO)

        last_byte_time
        (PRO 1.4.0+)

Число; среднее время (в миллисекундах) получения полного ответа от сервера; см. директиву response_time_factor (PRO)

Изменено в версии 1.4.0: PRO

Если в Angie PRO для апстрима настроены проверки upstream_probe (PRO), то в объекте health также есть вложенный объект probes, содержащий счетчики проверок работоспособности сервера, а state, помимо значений из таблицы выше, может принимать значения checking и unhealthy:

{
    "192.168.16.4:80": {
        "state": "unhealthy",
        "...": "...",
        "health": {
            "...": "...",
            "probes": {
                "count": 2,
                "fails": 2,
                "last": "2025-02-13T11:03:54Z"
            }
        }
    }
}

Значение checking у state означает, что сервер, проверка которого настроена с параметром essential, еще не проверялся; значение unhealthy — что сервер неработающий. Оба эти состояния также означают, что сервер не участвует в балансировке. Детали проверок см. в описании upstream_probe.

Счетчики в probes:

count

Число; общее количество проверок этого сервера

fails

Число; количество неуспешных проверок

last

Строка или число; время последней проверки в формате даты

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

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

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

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

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

/config/http/upstreams/<upstream>/servers/<имя>#

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

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

<upstream>

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

<имя>

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

  • <service>@ — необязательная часть, задающая имя сервиса в целях разрешения SRV-записей.

  • <host> — доменное имя сервиса (при наличии resolve) или IP-адрес; также можно указать порт.

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

upstream backend {
    server backend.example.com 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/
$ curl http://127.0.0.1/config/http/upstreams/backend/servers/127.0.0.1:80/

Этот подраздел 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/<имя>#

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

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

<upstream>

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

<имя>

Имя конкретного сервера в составе указанного <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.

Примечание

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

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

Пример:

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

Фактически доступны будут только те параметры, которые поддерживает текущий метод балансировки нагрузки апстрима. Так, если апстрим настроен с методом балансировки 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/stream/upstreams/backend/servers/backend1.example.com

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

Примечание

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

При удалении серверов можно установить аргумент connection_drop=<значение> (PRO), чтобы переопределить настройки proxy_connection_drop:

$ curl -X DELETE \
    http://127.0.0.1/config/stream/upstreams/backend/servers/backend1.example.com?connection_drop=off

$ curl -X DELETE \
    http://127.0.0.1/config/stream/upstreams/backend/servers/backend2.example.com?connection_drop=on

$ curl -X DELETE \
    http://127.0.0.1/config/stream/upstreams/backend/servers/backend3.example.com?connection_drop=1000

HTTP-методы#

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

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 вернулся к значению по умолчанию.

При удалении серверов можно установить аргумент connection_drop=<значение> (PRO), чтобы переопределить настройки proxy_connection_drop, grpc_connection_drop, fastcgi_connection_drop, scgi_connection_drop и uwsgi_connection_drop:

$ curl -X DELETE \
    http://127.0.0.1/config/http/upstreams/backend/servers/backend1.example.com?connection_drop=off

$ curl -X DELETE \
    http://127.0.0.1/config/http/upstreams/backend/servers/backend2.example.com?connection_drop=on

$ curl -X DELETE \
    http://127.0.0.1/config/http/upstreams/backend/servers/backend3.example.com?connection_drop=1000

PATCH#

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