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

Nota

Si api se coloca en un location con una barra final en el prefijo (por ejemplo, location /name/), y la directiva auto_redirect está establecida en default, las peticiones sin barra final serán redirigidas (/name -> /name/).

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.3",
    "address":"192.168.16.5",
    "generation":1,
    "load_time":"2025-11-13T12:58:39.789Z",
    "config_files": {
        "/etc/angie/angie.conf": "...",
        "/etc/angie/angie.conf": "..."
    }
}

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

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 zonas 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.3",
        "address":"192.168.16.5",
        "generation":1,
        "load_time":"2025-11-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
            }
        }
    }
}

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.3",
    "build_time": "2025-11-13T16:05:43.805Z",
    "address": "192.168.16.5",
    "generation": 1,
    "load_time": "2025-11-13T16: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 compilación particular si 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; los valores de cadena 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 número total de conexiones de clientes aceptadas

dropped

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

active

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

idle

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

Zonas de memoria compartida con asignación slab#

/status/slabs/<zone>#

Estadísticas de uso de zonas de memoria compartida que utilizan asignación slab, como limit_conn, limit_req, y caché HTTP:

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; el número de consultas para resolver nombres a direcciones (consultas A y AAAA)

srv

Número; el número de consultas para resolver servicios a direcciones (consultas SRV)

addr

Número; el número de consultas para resolver direcciones a nombres (consultas PTR)

responses

Objeto; estadísticas de respuestas

success

Número; el número de respuestas exitosas

timedout

Número; el número de consultas agotadas por tiempo

format_error

Número; el número de respuestas con código 1 (Format Error)

server_failure

Número; el número de respuestas con código 2 (Server Failure)

not_found

Número; el número de respuestas con código 3 (Name Error)

unimplemented

Número; el número de respuestas con código 4 (Not Implemented)

refused

Número; el número de respuestas con código 5 (Refused)

other

Número; el número de consultas completadas con otro código distinto de cero

sent

Objeto; estadísticas de consultas DNS enviadas

a

Número; el número de consultas de tipo A

aaaa

Número; el número de consultas de tipo AAAA

ptr

Número; el número de consultas de tipo PTR

srv

Número; el número de consultas de tipo SRV

Los códigos de respuesta se describen en RFC 1035, sección 4.1.1.

Los diversos tipos de registros DNS se detallan en RFC 1035, RFC 2782, y RFC 3596.

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 número total de bytes recibidos de los clientes

sent

Número; el número 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, establezca 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 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:

requests

Objeto; estadísticas de solicitudes

total

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

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 número total de bytes recibidos de los clientes

sent

Número; el número 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, 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

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 de escucha con directivas pass

sessions

Objeto; estadísticas de sesiones

success

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

invalid

Número; el número de sesiones completadas con código 400, lo que ocurre cuando los datos del cliente no pudieron analizarse, por ejemplo, la cabecera del protocolo PROXY

forbidden

Número; el número de sesiones completadas con código 403, cuando se prohibió el acceso, por ejemplo, cuando el acceso está limitado para ciertas direcciones de clientes

internal_error

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

bad_gateway

Número; el número de sesiones completadas con código 502, bad gateway, por ejemplo, si no se pudo seleccionar o alcanzar un servidor upstream

service_unavailable

Número; el número de sesiones completadas con código 503, servicio no disponible, por ejemplo, cuando el acceso está limitado por el número de conexiones

data

Objeto; estadísticas de datos

received

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

sent

Número; el número 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 cache loader 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 obsoletas 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 obsoletas 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 expiradas 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 expiradas 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é

En Angie PRO, si el cache sharding está habilitado con directivas proxy_cache_path, los fragmentos individuales se exponen como miembros de objeto 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 cache loader 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 número total de conexiones aceptadas

skipped

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

rejected

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

exhausted

Número; el número 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 número total de solicitudes aceptadas

skipped

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

delayed

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

rejected

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

exhausted

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

HTTP upstream#

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 cuyos 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 slow_start especificado para el servidor, expresado en segundos.

Al establecer el valor vía la subsección respectiva 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; peso configurado

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: recuperándose 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 del cliente 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 solicitudes de sonda;

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

  • unhealthy: no operativo, solo se envían solicitudes de sonda.

selected

Objeto; estadísticas de selección del peer

current

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

total

Número; número total de solicitudes 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 número máximo configurado de conexiones activas simultáneas al peer, si está especificado

responses

Objeto; estadísticas de respuestas

<code>

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

xxx

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

data

Objeto; estadísticas de datos

received

Número; el número total de bytes recibidos del peer

sent

Número; el número total de bytes enviados al peer

health

Objeto; estadísticas de salud

fails

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

unavailable

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

downtime

Número; el 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

header_time
(PRO 1.3.0+)

Número; tiempo promedio (en milisegundos) para recibir las cabeceras de respuesta del servidor; ver response_time_factor (PRO)

response_time
(PRO 1.3.0+)

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

sid

Cadena; id configurado del servidor en el grupo upstream

keepalive

Número; el número actual de conexiones en caché

