API#

El módulo API implementa una interfaz RESTful HTTP para obtener información básica sobre el servidor web en formato JSON, así como estadísticas sobre conexiones de clientes, zonas de memoria compartida, consultas DNS, peticiones HTTP, caché de respuestas HTTP, sesiones del módulo stream y zonas de los módulos limit_conn http, limit_conn stream, limit_req y http upstream.

La interfaz admite métodos HTTP GET y HEAD; una petición con otro método provocará un error:

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

En Angie PRO, esta interfaz incluye una sección de configuración dinámica que permite cambiar ajustes sin recargar la configuración ni reiniciar; actualmente, la configuración de servidores individuales dentro de upstream está disponible.

Directivas#

api#

Sintaxis

api path;

Predeterminado

—

Contexto

location

Habilita la interfaz RESTful HTTP en location.

El parámetro path es obligatorio. Similar a la directiva alias, establece la ruta para reemplazar la que se especifica en location, pero sobre el árbol de la API en lugar del sistema de archivos.

Si se especifica en un prefijo location:

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

la parte del URI de la petición que coincide con el prefijo /stats/ será reemplazada con la ruta especificada en el parámetro path: /status/http/server_zones/. Por ejemplo, una petición a /stats/foo/ accederá al elemento de la API /status/http/server_zones/foo/.

Se permiten variables: api /status/$module/server_zones/$name/ y uso dentro de location con expresiones regulares:

location ~^/api/([^/]+)/(.*)$ {
    api /status/http/$1_zones/$2;
}

Aquí el parámetro path define la ruta completa al elemento de la API; así, de una petición a /api/location/data/ se extraerán las siguientes variables:

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

Y la petición final será /status/http/location_zones/data/.

Nota

En Angie PRO, puede separar la API de configuración dinámica y la API de estado inmutable que refleja el estado actual:

location /config/ {
    api /config/;
}

location /status/ {
    api /status/;
}

El parámetro path también permite controlar el acceso a la API:

location /status/ {
    api /status/;

    allow 127.0.0.1;
    deny  all;
}

O:

location /blog/requests/ {
    api /status/http/server_zones/blog/requests/;

    auth_basic           "blog";
    auth_basic_user_file conf/htpasswd;
}

api_config_files#

Sintaxis

api_config_files on | off;

Predeterminado

off

Contexto

location

Habilita o deshabilita la adición del objeto config_files, que lista el contenido de todos los archivos de configuración de Angie actualmente cargados por la instancia del servidor, a la sección de la API /status/angie/. Por ejemplo, con esta configuración:

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

Una petición a /status/angie/ devuelve aproximadamente lo siguiente:

{
    "version":"1.10.2",
    "address":"192.168.16.5",
    "generation":1,
    "load_time":"2025-08-21T12:58:39.789Z",
    "config_files": {
        "/etc/angie/angie.conf": "...",
        "/etc/angie/mime.types": "..."
    }
}

Por defecto, la salida está deshabilitada porque los archivos de configuración pueden contener información particularmente sensible y confidencial.

Métricas#

Angie publica estadísticas de uso en la sección de API /status/; puedes abrir el acceso a ella configurando la location adecuada. Acceso completo:

location /status/ {
    api /status/;
}

Ejemplo de acceso parcial, ya mostrado:

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

Ejemplo de configuración#

Con una configuración que incluye location /status/, resolver, http en upstream, http server, location, cache, limit_conn en http y 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;
        proxy_cache_valid 200 10m;

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

    }
}

En respuesta a la solicitud curl https://www.example.com/status/ Angie devuelve:

JSON tree
{
    "angie": {
        "version":"1.10.2",
        "address":"192.168.16.5",
        "generation":1,
        "load_time":"2025-08-21T12: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
            }
        }
    }
}

Se puede solicitar un conjunto de métricas por rama JSON individual construyendo la solicitud adecuada. Por ejemplo:

$ 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

Nota

Por defecto, el módulo utiliza cadenas de formato ISO 8601 para fechas; para usar el formato de época UNIX entero en su lugar, añade el parámetro date=epoch a la cadena de consulta:

$ 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

Estado del servidor#

/status/angie#

