# 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](#metrics) sobre conexiones de clientes, zonas de memoria compartida, consultas DNS, peticiones HTTP, caché de respuestas HTTP, sesiones del módulo [stream](https://es.angie.software//angie/docs/configuration/modules/stream/index.md#stream-core) y zonas de los módulos [limit_conn http](https://es.angie.software//angie/docs/configuration/modules/http/http_limit_conn.md#http-limit-conn), [limit_conn stream](https://es.angie.software//angie/docs/configuration/modules/stream/stream_limit_conn.md#stream-limit-conn), [limit_req](https://es.angie.software//angie/docs/configuration/modules/http/http_limit_req.md#http-limit-req) y [http upstream](https://es.angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream). La interfaz admite métodos HTTP `GET` y `HEAD`; una petición con otro método provocará un error: ```json { "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](#api-config) que permite cambiar ajustes sin recargar la configuración ni reiniciar; actualmente, la configuración de servidores individuales dentro de [upstream](https://es.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) está disponible. ## Directivas ### api | [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile) | `api` path; | |--------------------------------------------------------------------------------------------|---------------| | Predeterminado | — | | [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile) | location | Habilita la interfaz RESTful HTTP en `location`. El parámetro path es obligatorio. Similar a la directiva [alias](https://es.angie.software//angie/docs/configuration/modules/http/index.md#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`: ```nginx 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: ```nginx 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: ```console $1 = "location" $2 = "data/" ``` Y la petición final será `/status/http/location_zones/data/`. #### NOTE En Angie PRO, puede separar la [API de configuración dinámica](#api-config) y la [API de estado](#metrics) inmutable que refleja el estado actual: ```nginx location /config/ { api /config/; } location /status/ { api /status/; } ``` El parámetro path también permite controlar el acceso a la API: ```nginx location /status/ { api /status/; allow 127.0.0.1; deny all; } ``` O: ```nginx location /blog/requests/ { api /status/http/server_zones/blog/requests/; auth_basic "blog"; auth_basic_user_file conf/htpasswd; } ``` #### NOTE Si `api` se coloca en un `location` con una barra final en el prefijo (por ejemplo, `location /name/`), y la directiva [auto_redirect](https://es.angie.software//angie/docs/configuration/modules/http/index.md#auto-redirect) está establecida en `default`, las peticiones sin barra final serán redirigidas (`/name -> /name/`). ### api_config_files | [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile) | `api_config_files` `on` | `off`; | |--------------------------------------------------------------------------------------------|------------------------------------| | Predeterminado | off | | [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile) | 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/](#status-angie). Por ejemplo, con esta configuración: ```nginx location /status/ { api /status/; api_config_files on; } ``` Una petición a `/status/angie/` devuelve aproximadamente lo siguiente: ```json { "version":"|version|", "address":"192.168.16.5", "generation":1, "load_time":"|sampledateshort|T12: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: ```nginx location /status/ { api /status/; } ``` Ejemplo de acceso parcial, ya mostrado anteriormente: ```nginx 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`: ```nginx 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 ```json { "angie": { "version":"|version|", "address":"192.168.16.5", "generation":1, "load_time":"|sampledateshort|T12: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":"" } }, "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: ```console $ curl https://www.example.com/status/angie $ curl https://www.example.com/status/connections $ curl https://www.example.com/status/slabs $ curl https://www.example.com/status/slabs//slots $ curl https://www.example.com/status/slabs//slots/64 $ curl https://www.example.com/status/http/ $ curl https://www.example.com/status/http/acme_clients $ curl https://www.example.com/status/http/acme_clients/ $ curl https://www.example.com/status/http/metric_zones $ curl https://www.example.com/status/http/metric_zones//metrics $ curl https://www.example.com/status/http/server_zones $ curl https://www.example.com/status/http/server_zones/ $ curl https://www.example.com/status/http/server_zones//ssl ``` #### NOTE Por defecto, el módulo utiliza cadenas de formato ISO 8601 para las fechas; para usar en su lugar el formato entero de época UNIX, añada el parámetro `date=epoch` a la cadena de consulta: ```console $ 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` ```json { "version": "|version|", "build_time": "|sampledateshort|T16:05:43.805Z", "address": "192.168.16.5", "generation": 1, "load_time": "|sampledateshort|T16: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](#api-date-format) | | `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](#api-date-format);
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:

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