backup_switch

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; el nivel del grupo activo que se utiliza actualmente para el balanceo de 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 balanceador volverá a verificar nodos sanos en grupos con niveles inferiores, comenzando por el grupo primario, mientras que los grupos con niveles superiores no se verifican; no se muestra para el grupo primario (nivel 0)

health/probes (PRO)#

Distinto en la versión 1.2.0: 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 servidor, mientras que state, además de los valores listados en la tabla anterior, también puede ser checking y unhealthy:

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

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

Contadores en probes:

count

Número; sondas totales para este servidor

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

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 cuyos 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 de segundos o un valor de tiempo con precisión de milisegundos.

backup

Booleano; true para servidores de respaldo

weight

Número; el weight establecido para el peer

state

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

  • 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 siendo verificado, solo se envían solicitudes de sondeo

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

  • unhealthy: no operativo, solo se envían solicitudes de sondeo

selected

Objeto; estadísticas sobre la selección de este peer para conexiones

current

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

total

Número; 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; número máximo de conexiones activas simultáneas al peer, si está establecido

data

Objeto; estadísticas de transferencia de datos

received

Número; bytes totales recibidos del peer

sent

Número; bytes totales enviados al peer

health

Objeto; estadísticas de salud del peer

fails

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

unavailable

Número; número total de veces que el peer se volvió unavailable debido a alcanzar el valor max_fails

downtime

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

downstart

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

connect_time

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

first_byte_time

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

last_byte_time

Número; tiempo promedio (en milisegundos) para recibir la respuesta completa del servidor; 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 carga. Si el grupo activo es el grupo primario, el valor es 0

timeout

Número; tiempo de espera restante en milisegundos tras el cual el balanceador de carga volverá a verificar nodos sanos en grupos con niveles inferiores, empezando por el grupo primario, mientras que los grupos con niveles superiores no se verifican; 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 servidor, mientras que state, además de los valores de la tabla anterior, también puede ser checking y unhealthy:

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

El valor checking de state significa que el servidor, que tiene una sonda configurada con el parámetro essential, aún no ha sido verificado; el valor unhealthy significa que el servidor no está operativo. Ambos estados también significan que el servidor no está incluido en el balanceo de carga. Para detalles de las sondas de salud, ver upstream_probe.

Contadores en probes:

count

Número; número total de sondas para este servidor

fails

Número; número de sondas fallidas

last

Cadena o número; momento de la última sonda, formateado como una fecha

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

La API incluye una sección /config que permite actualizaciones dinámicas a la configuración de Angie en formato JSON con solicitudes HTTP PUT, PATCH y DELETE. Todas las actualizaciones son atómicas: los nuevos ajustes se aplican en su totalidad, o ninguno se aplica en absoluto. 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 un nombre de servicio opcional, usado para la resolución de registros SRV.

  • <host> es el nombre de dominio del servicio (si resolve está presente) o su IP; se puede definir un puerto opcional aquí.

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

Los parámetros realmente disponibles están limitados a los que son compatibles con el método de balanceo de carga actual del upstream. Por tanto, si el upstream está configurado con el método random:

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

No podrá 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 de carga compatible, el parámetro backup solo puede establecerse al añadir un nuevo peer.

/config/stream/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 bloque 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 un nombre de servicio opcional, usado para la resolución de registros SRV.

  • <host> es el nombre de dominio del servicio (si resolve está presente) o su IP; se puede definir un puerto opcional aquí.

Por ejemplo, la siguiente configuración:

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

Permite los siguientes nombres de peer:

$ 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, tal como se describe en server.

Nota

No existe un parámetro separado drain (PRO); para habilitar el modo drain, establezca 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,
}

Los parámetros realmente disponibles están limitados a los que son compatibles con el método de balanceo de carga actual del upstream. Por tanto, si el upstream está configurado con el método random:

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

No podrá añadir un nuevo peer que defina 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 de carga compatible, el parámetro backup solo puede establecerse al añadir un nuevo peer.

Al eliminar peers, puede establecer el argumento connection_drop=<value> (PRO) para anular las configuraciones de 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

Métodos HTTP#

Consideremos la semántica de cada método HTTP aplicable a esta sección utilizando la siguiente configuración de upstream como ejemplo:

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 de parámetros predeterminados con el argumento 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 añadir el parámetro max_fails, no especificado anteriormente, al 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, restaura los valores predeterminados si los hay.

Por ejemplo, para eliminar el parámetro max_fails previamente modificado 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 el argumento 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": ""
}

El parámetro 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 el parámetro down del servidor backend.example.com dentro del upstream backend, 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
}

Observa que el objeto JSON proporcionado con la solicitud PATCH se fusionó con el existente en lugar de reemplazarlo completamente, como ocurriría con PUT.

Los valores null son un caso especial; se utilizan para eliminar elementos específicos de configuración durante dicha fusión.

Nota

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

Por ejemplo, para eliminar el parámetro down añadido anteriormente y simultáneamente 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 valor null, fue eliminado; el valor de max_conns fue actualizado.