{
    "version": "1.10.2",
    "build_time": "2025-08-21T16:05:43.805Z",
    "address": "192.168.16.5",
    "generation": 1,
    "load_time": "2025-08-21T16:15:43.805Z"
    "config_files": {
        "/etc/angie/angie.conf": "...",
        "/etc/angie/mime.types": "..."
    }
}

version

Cadena; versión del servidor web Angie en ejecución

build

Cadena; nombre de construcción particular cuando se especifica durante la compilación

build_time

Cadena; tiempo de compilación del ejecutable Angie en el formato date

address

Cadena; la dirección del servidor que aceptó la petición API

generation

Número; número total de recargas de configuración desde el último inicio

load_time

Cadena; tiempo de la última recarga de configuración en el formato date; las cadenas tienen resolución en milisegundos

config_files

Objeto; sus miembros son rutas absolutas de todos los archivos de configuración de Angie que están actualmente cargados por la instancia del servidor, y sus valores son representaciones en cadena del contenido de los archivos, por ejemplo:

{
    "/etc/angie/angie.conf": "server {\n  listen 80;\n  # ...\n\n}\n"
}

Advertencia

El objeto config_files está disponible en /status/angie/ solo si la directiva api_config_files está habilitada.

Conexiones#

/status/connections#

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

accepted

Número; el total de conexiones de clientes aceptadas

dropped

Número; el total de conexiones de clientes descartadas

active

Número; el total actual de conexiones de clientes activas

idle

Número; el total actual de conexiones de clientes ociosas

Memorias compartidas con asignación slab#

/status/slabs/<zone>#

Estadísticas de uso de zonas de memoria compartida que utilizan asignación slab <https://en.wikipedia.org/wiki/Slab_allocation>_, como limit_conn, limit_req, y 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;
proxy_cache_valid 200 10m;

La zona de memoria compartida especificada recogerá las siguientes estadísticas:

pages

Objeto; estadísticas de páginas de memoria

used

Número; el número de páginas de memoria actualmente utilizadas

free

Número; el número de páginas de memoria actualmente libres

slots

Objeto; estadísticas de slots de memoria para cada tamaño de slot. El objeto slots contiene datos para tamaños de slots de memoria (8, 16, 32, etc., hasta la mitad del tamaño de la página en bytes)

used

Número; el número de slots de memoria actualmente utilizados del tamaño especificado

free

Número; el número de slots de memoria actualmente libres del tamaño especificado

reqs

Número; el número total de intentos de asignar memoria del tamaño especificado

fails

Número; el número de intentos fallidos de asignar memoria del tamaño especificado

Ejemplo:

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

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

Consultas DNS al resolvedor#

/status/resolvers/<zone>#

Para recopilar estadísticas del resolvedor, la directiva resolver debe establecer el parámetro status_zone (HTTP o Stream):

resolver 127.0.0.53 status_zone=resolver_zone;

La zona de memoria compartida especificada recopilará las siguientes estadísticas:

queries

Objeto; estadísticas de consultas

name

Número; la cantidad de consultas para resolver nombres a direcciones (consultas A y AAAA)

srv

Número; la cantidad de consultas para resolver servicios a direcciones (consultas SRV)

addr

Número; la cantidad de consultas para resolver direcciones a nombres (consultas PTR)

responses

Objeto; estadísticas de respuestas

success

Número; la cantidad de respuestas exitosas

timedout

Número; la cantidad de consultas agotadas por tiempo

format_error

Número; la cantidad de respuestas con código 1 (Formato error)

server_failure

Número; la cantidad de respuestas con código 2 (Fallo del servidor)

not_found

Número; la cantidad de respuestas con código 3 (Name Error)

unimplemented

Número; la cantidad de respuestas con código 4 (Not Implemented)

refused

Número; la cantidad de respuestas con código 5 (Rechazado)

other

Número; la cantidad de consultas completadas con otro código distinto de cero

sent

Objeto; estadísticas de consultas DNS enviadas

a

Número; la cantidad de consultas de tipo A

aaaa

Número; la cantidad de consultas de tipo AAAA

ptr

Número; la cantidad de consultas de tipo PTR

srv