#### WARNING
El objeto `config_files` está disponible en `/status/angie/`
solo si la directiva
[api_config_files](#a-api-config-files)
está habilitada. | #### `/status/angie/license` (PRO) ```json { "path": "/etc/angie/license.pem", "status": "valid", "owner": "Example Corp", "days_left": 30, "since": "2024-01-01", "until": "2025-01-01", "limits": { "worker_processes": 16, "worker_connections": 65535 } } ``` | `path` | Cadena; ruta completa al archivo de licencia | |-------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `status` | Cadena; estado de la licencia: `missing`, `invalid`, `valid`,
`grace`, `expired`, o `pending` | | `owner` | Cadena; propietario de la licencia del sujeto del certificado | | `days_left` | Número; días hasta que la licencia cambie de estado. Un valor negativo significa
que la licencia ha expirado, y el valor es el número de días desde
la expiración | | `since` | Cadena; fecha de inicio de validez de la licencia | | `until` | Cadena; fecha de fin de validez de la licencia | | `limits` | Objeto; límites licenciados para la instancia actual | ### Conexiones #### `/status/connections` ```json { "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/` 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-conn), [limit_req](#limit-req), y [caché HTTP](https://es.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache): ```nginx 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: ```json { "pages": { "used": 2, "free": 506 }, "slots": { "64": { "used": 1, "free": 63, "reqs": 1, "fails": 0 } } ``` ### Consultas DNS al resolvedor #### `/status/resolvers/` Para recopilar estadísticas del resolvedor, la directiva [resolver](https://es.angie.software//angie/docs/configuration/modules/http/index.md#resolver) debe establecer el parámetro `status_zone` ([HTTP](https://es.angie.software//angie/docs/configuration/modules/http/index.md#resolver-status) o [Stream](https://es.angie.software//angie/docs/configuration/modules/stream/index.md#s-resolver-status)): ```nginx 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 | #### NOTE `queries` y `responses` cuentan cada solicitud de resolución que Angie realiza internamente, incluidas las servidas desde la caché TTL. `sent` cuenta los paquetes realmente enviados al servidor de nombres; la diferencia entre ambos refleja los aciertos de caché. Los códigos de respuesta se describen en [RFC 1035](https://datatracker.ietf.org/doc/html/rfc1035.html), sección [4.1.1](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: ```json { "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/` Para recopilar las métricas de `server`, establezca la directiva [status_zone](https://es.angie.software//angie/docs/configuration/modules/http/index.md#status-zone) en el contexto [server](https://es.angie.software//angie/docs/configuration/modules/http/index.md#server): ```nginx 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](https://es.angie.software//angie/docs/configuration/modules/http/index.md#v-host), con cada grupo reportado como una zona independiente: ```nginx 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 | | `` | Número; un número distinto de cero de respuestas con estado (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: ```json { "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/` Para recopilar las métricas de `location`, establezca la directiva [status_zone](https://es.angie.software//angie/docs/configuration/modules/http/index.md#status-zone) en el contexto de [location](https://es.angie.software//angie/docs/configuration/modules/http/index.md#location) o [if in location](https://es.angie.software//angie/docs/configuration/modules/http/http_rewrite.md#if): ```nginx 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](https://es.angie.software//angie/docs/configuration/modules/http/index.md#v-host), con cada grupo reportado como una zona independiente: ```nginx 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 | | `` | Número; un número distinto de cero de respuestas con estado (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: ```json { "requests": { "total": 4158, "discarded": 0 }, "responses": { "200": 4157, "304": 1 }, "data": { "received": 538200, "sent": 177606236 } } ``` #### `/status/http/metric_zones/` Métricas personalizadas definidas por [metric_zone](https://es.angie.software//angie/docs/configuration/modules/http/http_metric.md#metric-zone) o [metric_complex_zone](https://es.angie.software//angie/docs/configuration/modules/http/http_metric.md#metric-complex-zone) en el contexto `http`. Las métricas se actualizan con la directiva [metric](https://es.angie.software//angie/docs/configuration/modules/http/http_metric.md#id3) o las variables del módulo. | `discarded` | Número; el número de entradas de métricas descartadas porque la zona se quedó sin
memoria. | |---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `metrics` | Objeto; métricas por clave. Para zonas de métrica única, los valores son números.
Para zonas complejas, los valores son objetos con nombres de métricas. Para el modo
histograma, los valores son objetos con nombres de buckets. | Si `discard_key` está configurado y algunas entradas han expirado, sus métricas agregadas se exponen bajo esta clave. Ejemplo: ```json { "discarded": 3, "metrics": { "example.com": { "count": 42, "max": 8 } "expired": { "count": 10, "max": 3.2 } } } ``` ### Servidor Stream #### `/status/stream/server_zones/` Para recopilar las métricas de `server`, establezca la directiva [status_zone](https://es.angie.software//angie/docs/configuration/modules/stream/index.md#s-status-zone) en el contexto [server](https://es.angie.software//angie/docs/configuration/modules/stream/index.md#s-server): ```nginx 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](https://es.angie.software//angie/docs/configuration/modules/http/index.md#v-host), con cada grupo reportado como una zona independiente: ```nginx 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: ```json { "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 } } ``` ### Cachés HTTP ```nginx proxy_cache cache_zone; proxy_cache_valid 200 10m; ``` #### `/status/http/caches/` Para cada zona configurada con [proxy_cache](https://es.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache), se almacenan los siguientes datos: ```json { "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](https://es.angie.software//angie/docs/configuration/modules/http/http_proxy.md#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](https://es.angie.software//angie/docs/configuration/modules/http/http_proxy.md#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](https://es.angie.software//angie/docs/configuration/modules/http/http_proxy.md#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](https://es.angie.software//angie/docs/configuration/modules/http/http_proxy.md#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](https://es.angie.software//angie/docs/configuration/modules/http/http_proxy.md#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](https://es.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-cache-path), los fragmentos individuales se exponen como miembros de objeto de un objeto `shards`: | `shards` | Objeto; enumera fragmentos individuales como miembros | |------------|-----------------------------------------------------------------------------| | `` | 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 | ```json { "name_zone": { "shards": { "/path/to/shard1": { "size": 0, "cold": false }, "/path/to/shard2": { "size": 0, "cold": false } } } ``` ### Clientes ACME #### `/status/http/acme_clients/` Para cada [acme_client](https://es.angie.software//angie/docs/configuration/modules/http/http_acme.md#acme-client) configurado en el bloque `http`, devuelve el estado actual del cliente y del certificado: ```json { "state": "ready", "certificate": "valid", "details": "The client is ready to request a certificate.", "next_run": "|sampledateshort|T16:15:43.805Z" } ``` | `state` | Cadena; estado del cliente ACME. Valores posibles: `ready`,
`requesting`, `disabled`, `failed`. | |---------------|------------------------------------------------------------------------------------------------------------------------------------------------| | `certificate` | Cadena; estado del certificado. Valores posibles: `valid`,
`expired`, `missing`, `mismatch`, `error`. | | `details` | Cadena; detalles breves del estado de la última operación ACME. | | `next_run` | Fecha; próximo intento programado para solicitar o renovar el certificado.
No se devuelve cuando `state` es `disabled` o
`requesting`. | ### limit_conn ```nginx limit_conn_zone $binary_remote_addr zone=limit_conn_zone:10m; ``` #### `/status/http/limit_conns/`, `/status/stream/limit_conns/` Objetos para cada [limit_conn en http](#limit-conn) o [limit_conn en stream](https://es.angie.software//angie/docs/configuration/modules/stream/stream_limit_conn.md#s-limit-conn) configurados con los siguientes campos: ```json { "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 ```nginx limit_req_zone $binary_remote_addr zone=limit_req_zone:10m rate=1r/s; ``` #### `/status/http/limit_reqs/` Objetos para cada [limit_req](#limit-req) configurado con los siguientes campos: ```json { "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](https://es.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone) en el contexto [upstream](https://es.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream), por ejemplo: ```nginx upstream upstream { zone upstream 256k; server backend.example.com service=_example._tcp resolve max_conns=5; keepalive 4; } ``` #### `/status/http/upstreams/` donde es el nombre de cualquier [upstream](https://es.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) especificado con la directiva [zone](https://es.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone) ```json { "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": "" } }, "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](https://es.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) | | `service` | Cadena; nombre del servicio tal como se especifica en la directiva [server](https://es.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server), si está configurado | | `backup` | Booleano; `true` para servidores de respaldo | | `weight` | Número; [peso](https://es.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) 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](https://es.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server),
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](https://es.angie.software//angie/docs/configuration/modules/http/http_upstream.md#slow-start),
cada vez se envían más solicitudes;
- `unavailable`: alcanzó el límite [max_fails](https://es.angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails),
solo se envían solicitudes de prueba del cliente
en intervalos definidos por [fail_timeout](https://es.angie.software//angie/docs/configuration/modules/http/http_upstream.md#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](https://es.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe);
- `draining`: similar a `down`,
pero las solicitudes de sesiones previamente enlazadas
(vía [sticky](https://es.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky)) siguen enviándose;
- `unhealthy`: no operativo,
solo se envían [solicitudes de sonda](https://es.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe). | | `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](#api-date-format) | | `max_conns` | Número; el número [máximo](https://es.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server) configurado de conexiones activas simultáneas al peer, si está especificado | | `responses` | Objeto; estadísticas de respuestas | | `` | Número; un número no cero de respuestas con estado (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](https://es.angie.software//angie/docs/configuration/modules/http/http_upstream.md#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](#api-date-format) | | `header_time` | Número; tiempo promedio (en milisegundos)
para recibir las cabeceras de respuesta del servidor;
ver [response_time_factor (PRO)](https://es.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-response-time-factor) | | `response_time` | Número; tiempo promedio (en milisegundos)
para recibir la respuesta completa del servidor;
ver [response_time_factor (PRO)](https://es.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-response-time-factor) | | `sid` | Cadena; [id configurado](https://es.angie.software//angie/docs/configuration/modules/http/http_upstream.md#reresolve) 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)](https://es.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-backup-switch) 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) #### Versionchanged Distinto en la versión 1.2.0: PRO Si el upstream tiene sondas [upstream_probe (PRO)](https://es.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe) 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`: ```json { "192.168.16.4:80": { "state": "unhealthy", "...": "...", "health": { "...": "...", "probes": { "count": 10, "fails": 10, "last": "|sampledateshort|T09: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](https://es.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-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](#api-date-format) | ##### `queue` (PRO) #### Versionchanged Distinto en la versión 1.4.0: PRO Si se configura una [cola de solicitudes](https://es.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-queue) para el upstream, el objeto upstream también contiene un objeto anidado `queue` con contadores de la cola de solicitudes: ```json { "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](https://es.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-zone) en el contexto [upstream](https://es.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-upstream), por ejemplo: ```nginx upstream upstream { zone upstream 256k; server backend.example.com service=_example._tcp resolve max_conns=5; keepalive 4; } ``` #### `/status/stream/upstreams/` Aquí, es el nombre de un [upstream](https://es.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) que está configurado con una directiva [zone](https://es.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone). ```json { "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](https://es.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server) | | `service` | Cadena; nombre del servicio, si está establecido por la directiva [server](https://es.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server) | | `backup` | Booleano; `true` para servidores de respaldo | | `weight` | Número; el [weight](https://es.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server) 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](https://es.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server),
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](https://es.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-slow-start),
se envían más y más solicitudes con el tiempo
- `unavailable`: alcanzó el límite [max_fails](https://es.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-max-fails),
solo se envían solicitudes de cliente de prueba
en intervalos definidos por [fail_timeout](https://es.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-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](https://es.angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#s-u-upstream-probe)
- `draining`: similar a `down`,
pero las solicitudes de sesiones previamente enlazadas
(mediante [sticky](https://es.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-sticky)) siguen enviándose
- `unhealthy`: no operativo,
solo se envían [solicitudes de sondeo](https://es.angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#s-u-upstream-probe) | | `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](#api-date-format) | | `max_conns` | Número;
número [máximo](https://es.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server)
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](https://es.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-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](#api-date-format) | | `connect_time` | Número; tiempo promedio (en milisegundos)
para establecer una conexión con el servidor;
consulte la directiva [response_time_factor (PRO)](https://es.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-response-time-factor) | | `first_byte_time` | Número; tiempo promedio (en milisegundos)
para recibir el primer byte de la respuesta del servidor;
consulte la directiva [response_time_factor (PRO)](https://es.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-response-time-factor) | | `last_byte_time` | Número; tiempo promedio (en milisegundos)
para recibir la respuesta completa del servidor;
consulte la directiva [response_time_factor (PRO)](https://es.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-response-time-factor) | | `backup_switch`
(PRO 1.10.0+) | Objeto; contiene el estado actual de la lógica de respaldo activo,
presente si [backup_switch (PRO)](https://es.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-backup-switch) 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) | #### Versionchanged Distinto en la versión 1.4.0: PRO En Angie PRO, si el upstream tiene sondas [upstream_probe (PRO)](https://es.angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#s-u-upstream-probe) 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`: ```json { "192.168.16.4:80": { "state": "unhealthy", "...": "...", "health": { "...": "...", "probes": { "count": 2, "fails": 2, "last": "|sampledateshort|T11: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, consulte [upstream_probe](https://es.angie.software//angie/docs/configuration/modules/stream/stream_upstream_probe.md#s-u-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-date-format) | ## 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](#api-config-http-upstreams-servers) y [stream](#api-config-stream-upstreams-servers); el número de ajustes elegibles para configuración dinámica está en constante aumento. #### `/config/http/upstreams//servers/` Permite configurar peers individuales de upstream, incluyendo eliminar peers existentes o añadir nuevos. Parámetros de la ruta URI: | `` | Nombre del upstream; para configurarlo vía `/config`, debe
tener configurada una directiva [zone](https://es.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone), que define una
zona de memoria compartida. | |----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `` | El nombre del peer dentro del upstream, definido como
`@`, donde:

- `@` es un nombre de servicio opcional, usado para
la resolución de registros SRV.
- `` 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: ```nginx upstream backend { server backend.example.com service=_http._tcp resolve; server 127.0.0.1; zone backend 1m; } ``` Permite los siguientes nombres de peer: ```console $ 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`, `slow_start`, `backup`, `down` y `sid`, tal como se describe en [server](https://es.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-server). #### NOTE No existe un parámetro separado `drain` (PRO); para habilitar `drain`, establezca `down` al valor de cadena `drain`: ```console $ curl -X PUT -d \"drain\" \ http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com/down ``` Ejemplo: ```console $ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com?defaults=on ``` ```json { "weight": 1, "max_conns": 0, "max_fails": 1, "fail_timeout": 10, "slow_start": 0, "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](https://es.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream). Por tanto, si el upstream está configurado con el método `random`: ```nginx upstream backend { zone backend 256k; server backend.example.com resolve max_conns=5; random; } ``` No podrá añadir un nuevo peer que defina `backup`: ```console $ curl -X PUT -d '{ "backup": true }' \ http://127.0.0.1/config/http/upstreams/backend/servers/backend1.example.com ``` ```json { "error": "FormatError", "description": "The \"backup\" field is unknown." } ``` #### NOTE 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//servers/` Permite configurar peers individuales de upstream, incluyendo eliminar peers existentes o añadir nuevos. Parámetros de la ruta URI: | `` | Nombre del bloque `upstream`;
para configurarlo vía `/config`,
debe tener configurada una directiva [zone](https://es.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-zone),
que define una zona de memoria compartida. | |----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `` | El nombre del peer dentro del upstream, definido como
`@`, donde:

- `@` es un nombre de servicio opcional, usado para
la resolución de registros SRV.
- `` 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: ```nginx 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: ```console $ 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`, `slow_start`, `backup` y `down`, tal como se describe en [server](https://es.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-server). #### NOTE No existe un parámetro separado `drain` (PRO); para habilitar el modo `drain`, establezca `down` al valor de cadena `drain`: ```console $ curl -X PUT -d \"drain\" \ http://127.0.0.1/config/stream/upstreams/backend/servers/backend.example.com/down ``` Ejemplo: ```console curl http://127.0.0.1/config/stream/upstreams/backend/servers/backend.example.com?defaults=on ``` ```json { "weight": 1, "max_conns": 0, "max_fails": 1, "fail_timeout": 10, "slow_start": 0, "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](https://es.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-upstream). Por tanto, si el upstream está configurado con el método `random`: ```nginx upstream backend { zone backend 256k; server backend.example.com resolve max_conns=5; random; } ``` No podrá añadir un nuevo peer que defina `backup`: ```console $ curl -X PUT -d '{ "backup": true }' \ http://127.0.0.1/config/stream/upstreams/backend/servers/backend1.example.com ``` ```json { "error": "FormatError", "description": "The \"backup\" field is unknown." } ``` #### NOTE 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=` (PRO) para anular la configuración de [proxy_connection_drop](https://es.angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-connection-drop): ```console $ 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: ```nginx 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: ```console $ 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 ``` Puede obtener valores de parámetros predeterminados con el argumento `defaults=on`: ```console $ curl http://127.0.0.1/config/http/upstreams/backend/servers?defaults=on ``` ```json { "backend.example.com": { "weight": 1, "max_conns": 5, "max_fails": 1, "fail_timeout": 10, "slow_start": 0, "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`: ```console $ curl -X PUT -d '2' \ http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com/max_fails ``` ```json { "success": "Updated", "description": "Existing configuration API entity \"/config/http/upstreams/backend/servers/backend.example.com/max_fails\" was updated with replacing." } ``` Verifica los cambios: ```console $ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com ``` ```json { "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`: ```console $ curl -X DELETE \ http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com/max_fails ``` ```console { "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`: ```console $ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com?defaults=on ``` ```json { "weight": 1, "max_conns": 5, "max_fails": 1, "fail_timeout": 10, "slow_start": 0, "backup": false, "down": false, "sid": "" } ``` El parámetro `max_fails` ha vuelto a su valor predeterminado. Al eliminar servidores, puede establecer el argumento `connection_drop=` (PRO) para anular las configuraciones de [proxy_connection_drop](https://es.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-connection-drop), [grpc_connection_drop](https://es.angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-connection-drop), [fastcgi_connection_drop](https://es.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-connection-drop), [scgi_connection_drop](https://es.angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-connection-drop) y [uwsgi_connection_drop](https://es.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-connection-drop): ```console $ 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](https://datatracker.ietf.org/doc/html/rfc7396)) 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: ```console $ curl -X PATCH -d '{ "down": true }' \ http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com ``` ```json { "success": "Updated", "description": "Existing configuration API entity \"/config/http/upstreams/backend/servers/backend.example.com\" was updated with merging." } ``` Verifica los cambios: ```console $ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com ``` ```json { "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. #### NOTE 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`: ```console $ curl -X PATCH -d '{ "down": null, "max_conns": 6 }' \ http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com ``` ```json { "success": "Updated", "description": "Existing configuration API entity \"/config/http/upstreams/backend/servers/backend.example.com\" was updated with merging." } ``` Verifica los cambios: ```console $ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com ``` ```json { "max_conns": 6 } ``` El parámetro `down`, para el cual se proporcionó un valor `null`, fue eliminado; el valor de `max_conns` fue actualizado.