Número; la cantidad de consultas de tipo SRV

Los códigos de respuesta se describen en RFC 1035 <https://datatracker.ietf.org/doc/html/rfc1035.html>, sección <https://datatracker.ietf.org/doc/html/rfc1035.html#section-4.1.1>.

Los diversos tipos de registros DNS se detallan en RFC 1035 <https://datatracker.ietf.org/doc/html/rfc1035.html>, RFC 2782 <https://datatracker.ietf.org/doc/html/rfc2782.html>, y RFC 3596 <https://datatracker.ietf.org/doc/html/rfc3596.html>.

Ejemplo:

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

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

Servidor HTTP y ubicación#

/status/http/server_zones/<zone>#

Para recopilar las métricas de server, establezca la directiva status_zone en el contexto server:

server {
    ...
    status_zone server_zone;
}

Para agrupar las métricas por un valor personalizado, utilice la sintaxis alternativa. Aquí, las métricas se agregan por $host, con cada grupo reportado como una zona independiente:

status_zone $host zone=server_zone:5;

La zona de memoria compartida especificada recopilará las siguientes estadísticas:

ssl

Objeto; estadísticas SSL. Presente si server establece listen ssl;

handshaked

Número; el número total de handshakes SSL exitosos

reuses

Número; el número total de reutilizaciones de sesión durante el handshake SSL

timedout

Número; el número total de handshakes SSL que agotaron el tiempo de espera

failed

Número; el número total de handshakes SSL fallidos

requests

Objeto; estadísticas de solicitudes

total

Número; el número total de solicitudes de clientes

processing

Número; el número de solicitudes de clientes que se están procesando actualmente

discarded

Número; el número total de solicitudes de clientes completadas sin enviar una respuesta

responses

Objeto; estadísticas de respuestas

<code>

Número; un número distinto de cero de respuestas con estado <code> (100-599)

xxx

Número; un número distinto de cero de respuestas con otros códigos de estado

data

Objeto; estadísticas de datos

received

Número; el total de bytes recibidos de los clientes

sent

Número; el total de bytes enviados a los clientes

Ejemplo:

{
    "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/<zone>#

Para recopilar las métricas de location, configure la directiva status_zone en el contexto de location o if in location:

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

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

Para agrupar las métricas por un valor personalizado, utilice la sintaxis alternativa. Aquí, las métricas se agrupan por $host, reportándose cada grupo como una zona independiente:

status_zone $host zone=server_zone:5;

La zona de memoria compartida especificada recopilará las siguientes estadísticas:

requests

Objeto; estadísticas de solicitudes

total

Número; el total de solicitudes de clientes

discarded

Número; el total de solicitudes de clientes completadas sin enviar una respuesta

responses

Objeto; estadísticas de respuestas

<code>

Número; un número distinto de cero de respuestas con estado <code> (100-599)

xxx

Número; un número distinto de cero de respuestas con otros códigos de estado

data

Objeto; estadísticas de datos

received

Número; el total de bytes recibidos de los clientes

sent

Número; el total de bytes enviados a los clientes

Ejemplo:

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

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

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

Stream server#

/status/stream/server_zones/<zone>#

Para recopilar las métricas de server, configure la directiva status_zone en el contexto server:

server {
    ...
    status_zone server_zone;
}

Para agrupar las métricas por un valor personalizado, utilice la sintaxis alternativa. Aquí, las métricas se agrupan por $host, reportándose cada grupo como una zona independiente:

status_zone $host zone=server_zone:5;

La zona de memoria compartida especificada recopilará las siguientes estadísticas:

ssl

Objeto; estadísticas SSL. Presente si server establece listen ssl;

handshaked

Número; el número total de handshakes SSL exitosos

reuses

Número; el número total de reutilizaciones de sesión durante el handshake SSL

timedout

Número; el número total de handshakes SSL que agotaron el tiempo de espera

failed

Número; el número total de handshakes SSL fallidos

connections

Objeto; estadísticas de conexiones

total

Número; el número total de conexiones de clientes

processing

Número; el número de conexiones de clientes que se están procesando actualmente

discarded

Número; el número total de conexiones de clientes completadas sin crear una sesión

passed

Número; el número total de conexiones de clientes redirigidas a otro puerto con directivas pass

sessions

Objeto; estadísticas de sesiones

success

Número; el número de sesiones completadas con código 200, lo que indica finalización exitosa

invalid

Número; el número de sesiones completadas con código 400, cuando los datos del cliente no pudieron analizarse (por ejemplo, cabecera PROXY)

forbidden

Número; el número de sesiones completadas con código 403, cuando se restringió el acceso

internal_error

Número; el número de sesiones completadas con código 500, error interno

bad_gateway

Número; el número de sesiones completadas con código 502, bad gateway

service_unavailable

Número; el número de sesiones completadas con código 503, servicio no disponible

data

Objeto; estadísticas de datos

received

Número; el total de bytes recibidos de los clientes

sent

Número; el total de bytes enviados a los clientes

Ejemplo:

{
  "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;
proxy_cache_valid 200 10m;

/status/http/caches/<cache>#

Para cada zona configurada con proxy_cache, se almacenan los siguientes datos:

{
  "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

Número; el tamaño actual de la caché

max_size

Número; límite configurado para el tamaño máximo de la caché

cold

Booleano; true mientras el cargador de caché carga datos desde el disco

hit

Objeto; estadísticas de respuestas válidas en caché (proxy_cache_valid)

responses

Número; el número total de respuestas leídas desde la caché

bytes

Número; el número total de bytes leídos desde la caché

stale

Objeto; estadísticas de respuestas caducadas tomadas de la caché (proxy_cache_use_stale)

responses

Número; el número total de respuestas leídas desde la caché

bytes

Número; el número total de bytes leídos desde la caché

updating

Objeto; estadísticas de respuestas caducadas tomadas de la caché mientras se actualizaban las respuestas (proxy_cache_use_stale updating)

responses

Número; el número total de respuestas leídas desde la caché

bytes

Número; el número total de bytes leídos desde la caché

revalidated

Objeto; estadísticas de respuestas caducadas y revalidadas tomadas de la caché (proxy_cache_revalidate)

responses

Número; el número total de respuestas leídas desde la caché

bytes

Número; el número total de bytes leídos desde la caché

miss

Objeto; estadísticas de respuestas no encontradas en la caché

responses

Número; el número total de respuestas correspondientes

bytes

Número; el número total de bytes leídos desde el servidor proxy

responses_written

Número; el número total de respuestas escritas en la caché

bytes_written

Número; el número total de bytes escritos en la caché

expired

Objeto; estadísticas de respuestas caducadas no tomadas de la caché

responses

Número; el número total de respuestas correspondientes

bytes

Número; el número total de bytes leídos desde el servidor proxy

responses_written

Número; el número total de respuestas escritas en la caché

bytes_written

Número; el número total de bytes escritos en la caché

bypass

Objeto; estadísticas de respuestas no buscadas en la caché (proxy_cache_bypass)

responses

Número; el número total de respuestas correspondientes

bytes

Número; el número total de bytes leídos desde el servidor proxy

responses_written

Número; el número total de respuestas escritas en la caché

bytes_written

Número; el número total de bytes escritos en la caché

Added in version 1.2.0: PRO

En Angie PRO, si el caché está particionado con directivas proxy_cache_path, los fragmentos individuales se exponen como miembros de un objeto shards:

shards

Objeto; enumera fragmentos individuales como miembros

<shard>

Objeto; representa un fragmento individual con su ruta de caché como nombre

size

Número; el tamaño actual del fragmento

max_size

Número; tamaño máximo del fragmento, si está configurado

cold

Booleano; true mientras el cargador de caché carga datos desde el disco

{
  "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/<zone>, /status/stream/limit_conns/<zone>#

Objetos para cada limit_conn en http o limit_conn en stream configurados con los siguientes campos:

{
  "passed": 73,
  "skipped": 0,
  "rejected": 0,
  "exhausted": 0
}

passed

Número; el total de conexiones aceptadas

skipped

Número; el total de conexiones aceptadas con clave de longitud cero, o clave que excede 255 bytes

rejected

Número; el total de conexiones que exceden el límite configurado

exhausted

Número; el total de conexiones rechazadas por agotamiento del almacenamiento de la zona

limit_req#

limit_req_zone $binary_remote_addr zone=limit_req_zone:10m rate=1r/s;

/status/http/limit_reqs/<zone>#

Objetos para cada limit_req configurado con los siguientes campos:

{
  "passed": 54816,
  "skipped": 0,
  "delayed": 65,
  "rejected": 26,
  "exhausted": 0
}

passed

Número; el total de solicitudes aceptadas

skipped

Número; el total de solicitudes aceptadas con clave de longitud cero, o clave que excede 255 bytes

delayed

Número; el total de solicitudes retrasadas

rejected

Número; el total de solicitudes rechazadas

exhausted

Número; el total de solicitudes rechazadas por agotamiento del almacenamiento de la zona

HTTP upstream#

Added in version 1.1.0.

Para habilitar la recopilación de las siguientes métricas, establezca la directiva zone en el contexto upstream, por ejemplo:

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

/status/http/upstreams/<upstream>#

donde <upstream> es el nombre de cualquier upstream especificado con la directiva 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

Objeto; contiene las métricas de los peers del upstream como subobjetos cuyas nombres son representaciones canónicas de las direcciones de los peers. Miembros de cada subobjeto:

server

Cadena; el parámetro de la directiva server

service

Cadena; nombre del servicio tal como se especifica en la directiva server, si está configurado

slow_start
(PRO 1.4.0+)

Número; el valor especificado slow_start para el servidor, expresado en segundos.

Al establecer el valor vía la subsección respectiva /config/http/upstreams/<upstream>/servers/<name> de la API de configuración dinámica, puede especificar un número de segundos o un valor de tiempo con precisión de milisegundos.

backup

Booleano; true para servidores de respaldo

weight

Número; el peso configurado de la directiva server

state

Cadena; el estado actual del peer y qué solicitudes se le envían:

  • busy: indica que el número de solicitudes al servidor ha alcanzado el límite establecido por max_conns, y no se envían nuevas solicitudes;

  • down: deshabilitado manualmente, no se envían solicitudes;

  • recovering: se recupera tras un fallo según slow_start, cada vez se envían más solicitudes;

  • unavailable: alcanzó el límite max_fails, solo se envían solicitudes de prueba en intervalos definidos por fail_timeout;

  • up: operativo, las solicitudes se envían como de costumbre;

Estados adicionales en Angie PRO:

  • checking: configurado como essential y siendo verificado, solo se envían probe requests;

  • draining: similar a down, pero las solicitudes de sesiones previamente enlazadas (a través de sticky) siguen enviándose;

  • unhealthy: no operativo, solo se envían probe requests.

selected

Objeto; las métricas de selección del peer

current

Número; el número actual de conexiones al peer

total

Número; el número total de conexiones reenviadas al peer

last

Cadena o número; momento en que el peer fue seleccionado por última vez, formateado como una fecha

max_conns

Número; el máximo configurado de conexiones simultáneas al peer, si está especificado

data

Objeto; métricas de transferencia de datos

received

Número; el total de bytes recibidos del peer

sent

Número; el total de bytes enviados al peer

health

Objeto; métricas de salud

fails

Número; el total de intentos fallidos de comunicarse con el peer

unavailable

Número; cuántas veces el peer se volvió unavailable por haber llegado al límite de max_fails

downtime

Número; el tiempo total (en milisegundos) que el peer estuvo unavailable para la selección

downstart

Cadena o número; momento en que el peer se volvió unavailable, formateado como una fecha

connect_time
(PRO 1.4.0+)

Número; tiempo promedio (en milisegundos) para establecer una conexión con el peer; ver la directiva response_time_factor (PRO).

first_byte_time
(PRO 1.4.0+)

Número; tiempo promedio (en milisegundos) para recibir el primer byte de la respuesta del peer; ver la directiva response_time_factor (PRO).

last_byte_time
(PRO 1.4.0+)

Número; tiempo promedio (en milisegundos) para recibir la respuesta completa del peer; ver la directiva response_time_factor (PRO).

backup_switch (PRO 1.10.0+)

Objeto; contiene el estado actual de la lógica de respaldo activa, presente si backup_switch (PRO) está configurado para el upstream

active

Número; nivel del grupo activo actualmente utilizado para equilibrar la carga de solicitudes. Si el grupo activo es el primario, el valor es 0

timeout

Número; tiempo de espera restante en milisegundos, después del cual el equilibrador de carga volverá a comprobar nodos sanos en grupos con niveles inferiores, a partir del grupo primario; no se muestra para el grupo primario (nivel 0)

Distinto en la versión 1.4.0: PRO

En Angie PRO, si el upstream tiene sondas upstream_probe (PRO) configuradas, el objeto health también tiene un subobjeto probes que almacena los contadores de sondas de salud del peer, mientras que el estado del peer puede ser checking y unhealthy, además de los valores listados en la tabla anterior:

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

El valor checking de state significa que el peer, que tiene una sonda configurada como essential, aún no ha sido verificado; el valor unhealthy significa que el peer está funcionando incorrectamente. Ambos estados también implican que el peer no está incluido en el balanceo de carga. Para detalles sobre sondas de salud, consulte upstream_probe.

Contadores en probes:

count

Número; sondas totales para este peer

fails

Número; sondas fallidas totales

last

Cadena o número; hora de la última sonda, formateada como una fecha

queue (PRO)#

Distinto en la versión 1.4.0: PRO

Si se configura una cola de solicitudes para el upstream, el objeto upstream también contiene un objeto anidado queue con contadores de la cola de solicitudes:

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

Los valores de los contadores se suman en todos los procesos de trabajo:

queued

Número; número total de solicitudes que entraron en la cola

waiting

Número; número actual de solicitudes en la cola

dropped

Número; número total de solicitudes eliminadas de la cola porque el cliente cerró la conexión prematuramente

timedout

Número; número total de solicitudes eliminadas de la cola por tiempo de espera

overflows

Número; número total de ocurrencias de desbordamiento de la cola

Upstream de flujo#

Para habilitar la recopilación de las siguientes métricas, establezca la directiva zone en el contexto upstream, por ejemplo:

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

/status/stream/upstreams/<upstream>#

Aquí, <upstream> es el nombre de un upstream que está configurado con una directiva 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

Objeto; contiene las métricas de los peers del upstream como subobjetos cuyas nombres son representaciones canónicas de las direcciones de los peers. Miembros de cada subobjeto:

server

Cadena; dirección establecida por la directiva server

service

Cadena; nombre del servicio, si está establecido por la directiva server

slow_start
(PRO 1.4.0+)

Número; el valor especificado slow_start para el servidor, expresado en segundos.

Al establecer el valor a través de la subsección correspondiente de la API de configuración dinámica, puede especificar un número o un valor de tiempo con precisión de milisegundos.

backup

Booleano; true para servidor de respaldo

weight

Número; el weight del peer

state

Cadena; el estado actual del peer y qué solicitudes se envían:

  • busy: indica que el número de solicitudes al servidor ha alcanzado el límite establecido por max_conns, y no se envían nuevas solicitudes

  • down: deshabilitado manualmente, no se envían solicitudes

  • recovering: recuperándose tras una falla según slow_start, se envían más y más solicitudes con el tiempo

  • unavailable: alcanzó el límite max_fails, solo se envían solicitudes de cliente de prueba en intervalos definidos por fail_timeout;

  • up: operativo, las solicitudes se envían como de costumbre

Estados adicionales en Angie PRO:

  • checking: configurado como essential y estando verificado, solo se envían probe requests

  • draining: similar a down, pero las solicitudes de sesiones previamente enlazadas (mediante sticky) siguen enviándose

  • unhealthy: no operativo, solo se envían probe requests

selected

Objeto; métricas de selección del peer

current

Número; conexiones actuales al peer

total

Número; conexiones totales reenviadas al peer

last

Cadena o número; momento en que el peer fue seleccionado por última vez, formateado como una fecha

max_conns

Número; el máximo configurado de conexiones activas simultáneas al peer, si está establecido

data

Objeto; métricas de transferencia de datos

received

Número; bytes totales recibidos del peer

sent

Número; bytes totales enviados al peer

health

Objeto; métricas de salud

fails

Número; total de intentos fallidos de alcanzar al peer

unavailable

Número; cuántas veces el peer se volvió unavailable por alcanzar el límite max_fails

downtime

Número; tiempo total (en milisegundos) que el peer estuvo unavailable para selección

downstart

Cadena o número; momento en que el peer se volvió unavailable, formateado como una fecha

connect_time
(PRO 1.4.0+)

Número; tiempo promedio (en milisegundos) para establecer una conexión con el peer; ver la directiva response_time_factor (PRO).

first_byte_time
(PRO 1.4.0+)

Número; tiempo promedio (en milisegundos) para recibir el primer byte de la respuesta del peer; ver la directiva response_time_factor (PRO).

last_byte_time
(PRO 1.4.0+)

Número; tiempo promedio (en milisegundos) para recibir la respuesta completa del peer; ver la directiva response_time_factor (PRO).

backup_switch (PRO 1.10.0+)

Objeto; contiene el estado actual de la lógica de respaldo activo, presente si backup_switch (PRO) está configurado para el upstream

active

Número; nivel del grupo activo actualmente utilizado para el balanceo de la carga. Si el grupo activo es el primario, el valor es 0

timeout

Número; tiempo de espera restante en milisegundos, tras el cual el equilibrador de carga volverá a comprobar nodos sanos en grupos con niveles inferiores, empezando por el grupo primario; no se muestra para el grupo primario (nivel 0)

Distinto en la versión 1.4.0: PRO

En Angie PRO, si el upstream tiene sondas de upstream upstream_probe (PRO) configuradas, el objeto health también tiene un subobjeto probes que almacena los contadores de sondas de salud del peer, mientras que el estado del peer puede ser checking y unhealthy, además de los valores listados en la tabla anterior:

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

El valor checking de state significa que el peer, que tiene una sonda configurada como essential, aún no ha sido verificado; el valor unhealthy significa que el peer está funcionando mal. Ambos estados también implican que el peer no está incluido en el balanceo de carga. Para detalles sobre sondas de salud, consulte upstream_probe.

Contadores en probes:

count

Número; total de sondas para este peer

fails

Número; total de sondas fallidas

last

Cadena o número; hora de la última sonda, formateada como una fecha

API de Configuración Dinámica (solo PRO)#

Added in version 1.2.0: PRO

La API incluye una sección /config que permite actualizaciones dinámicas a la configuración de Angie en formato JSON con peticiones HTTP PUT, PATCH y DELETE. Todas las actualizaciones son atómicas; los nuevos ajustes se aplican en su totalidad, o ninguno se aplica. En caso de error, Angie informa la razón.

Subsecciones de /config#

Actualmente, la configuración de servidores individuales dentro de upstreams está disponible en la sección /config para los módulos HTTP y stream; el número de ajustes elegibles para configuración dinámica está en constante aumento.

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

Permite configurar peers individuales de upstream, incluyendo eliminar peers existentes o añadir nuevos.

Parámetros de la ruta URI:

<upstream>

Nombre del upstream; para configurarlo vía /config, debe tener configurada una directiva zone, que define una zona de memoria compartida.

<name>

El nombre del peer dentro del upstream, definido como <service>@<host>, donde:

  • <service>@ es una parte opcional que especifica el nombre del servicio para resolver SRV.

  • <host> es el nombre de dominio del servicio (cuando resolve está presente) o su IP; también puede definirse un puerto.

Por ejemplo, la siguiente configuración:

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

Permite los siguientes nombres de peer:

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

Esta subsección de la API permite establecer los parámetros weight, max_conns, max_fails, fail_timeout, backup, down y sid, tal como se describe en la sección server.

Nota

No existe un parámetro separado drain (PRO); para habilitar drain, establezca down al valor de cadena drain:

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

Ejemplo:

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

Actualmen­te disponibles son los parámetros soportados por el método de balanceo actual del upstream. Por ejemplo, si el upstream está configurado con el método de balanceo random:

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

No podrás añadir un nuevo peer que defina 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."
}

Nota

Incluso con un método de balanceo compatible, el parámetro backup solo puede establecerse al añadir un nuevo peer.

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

Permite configurar servidores individuales dentro de un upstream, incluyendo añadir nuevos y eliminar los ya configurados.

Parámetros en la ruta URI:

<upstream>

Nombre del bloque upstream; para configurarlo vía /config, debe contener la directiva zone que define una zona de memoria compartida.

<name>

Nombre de un servidor específico dentro del <upstream> especificado; especificado en el formato <service>@<host>, donde:

  • <service>@ — parte opcional que especifica el nombre del servicio para resolver SRV.

  • <host> — nombre de dominio del servicio (cuando resolve está presente) o IP; también se puede especificar el puerto.

Por ejemplo, para la siguiente configuración:

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

Estos nombres de servidor son válidos:

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

Esta subsección de la API permite establecer los parámetros weight, max_conns, max_fails, fail_timeout, backup, y down descritos en la sección server.

Nota

No existe un parámetro separado drain (PRO); para habilitar el modo drain, establezca el parámetro down al valor de cadena drain:

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

Ejemplo:

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

Solo aquellos parámetros que son compatibles con el método de balanceo de carga actual del upstream <s_u_upstream> estarán realmente disponibles. Por ejemplo, si el upstream está configurado con el método de balanceo random:

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

Entonces es imposible añadir un nuevo servidor con el parámetro 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."
}

Nota

Incluso con un método de balanceo compatible, el parámetro backup solo puede establecerse al añadir un nuevo servidor.

Al eliminar servidores, puede establecer el argumento connection_drop=<value> (PRO) para anular las configuraciones de proxy_connection_drop, grpc_connection_drop, fastcgi_connection_drop, scgi_connection_drop y uwsgi_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

Métodos HTTP#

Consideremos la semántica de todos los métodos HTTP aplicables a esta sección, dada esta configuración de upstream:

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#

El método HTTP GET consulta una entidad en cualquier ruta existente dentro de /config, tal como lo hace para otras secciones de la API.

Por ejemplo, la rama del servidor upstream /config/http/upstreams/backend/servers/ permite estas consultas:

$ 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

Puedes obtener valores predeterminados con 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#

El método HTTP PUT crea una nueva entidad JSON en la ruta especificada o reemplaza completamente una existente.

Por ejemplo, para establecer el parámetro max_fails, no especificado anteriormente, del servidor backend.example.com dentro del upstream 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."
}

Verifica los cambios:

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

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

DELETE#

El método HTTP DELETE elimina configuraciones previamente definidas en la ruta especificada; al hacerlo, vuelve a los valores predeterminados si los hay.

Por ejemplo, para eliminar el parámetro max_fails previamente establecido del servidor backend.example.com dentro del upstream 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."
}

Verifica los cambios usando 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": ""
}

La configuración max_fails ha vuelto a su valor predeterminado.

Al eliminar servidores, puedes establecer el argumento connection_drop=<value> (PRO) para anular las configuraciones proxy_connection_drop, grpc_connection_drop, fastcgi_connection_drop, scgi_connection_drop y 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#

El método HTTP PATCH crea una nueva entidad en la ruta especificada o reemplaza parcialmente o complementa una existente (RFC 7386) proporcionando una definición JSON en su carga útil.

El método opera de la siguiente manera: si las entidades de la nueva definición existen en la configuración, se sobrescriben; de lo contrario, se añaden.

Por ejemplo, para cambiar la configuración down del servidor backend.example.com dentro del upstream, dejando el resto intacto:

$ 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."
}

Verifica los cambios:

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

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

La API devuelve el objeto JSON proporcionado con la solicitud PATCH fusionado con el existente, en lugar de reemplazarlo, como ocurriría con PUT.

Los valores nulos son un caso especial; se utilizan para eliminar elementos concretos de configuración durante dicha fusión.

Nota

Esta eliminación es idéntica a DELETE; en particular, restablece los valores a sus predeterminados.

Por ejemplo, para eliminar la configuración down añadida anteriormente y, al mismo tiempo, actualizar 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."
}

Verifica los cambios:

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

{
    "max_conns": 6
}

El parámetro down, para el cual se proporcionó un null, fue eliminado; max_conns fue actualizado.