API#

O módulo API implementa uma interface HTTP RESTful para obter informações básicas sobre o servidor web em formato JSON, bem como estatísticas sobre conexões de clientes, zonas de memória compartilhada, consultas DNS, requisições HTTP, cache de resposta HTTP, sessões do módulo stream e zonas dos módulos limit_conn http, limit_conn stream, limit_req e http upstream, bem como informações sobre os certificados especificados na configuração e obtidos por clientes ACME.

Nota

Veja um exemplo ao vivo da saída da API em https://console.angie.software/api/.

A interface aceita os métodos HTTP GET e HEAD; uma requisição com outro método causará um erro:

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

No Angie PRO, esta interface inclui uma seção de configuração dinâmica que permite alterar configurações sem recarregar a configuração ou reiniciar; atualmente, a configuração de servidores individuais dentro de upstream está disponível.

Diretivas#

api#

Sintaxe	`api` path;
Padrão	—
Contexto	location

Habilita a interface HTTP RESTful em location.

O parâmetro path é obrigatório. Similar à diretiva alias, ele define o caminho para substituir aquele especificado em location, mas sobre a árvore da API ao invés do sistema de arquivos.

Se especificado em um location de prefixo:

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

a parte da URI da requisição que corresponde ao prefixo /stats/ será substituída pelo caminho especificado no parâmetro path: /status/http/server_zones/. Por exemplo, uma requisição para /stats/foo/ acessará o elemento da API /status/http/server_zones/foo/.

Variáveis são permitidas: api /status/$module/server_zones/$name/ e uso dentro de location regex:

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

Aqui o parâmetro path define o caminho completo para o elemento da API; assim, de uma requisição para /api/location/data/ as seguintes variáveis serão extraídas:

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

E a requisição final será /status/http/location_zones/data/.

Nota

No Angie PRO, você pode separar a API de configuração dinâmica e a API de status imutável que reflete o estado atual:

location /config/ {
    api /config/;
}

location /status/ {
    api /status/;
}

O parâmetro path também permite controlar o acesso à API:

location /status/ {
    api /status/;

    allow 127.0.0.1;
    deny  all;
}

Ou:

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

    auth_basic           "blog";
    auth_basic_user_file conf/htpasswd;
}

Nota

Se api for colocado em um location com uma barra final no prefixo (por exemplo, location /name/), e a diretiva auto_redirect estiver definida como default, requisições sem uma barra final serão redirecionadas (/name -> /name/).

api_config_files#

Sintaxe	`api_config_files` `on` \| `off`;
Padrão	off
Contexto	location

Habilita ou desabilita a adição do objeto config_files, que lista o conteúdo de todos os arquivos de configuração do Angie atualmente carregados pela instância do servidor, à seção da API /status/angie/. Por exemplo, com esta configuração:

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

Uma requisição para /status/angie/ retorna aproximadamente o seguinte:

{
    "version":"1.12.1",
    "address":"192.168.16.5",
    "generation":1,
    "load_time":"2026-07-17T12:58:39.789Z",
    "config_files": {
        "/etc/angie/angie.conf": "...",
        "/etc/angie/mime.types": "..."
    }
}

Por padrão, a saída está desabilitada porque os arquivos de configuração podem conter informações particularmente sensíveis e confidenciais.

Métricas#

O Angie publica estatísticas de uso na seção da API /status/; você pode abrir acesso a ela definindo o location apropriado. Acesso completo:

location /status/ {
    api /status/;
}

Exemplo de acesso parcial, já mostrado acima:

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

Exemplo de configuração#

Com uma configuração incluindo location /status/, resolver, http em upstream, http server, location, cache, limit_conn em http e 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;
        }

    }
}

Em resposta à requisição curl https://www.example.com/status/, o Angie retorna:

Árvore JSON

{
    "angie": {
        "version":"1.12.1",
        "address":"192.168.16.5",
        "generation":1,
        "load_time":"2026-07-17T12: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
            }
        }
    }
}

Um conjunto de métricas pode ser solicitado por ramo JSON individual construindo a requisição apropriada. Por exemplo:

$ 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/acme_clients
$ curl https://www.example.com/status/http/acme_clients/<client>
$ curl https://www.example.com/status/http/metric_zones
$ curl https://www.example.com/status/http/metric_zones/<zone>/metrics
$ 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

Argumentos da query string#

Os seguintes argumentos da query string modificam as respostas JSON da API:

pretty

Por padrão, a API formata as respostas JSON com recuo e quebras de linha. Para obter uma saída compacta de uma única linha, adicione pretty=off à query string:

$ curl https://www.example.com/status/connections?pretty=off

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

date

Por padrão, o módulo usa strings de formato ISO 8601 para datas; para usar o formato inteiro UNIX epoch em vez disso, adicione o parâmetro date=epoch à query string:

$ 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

defaults (PRO)

Você pode obter valores de parâmetros padrão com o 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,
        "slow_start": 0,
        "backup": false,
        "down": false,
        "sid": ""
    }
}

Status do servidor#

`/status/angie`#

{
    "version": "1.12.1",
    "build_time": "2026-07-17T16:05:43.805Z",
    "address": "192.168.16.5",
    "generation": 1,
    "load_time": "2026-07-17T16:15:43.805Z"
    "config_files": {
        "/etc/angie/angie.conf": "...",
        "/etc/angie/mime.types": "..."
    }
}

`version`	String; versão do servidor web Angie em execução
`build`	String; nome específico da build se especificado durante a compilação
`build_time`	String; o tempo de build do executável Angie no formato de data
`address`	String; o endereço do servidor que aceitou a requisição da API
`generation`	Number; número total de recarregamentos de configuração desde o último início
`load_time`	String; tempo do último recarregamento de configuração no formato de data; valores string têm resolução de milissegundos
`config_files`	Object; seus membros são nomes de caminho absolutos de todos os arquivos de configuração do Angie que estão atualmente carregados pela instância do servidor, e seus valores são representações string do conteúdo dos arquivos, por exemplo: { "/etc/angie/angie.conf": "server {\n listen 80;\n # ...\n\n}\n" } Aviso O objeto `config_files` está disponível em `/status/angie/` apenas se a diretiva api_config_files estiver habilitada.

`/status/angie/license` (PRO)#

Adicionado na versão 1.11.0: PRO

{
    "path": "/etc/angie/license.pem",
    "status": "valid",
    "owner": "Example Corp",
    "days_left": 30,
    "since": "2026-01-01",
    "until": "2027-01-01",
    "limits": {
        "worker_processes": 16,
        "worker_connections": 65535
    }
}

`path`	String; caminho completo para o arquivo de licença
`status`	String; status da licença: `missing`, `invalid`, `valid`, `grace`, `expired`, ou `pending`
`owner`	String; proprietário da licença do assunto do certificado
`days_left`	Number; dias até que a licença mude de estado. Um valor negativo significa que a licença expirou, e o valor é o número de dias desde a expiração
`since`	String; data de início de validade da licença
`until`	String; data de término de validade da licença
`limits`	Object; limites licenciados para a instância atual

Conexões#

`/status/connections`#

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

`accepted`	Number; o número total de conexões de cliente aceitas
`dropped`	Number; o número total de conexões de cliente descartadas
`active`	Number; o número atual de conexões de cliente ativas
`idle`	Number; o número atual de conexões de cliente ociosas

Zonas de memória compartilhada com alocação slab#

`/status/slabs/<zone>`#

Estatísticas de uso de zonas de memória compartilhada que utilizam alocação slab. Qualquer zona que utilize alocação slab é informada, incluindo as de limit_conn, limit_req e cache HTTP, bem como a zona de memória compartilhada de um upstream HTTP ou stream:

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;

A zona de memória compartilhada especificada coletará as seguintes estatísticas:

`pages`	Object; estatísticas de páginas de memória
`used`	Number; o número de páginas de memória atualmente em uso
`free`	Number; o número de páginas de memória atualmente livres
`slots`	Object; estatísticas de slots de memória para cada tamanho de slot. O objeto `slots` contém dados para tamanhos de slot de memória (`8`, `16`, `32`, etc., até metade do tamanho da página em bytes)
`used`	Number; o número de slots de memória atualmente em uso do tamanho especificado
`free`	Number; o número de slots de memória atualmente livres do tamanho especificado
`reqs`	Number; o número total de tentativas de alocar memória do tamanho especificado
`fails`	Number; o número de tentativas malsucedidas de alocar memória do tamanho especificado

Exemplo:

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

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

Consultas DNS ao resolver#

`/status/resolvers/<zone>`#

Para coletar estatísticas do resolver, a diretiva resolver deve definir o parâmetro status_zone (HTTP ou Stream):

resolver 127.0.0.53 status_zone=resolver_zone;

A zona de memória compartilhada especificada coletará as seguintes estatísticas:

`queries`	Object; estatísticas de consultas
`name`	Number; o número de consultas para resolver nomes para endereços (consultas A e AAAA)
`srv`	Number; o número de consultas para resolver serviços para endereços (consultas SRV)
`addr`	Number; o número de consultas para resolver endereços para nomes (consultas PTR)
`responses`	Object; estatísticas de respostas
`success`	Number; o número de respostas bem-sucedidas
`timedout`	Number; o número de consultas que expiraram
`format_error`	Number; o número de respostas com código 1 (Format Error)
`server_failure`	Number; o número de respostas com código 2 (Server Failure)
`not_found`	Number; o número de respostas com código 3 (Name Error)
`unimplemented`	Number; o número de respostas com código 4 (Not Implemented)
`refused`	Number; o número de respostas com código 5 (Refused)
`other`	Number; o número de consultas completadas com outro código não-zero
`sent`	Object; estatísticas de consultas DNS enviadas
`a`	Number; o número de consultas do tipo A
`aaaa`	Number; o número de consultas do tipo AAAA
`ptr`	Number; o número de consultas do tipo PTR
`srv`	Number; o número de consultas do tipo SRV

Nota

queries e responses contabilizam cada solicitação de resolução que o Angie faz internamente, incluindo as servidas pelo cache TTL. sent contabiliza os pacotes efetivamente enviados ao servidor de nomes; a diferença entre os dois reflete os acertos de cache.

Os códigos de resposta são descritos na RFC 1035, seção 4.1.1.

Vários tipos de registro DNS são detalhados na RFC 1035, RFC 2782, e RFC 3596.

Exemplo:

{
  "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 e localização#

`/status/http/server_zones/<zone>`#

Para coletar as métricas do server, defina a diretiva status_zone no contexto server:

server {
    ...
    status_zone server_zone;
}

Para agrupar as métricas por um valor personalizado, use a sintaxe alternativa. Aqui, as métricas são agregadas por $host, com cada grupo relatado como uma zona independente:

status_zone $host zone=server_zone:5;

A zona de memória compartilhada especificada coletará as seguintes estatísticas:

`ssl`	Object; estatísticas SSL. Presente se `server` definir `listen ssl;`
`handshaked`	Number; o número total de handshakes SSL bem-sucedidos
`reuses`	Number; o número total de reutilizações de sessão durante o handshake SSL
`timedout`	Number; o número total de handshakes SSL que expiraram
`failed`	Number; o número total de handshakes SSL que falharam
`requests`	Object; estatísticas de requisições
`total`	Number; o número total de requisições de clientes
`processing`	Number; o número de requisições de clientes sendo processadas atualmente
`discarded`	Number; o número total de requisições de clientes concluídas sem enviar uma resposta
`responses`	Object; estatísticas de respostas
`<code>`	Number; um número não-zero de respostas com status <code> (100-599)
`xxx`	Number; um número não-zero de respostas com outros códigos de status
`data`	Object; estatísticas de dados
`received`	Number; o número total de bytes recebidos de clientes
`sent`	Number; o número total de bytes enviados para clientes

Nota

Os contadores responses registram apenas respostas reais, ou seja, aquelas que foram efetivamente enviadas ao cliente. Uma requisição cujo processamento terminou sem enviar uma resposta é contabilizada em discarded e não incrementa os contadores responses. Em particular, 499 não é uma resposta, mas um código de serviço interno, registrado apenas no log de acesso, que marca uma requisição cujo processamento terminou sem que uma resposta fosse enviada; tais requisições são refletidas em discarded, nunca em responses.

Exemplo:

{
    "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 coletar as métricas do location, defina a diretiva status_zone no contexto de location ou if in location:

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

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

Para agrupar as métricas por um valor personalizado, use a sintaxe alternativa. Aqui, as métricas são agregadas por $host, com cada grupo relatado como uma zona independente:

status_zone $host zone=server_zone:5;

A zona de memória compartilhada especificada coletará as seguintes estatísticas:

`requests`	Object; estatísticas de requisições
`total`	Number; o número total de requisições de clientes
`discarded`	Number; o número total de requisições de clientes concluídas sem enviar uma resposta
`responses`	Object; estatísticas de respostas
`<code>`	Number; um número não-zero de respostas com status <code> (100-599)
`xxx`	Number; um número não-zero de respostas com outros códigos de status
`data`	Object; estatísticas de dados
`received`	Number; o número total de bytes recebidos de clientes
`sent`	Number; o número total de bytes enviados para clientes

Nota

Os contadores responses registram apenas respostas reais, ou seja, aquelas que foram efetivamente enviadas ao cliente. Uma requisição cujo processamento terminou sem enviar uma resposta é contabilizada em discarded e não incrementa os contadores responses. Em particular, 499 não é uma resposta, mas um código de serviço interno, registrado apenas no log de acesso, que marca uma requisição cujo processamento terminou sem que uma resposta fosse enviada; tais requisições são refletidas em discarded, nunca em responses.

Exemplo:

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

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

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

`/status/http/metric_zones/<zone>`#

Métricas personalizadas definidas por metric_zone ou metric_complex_zone no contexto http. As métricas são atualizadas com a diretiva metric ou as variáveis do módulo.

`discarded`	Number; o número de entradas de métricas descartadas porque a zona ficou sem memória.
`metrics`	Object; métricas por chave. Para zonas de métrica única, os valores são números. Para zonas complexas, os valores são objetos com nomes de métricas. Para o modo histograma, os valores são objetos com nomes de buckets.

Se discard_key estiver definido e algumas entradas tiverem expirado, suas métricas agregadas são expostas sob esta chave.

Exemplo:

{
    "discarded": 3,
    "metrics": {
        "example.com": {
            "count": 42,
            "max": 8
        }
        "expired": {
            "count": 10,
            "max": 3.2
        }
    }
}

Servidor stream#

`/status/stream/server_zones/<zone>`#

Para coletar as métricas do server, defina a diretiva status_zone no contexto server:

server {
    ...
    status_zone server_zone;
}

Para agrupar as métricas por um valor personalizado, use a sintaxe alternativa. Aqui, as métricas são agregadas por $server_addr, com cada grupo relatado como uma zona independente:

status_zone $server_addr zone=server_zone:5;

A zona de memória compartilhada especificada coletará as seguintes estatísticas:

`ssl`	Object; estatísticas SSL. Presente se `server` definir `listen ssl;`
`handshaked`	Number; o número total de handshakes SSL bem-sucedidos
`reuses`	Number; o número total de reutilizações de sessão durante o handshake SSL
`timedout`	Number; o número total de handshakes SSL que expiraram
`failed`	Number; o número total de handshakes SSL que falharam
`connections`	Object; estatísticas de conexões
`total`	Number; o número total de conexões de clientes
`processing`	Number; o número de conexões de clientes sendo processadas atualmente
`discarded`	Number; o número total de conexões de clientes concluídas sem criar uma sessão
`passed`	Number; o número total de conexões de clientes redirecionadas para outra porta de escuta com diretivas `pass`
`sessions`	Object; estatísticas de sessões
`success`	Number; o número de sessões concluídas com código 200, que significa conclusão bem-sucedida
`invalid`	Number; o número de sessões concluídas com código 400, que acontece quando os dados do cliente não puderam ser analisados, por exemplo, o cabeçalho do protocolo PROXY
`forbidden`	Number; o número de sessões concluídas com código 403, quando o acesso foi proibido, por exemplo, quando o acesso é limitado para determinados endereços de clientes
`internal_error`	Number; o número de sessões concluídas com código 500, erro interno do servidor
`bad_gateway`	Number; o número de sessões concluídas com código 502, gateway inválido, por exemplo, se um servidor upstream não pôde ser selecionado ou alcançado
`service_unavailable`	Number; o número de sessões concluídas com código 503, serviço indisponível, por exemplo, quando o acesso é limitado pelo número de conexões
`data`	Object; estatísticas de dados
`received`	Number; o número total de bytes recebidos de clientes
`sent`	Number; o número total de bytes enviados para clientes

Exemplo:

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

`/status/stream/metric_zones/<zone>`#

Métricas personalizadas definidas por metric_zone ou metric_complex_zone no contexto stream. As métricas são atualizadas com a diretiva metric ou com as variáveis do módulo.

`discarded`	Número; o número de entradas de métricas descartadas porque a zona ficou sem memória.
`metrics`	Objeto; métricas por chave. Para zonas de métrica única, os valores são números. Para zonas complexas, os valores são objetos com nomes de métricas. Para o modo histograma, os valores são objetos com nomes de bucket.

Se discard_key estiver configurado e algumas entradas tiverem expirado, suas métricas agregadas são expostas sob esta chave.

Exemplo:

{
    "discarded": 3,
    "metrics": {
        "127.0.0.1": {
            "count": 42,
            "max": 8
        },
        "expired": {
            "count": 10,
            "max": 3.2
        }
    }
}

Caches HTTP#

proxy_cache cache_zone;
proxy_cache_valid 200 10m;

`/status/http/caches/<cache>`#

Para cada zona configurada com proxy_cache, os seguintes dados são armazenados:

{
  "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; o tamanho atual do cache
`max_size`	Número; limite configurado para o tamanho máximo do cache
`cold`	Booleano; `true` enquanto o cache loader carrega dados do disco
`hit`	Objeto; estatísticas de respostas válidas em cache (proxy_cache_valid)
`responses`	Número; o número total de respostas lidas do cache
`bytes`	Número; o número total de bytes lidos do cache
`stale`	Objeto; estatísticas de respostas obsoletas obtidas do cache (proxy_cache_use_stale)
`responses`	Número; o número total de respostas lidas do cache
`bytes`	Número; o número total de bytes lidos do cache
`updating`	Objeto; estatísticas de respostas obsoletas obtidas do cache enquanto as respostas estavam sendo atualizadas (proxy_cache_use_stale updating)
`responses`	Número; o número total de respostas lidas do cache
`bytes`	Número; o número total de bytes lidos do cache
`revalidated`	Objeto; estatísticas de respostas expiradas e revalidadas obtidas do cache (proxy_cache_revalidate)
`responses`	Número; o número total de respostas lidas do cache
`bytes`	Número; o número total de bytes lidos do cache
`miss`	Objeto; estatísticas de respostas não encontradas no cache
`responses`	Número; o número total de respostas correspondentes
`bytes`	Número; o número total de bytes lidos do servidor com proxy
`responses_written`	Número; o número total de respostas escritas no cache
`bytes_written`	Número; o número total de bytes escritos no cache
`expired`	Objeto; estatísticas de respostas expiradas não obtidas do cache
`responses`	Número; o número total de respostas correspondentes
`bytes`	Número; o número total de bytes lidos do servidor com proxy
`responses_written`	Número; o número total de respostas escritas no cache
`bytes_written`	Número; o número total de bytes escritos no cache
`bypass`	Objeto; estatísticas de respostas não consultadas no cache (proxy_cache_bypass)
`responses`	Número; o número total de respostas correspondentes
`bytes`	Número; o número total de bytes lidos do servidor com proxy
`responses_written`	Número; o número total de respostas escritas no cache
`bytes_written`	Número; o número total de bytes escritos no cache

No Angie PRO, se o cache sharding estiver habilitado com diretivas proxy_cache_path, fragmentos individuais são expostos como membros de objeto de um objeto shards:

`shards`	Objeto; lista fragmentos individuais como membros
`<shard>`	Objeto; representa um fragmento individual com seu caminho de cache como nome
`size`	Número; o tamanho atual do fragmento
`max_size`	Número; tamanho máximo do fragmento, se configurado
`cold`	Booleano; `true` enquanto o cache loader carrega dados do disco

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

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

Clientes ACME#

`/status/http/acme_clients/<client>`#

Para cada acme_client configurado no bloco http, retorna o status atual do cliente e do certificado:

{
  "state": "ready",
  "certificate": "valid",
  "details": "The client is ready to request a certificate.",
  "next_run": "2026-07-17T16:15:43.805Z"
}

`state`	String; estado do cliente ACME. Valores possíveis: `ready`, `requesting`, `disabled`, `failed`.
`certificate`	String; status do certificado. Valores possíveis: `valid`, `expired`, `missing`, `mismatch`, `error`.
`details`	String; detalhes breves do status da última operação ACME.
`next_run`	Data; próxima tentativa agendada para solicitar ou renovar o certificado. Não retornado quando `state` é `disabled` ou `requesting`.

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 em http ou limit_conn em stream configurado nos contextos com os seguintes campos:

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

`passed`	Número; o número total de conexões aprovadas
`skipped`	Número; o número total de conexões aprovadas com chave de comprimento zero, ou chave excedendo 255 bytes
`rejected`	Número; o número total de conexões excedendo o limite configurado
`exhausted`	Número; o número total de conexões rejeitadas devido ao esgotamento do armazenamento da 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 com os seguintes campos:

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

`passed`	Número; o número total de requisições aprovadas
`skipped`	Número; o número total de requisições aprovadas com chave de comprimento zero, ou chave excedendo 255 bytes
`delayed`	Número; o número total de requisições atrasadas
`rejected`	Número; o número total de requisições rejeitadas
`exhausted`	Número; o número total de requisições rejeitadas devido ao esgotamento do armazenamento da zona

HTTP upstream#

Para habilitar a coleta das seguintes métricas, defina a diretiva zone no contexto upstream, por exemplo:

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

O uso de memória desta zona de memória compartilhada é informado na seção da API /status/slabs/, indexado pelo nome da zona.

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

onde <upstream> é o nome de qualquer upstream especificado com a diretiva 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; contém as métricas dos peers do upstream como subobjetos cujos nomes são representações canônicas dos endereços dos peers. Membros de cada subobjeto:
`server`	String; o parâmetro da diretiva server
`service`	String; nome do serviço como especificado na diretiva server, se configurado
`backup`	Booleano; `true` para servidores de backup
`weight`	Número; peso configurado
`state`	String; o estado atual do peer e quais requisições são enviadas para ele: `busy`: indica que o número de requisições para o servidor atingiu o limite definido por max_conns, e nenhuma nova requisição é enviada para ele; `down`: desabilitado manualmente, nenhuma requisição é enviada; `draining`: similar a `down`, mas requisições de sessões previamente vinculadas (via sticky) ainda são enviadas; `recovering`: recuperando após uma falha de acordo com slow_start, mais e mais requisições são enviadas ao longo do tempo; `unavailable`: atingiu o limite max_fails, apenas requisições de teste do cliente são enviadas em intervalos definidos por fail_timeout; `up`: operacional, requisições são enviadas normalmente; Estados adicionais no Angie PRO: `checking`: configurado como `essential` e sendo verificado, apenas requisições de sonda são enviadas; `unhealthy`: não operacional, apenas requisições de sonda são enviadas.
`selected`	Objeto; estatísticas de seleção de peer
`current`	Número; o número atual de conexões para o peer
`total`	Número; número total de requisições encaminhadas para o peer
`last`	String ou número; momento em que o peer foi selecionado pela última vez, formatado como uma data
`max_conns`	Número; o número máximo configurado de conexões ativas simultâneas para o peer, se especificado
`responses`	Objeto; estatísticas de respostas
`<code>`	Número; um número não-zero de respostas com status <code> (100-599)
`xxx`	Número; um número não-zero de respostas com outros códigos de status
`data`	Objeto; estatísticas de dados
`received`	Número; o número total de bytes recebidos do peer
`sent`	Número; o número total de bytes enviados para o peer
`health`	Objeto; estatísticas de saúde
`fails`	Número; o número total de tentativas malsucedidas de comunicação com o peer
`unavailable`	Número; quantas vezes o peer ficou `unavailable` devido ao atingimento do limite max_fails
`downtime`	Número; o tempo total (em milissegundos) quando o peer estava `unavailable` para seleção
`downstart`	String ou número; momento em que o peer ficou `unavailable`, formatado como uma data. O campo só está presente enquanto o peer está no estado `unavailable`; caso contrário, está ausente
`header_time`	Número; tempo médio (em milissegundos) para receber os cabeçalhos de resposta do servidor; veja response_time_factor
`response_time`	Número; tempo médio (em milissegundos) para receber a resposta completa do servidor; veja response_time_factor
`sid`	String; id configurado do servidor no grupo upstream
`feedback` (PRO)	Número; o valor médio de feedback atual usado pelo método de balanceamento de carga feedback, presente apenas quando esse método é usado
`keepalive`	Número; o número atual de conexões em cache
`backup_switch`	Objeto; contém o estado atual da lógica de backup ativo, presente se backup_switch (PRO) estiver configurado para o upstream
`active`	Número; o nível do grupo ativo que está sendo usado atualmente para balanceamento de carga de requisições. Se o grupo ativo for o primário, o valor é 0
`timeout`	Número; tempo de espera restante em milissegundos, após o qual o balanceador irá verificar novamente por nós saudáveis em grupos com níveis mais baixos, começando pelo grupo primário, enquanto grupos com níveis mais altos não são verificados; não exibido para o grupo primário (nível 0)

`health/probes` (PRO)#

Se o upstream tiver sondas upstream_probe (PRO) configuradas, o objeto health também possui um subobjeto probes que armazena os contadores de sonda de saúde do servidor, enquanto state, além dos valores listados na tabela acima, também pode ser checking e unhealthy:

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

O valor checking de state não é contado como downtime e significa que o servidor, que possui uma sonda configurada como essential, ainda não foi verificado; o valor unhealthy significa que o servidor está com mau funcionamento. Ambos os estados também implicam que o servidor não está incluído no balanceamento de carga. Para detalhes das sondas de saúde, veja upstream_probe.

Contadores em probes:

`count`	Número; total de sondas para este servidor
`fails`	Número; total de sondas falhadas
`last`	String ou número; momento da última sonda, formatado como uma data

`queue` (PRO)#

Se uma fila de requisições estiver configurada para o upstream, o objeto upstream também contém um objeto queue aninhado com contadores da fila de requisições:

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

Os valores dos contadores são somados em todos os processos worker:

`queued`	Número; número total de requisições que entraram na fila
`waiting`	Número; número atual de requisições na fila
`dropped`	Número; número total de requisições removidas da fila porque o cliente fechou prematuramente a conexão
`timedout`	Número; número total de requisições removidas da fila devido a timeout
`overflows`	Número; número total de ocorrências de overflow da fila

Upstream de stream#

Para habilitar a coleta das seguintes métricas, defina a diretiva zone no contexto upstream, por exemplo:

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

O uso de memória desta zona de memória compartilhada é informado na seção da API /status/slabs/, indexado pelo nome da zona.

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

Aqui, <upstream> é o nome de um upstream que está configurado com uma diretiva 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; contém as métricas dos peers do upstream como subobjetos cujos nomes são representações canônicas dos endereços dos peers. Membros de cada subobjeto:
`server`	String; endereço definido pela diretiva server
`service`	String; nome do serviço, se definido pela diretiva server
`backup`	Booleano; `true` para servidores de backup
`weight`	Número; o peso definido para o peer
`state`	String; o estado atual do peer e quais requisições são enviadas para ele: `busy`: indica que o número de requisições para o servidor atingiu o limite definido por max_conns, e nenhuma nova requisição é enviada para ele `down`: desabilitado manualmente, nenhuma requisição é enviada `draining`: similar a `down`, mas requisições de sessões previamente vinculadas (via sticky) ainda são enviadas `recovering`: recuperando após uma falha de acordo com slow_start, mais e mais requisições são enviadas ao longo do tempo `unavailable`: atingiu o limite max_fails, apenas requisições de teste do cliente são enviadas em intervalos definidos por fail_timeout `up`: operacional, requisições são enviadas normalmente Estados adicionais no Angie PRO: `checking`: configurado como `essential` e sendo verificado, apenas requisições de sonda são enviadas `unhealthy`: não operacional, apenas requisições de sonda são enviadas
`selected`	Objeto; estatísticas sobre a seleção deste peer para conexões
`current`	Número; número atual de conexões para o peer
`total`	Número; número total de conexões encaminhadas para o peer
`last`	String ou número; momento em que o peer foi selecionado pela última vez, formatado como uma data
`max_conns`	Número; número máximo de conexões ativas simultâneas para o peer, se definido
`data`	Objeto; estatísticas de transferência de dados
`received`	Número; total de bytes recebidos do peer
`sent`	Número; total de bytes enviados para o peer
`health`	Objeto; estatísticas de saúde do peer
`fails`	Número; total de tentativas falhadas para alcançar o peer
`unavailable`	Número; número total de vezes que o peer ficou `unavailable` devido a atingir o valor max_fails
`downtime`	Número; tempo total (em milissegundos) que o peer esteve `unavailable` (indisponível para seleção)
`downstart`	String ou número; momento em que o peer ficou `unavailable` pela última vez, formatado como uma data. O campo só está presente enquanto o peer está no estado `unavailable`; caso contrário, está ausente
`connect_time` (PRO 1.4.0+)	Número; tempo médio (em milissegundos) para estabelecer uma conexão com o servidor; veja a diretiva response_time_factor
`first_byte_time` (PRO 1.4.0+)	Número; tempo médio (em milissegundos) para receber o primeiro byte da resposta do servidor; veja a diretiva response_time_factor
`last_byte_time` (PRO 1.4.0+)	Número; tempo médio (em milissegundos) para receber a resposta completa do servidor; veja a diretiva response_time_factor
`feedback` (PRO)	Número; o valor médio de feedback atual usado pelo método de balanceamento de carga feedback, presente apenas quando esse método é usado
`backup_switch` (PRO 1.10.0+)	Objeto; contém o estado atual da lógica de backup ativo, presente se backup_switch (PRO) estiver configurado para o upstream
`active`	Número; nível do grupo ativo atualmente usado para balanceamento de carga. Se o grupo ativo for o grupo primário, o valor é 0
`timeout`	Número; tempo de espera restante em milissegundos após o qual o balanceador de carga irá verificar novamente por nós saudáveis em grupos com níveis mais baixos, começando pelo grupo primário, enquanto grupos com níveis mais altos não são verificados; não exibido para o grupo primário (nível 0)

No Angie PRO, se o upstream tiver sondas upstream_probe (PRO) configuradas, o objeto health também tem um subobjeto probes que armazena os contadores de sonda de saúde do servidor, enquanto state, além dos valores da tabela acima, também pode ser checking e unhealthy:

{
    "192.168.16.4:80": {
        "state": "unhealthy",
        "...": "...",
        "health": {
            "...": "...",
            "probes": {
                "count": 2,
                "fails": 2,
                "last": "2026-07-17T11:03:54Z"
            }
        }
    }
}

O valor checking de state significa que o servidor, que tem uma sonda configurada com o parâmetro essential, ainda não foi verificado; o valor unhealthy significa que o servidor não está operacional. Ambos os estados também significam que o servidor não está incluído no balanceamento de carga. Para detalhes das sondas de saúde, veja upstream_probe.

Contadores em probes:

`count`	Número; número total de sondas para este servidor
`fails`	Número; número de sondas falhadas
`last`	String ou número; momento da última sonda, formatado como uma data

Certificados#

`/certificates/`#

Um objeto de nível superior da API, separado da árvore de estatísticas /status/, que informa os certificados TLS que o Angie carregou.

Um certificado não é listado sob static se o nome de seu arquivo de certificado ou de chave contiver uma variável, incluindo uma fornecida por um cliente ACME através da variável $acme_cert_<name>. Um certificado compartilhado por vários servidores é listado uma única vez.

O exemplo a seguir carrega um certificado estático e obtém outro certificado com um cliente ACME. O cliente ACME requer um resolver configurado para resolver o nome de host do diretório:

http {
    resolver 127.0.0.53;

    acme_client example https://acme.example.com/directory;

    server {
        listen      443 ssl;
        server_name www.example.com;

        ssl_certificate     example.com.crt;
        ssl_certificate_key example.com.key;

        location /certificates/ {
            api /certificates/;
        }
    }

    server {
        listen      443 ssl;
        server_name acme.example.com;

        acme                example;
        ssl_certificate     $acme_cert_example;
        ssl_certificate_key $acme_cert_key_example;
    }
}

Em resposta à requisição curl https://www.example.com/certificates/, o Angie retorna:

{
    "static": {
        "example.com.crt": {
            "key": "RSA (2048 bits)",
            "chain": [
                {
                    "subject": {
                        "common_name": "example.com",
                        "alt_names": [
                            "example.com",
                            "www.example.com"
                        ],
                        "organization": "Example, Inc."
                    },

                    "issuer": {
                        "common_name": "Example Root CA",
                        "country": "US",
                        "organization": "Example, Inc."
                    },

                    "validity": {
                        "since": "Sep 18 19:46:19 2022 GMT",
                        "until": "Jun 15 19:46:19 2025 GMT"
                    }
                }
            ]
        }
    },

    "acme_clients": {
        "example": {
            "key": "EC (prime256v1)",
            "chain": [
                {
                    "subject": {
                        "common_name": "acme.example.com"
                    },

                    "issuer": {
                        "common_name": "Example ACME CA"
                    },

                    "validity": {
                        "since": "Sep 18 19:46:19 2022 GMT",
                        "until": "Dec 17 19:46:19 2022 GMT"
                    }
                }
            ]
        }
    }
}

`static`	Objeto; certificados de servidor definidos com ssl_certificate em HTTP, ssl_certificate em Stream, ou ssl_certificate em Mail, cada um indexado pelo nome do arquivo de certificado. Em compilações com `--with-ntls`, também inclui certificados definidos com proxy_ssl_certificate em HTTP ou proxy_ssl_certificate em Stream para autenticação em servidores proxy
`acme_clients`	Objeto; disponível quando o Angie é compilado com o módulo HTTP ACME, que também é exigido pelo módulo Stream ACME. Contém certificados obtidos por clientes ACME para servidores HTTP e Stream. Cada entrada é indexada pelo nome de acme_client. Apenas os clientes que já obtiveram um certificado são listados

Cada entrada de static e acme_clients descreve um único pacote de certificados:

`key`	String; tipo e tamanho da chave privada (ou curva), por exemplo `RSA (2048 bits)`, `EC (prime256v1)`, ou `DH (2048 bits)`
`chain`	Array; os certificados do pacote, começando pelo certificado folha (servidor) seguido pelos certificados intermediários, em direção à raiz. Cada elemento é um objeto que descreve um certificado:
`subject`	Objeto; o nome distinto (DN) do titular
`common_name`	String; Common Name (`CN`)
`alt_names`	Array de strings; os nomes DNS e endereços IP da extensão Subject Alternative Name
`country`	String; Country (`C`)
`state_or_province`	String; State or Province Name (`ST`)
`organization`	String; Organization (`O`)
`issuer`	Objeto; o nome distinto (DN) do emissor, com os mesmos campos que `subject`
`validity`	Objeto; o período de validade do certificado
`since`	String; início do período de validade (`notBefore`)
`until`	String; fim do período de validade (`notAfter`)

Os campos de subject e issuer aparecem apenas quando presentes no certificado.

API de Configuração Dinâmica (PRO)#

A API inclui uma seção /config que permite atualizações dinâmicas na configuração do Angie em formato JSON com requisições HTTP PUT, PATCH e DELETE. Todas as atualizações são atômicas: as novas configurações são aplicadas como um todo, ou nenhuma é aplicada. Em caso de erro, o Angie reporta o motivo.

Subseções de `/config`#

Atualmente, a configuração de servidores individuais dentro de upstreams está disponível na seção /config para os módulos HTTP e stream; o número de configurações elegíveis para configuração dinâmica está aumentando constantemente.

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

Permite configurar peers individuais de upstream, incluindo excluir peers existentes ou adicionar novos.

Parâmetros do caminho URI:

<upstream>

Nome do upstream; para ser configurável via /config, deve ter uma diretiva zone configurada, definindo uma zona de memória compartilhada.

<name>

O nome do peer dentro do upstream, definido como <service>@<host>, onde:

<service>@ é um nome de serviço opcional, usado para resolução de registros SRV.
<host> é o nome de domínio do serviço (se resolve estiver presente) ou seu IP; uma porta opcional pode ser definida aqui.

Por exemplo, a seguinte configuração:

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

Permite os seguintes nomes 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 subseção da API permite definir os parâmetros weight, max_conns, max_fails, fail_timeout, slow_start, backup, down e sid, conforme descrito em server.

Nota

Não há um parâmetro drain separado aqui; para habilitar drain, defina down para o valor string drain:

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

Exemplo:

$ 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,
    "slow_start": 0,
    "backup": true,
    "down": false,
    "sid": ""
}

Os parâmetros realmente disponíveis são limitados aos suportados pelo método de balanceamento de carga atual do upstream. Então, se o upstream estiver configurado com o método random:

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

Você não conseguirá adicionar um novo 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."
}

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

Permite configurar peers individuais de upstream, incluindo excluir peers existentes ou adicionar novos.

Parâmetros do caminho URI:

<upstream>

Nome do bloco upstream; para ser configurável via /config, deve ter uma diretiva zone configurada, definindo uma zona de memória compartilhada.

<name>

O nome do peer dentro do upstream, definido como <service>@<host>, onde:

<service>@ é um nome de serviço opcional, usado para resolução de registros SRV.
<host> é o nome de domínio do serviço (se resolve estiver presente) ou seu IP; uma porta opcional pode ser definida aqui.

Por exemplo, a seguinte configuração:

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

Permite os seguintes nomes 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 subseção da API permite definir os parâmetros weight, max_conns, max_fails, fail_timeout, slow_start, backup e down, conforme descrito em server.

Nota

Não há um parâmetro drain separado aqui; para habilitar o modo drain, defina down para o valor string drain:

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

Exemplo:

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,
    "slow_start": 0,
    "backup": true,
    "down": false,
}

Os parâmetros realmente disponíveis são limitados aos suportados pelo método de balanceamento de carga atual do upstream. Então, se o upstream estiver configurado com o método random:

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

Você não conseguirá adicionar um novo 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."
}

Ao excluir peers, você pode definir o argumento connection_drop=<value> (PRO) para sobrescrever as configurações 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#

Vamos considerar a semântica de cada método HTTP aplicável a esta seção usando a seguinte configuração upstream como exemplo:

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#

O método HTTP GET consulta uma entidade em qualquer caminho existente dentro de /config, assim como faz para outras seções da API.

Por exemplo, o ramo de servidor upstream /config/http/upstreams/backend/servers/ habilita 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

Você pode obter valores de parâmetros padrão com o argumento defaults=on; consulte Argumentos da query string.

PUT#

O método HTTP PUT cria uma nova entidade JSON no caminho especificado ou substitui inteiramente uma existente.

Por exemplo, para adicionar o parâmetro max_fails, não especificado anteriormente, ao servidor backend.example.com dentro do 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."
}

Verifique as alterações:

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

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

DELETE#

O método HTTP DELETE exclui configurações previamente definidas no caminho especificado; ao fazer isso, restaura os valores padrão se houver algum.

Por exemplo, para excluir o parâmetro max_fails previamente modificado do servidor backend.example.com dentro do 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."
}

Verifique as alterações usando o 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,
    "slow_start": 0,
    "backup": false,
    "down": false,
    "sid": ""
}

O parâmetro max_fails retornou ao seu valor padrão.

Ao excluir servidores, você pode definir o argumento connection_drop=<value> (PRO) para sobrescrever as configurações proxy_connection_drop, grpc_connection_drop, fastcgi_connection_drop, scgi_connection_drop e 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#

O método HTTP PATCH cria uma nova entidade no caminho especificado ou substitui parcialmente ou complementa uma existente (RFC 7386) fornecendo uma definição JSON em seu payload.

O método opera da seguinte forma: se as entidades da nova definição existem na configuração, elas são sobrescritas; caso contrário, são adicionadas.

Por exemplo, para alterar o parâmetro down do servidor backend.example.com dentro do upstream backend, deixando o 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."
}

Verifique as alterações:

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

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

Observe que o objeto JSON fornecido com a requisição PATCH foi mesclado com o existente em vez de substituí-lo inteiramente, como seria o caso com PUT.

Os valores null são um caso especial; eles são usados para excluir itens específicos de configuração durante tal mesclagem.

Nota

Esta exclusão é idêntica ao DELETE; em particular, ela restaura os valores padrão.

Por exemplo, para excluir o parâmetro down adicionado anteriormente e simultaneamente atualizar 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."
}

Verifique as alterações:

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

{
    "max_conns": 6
}

O parâmetro down, para o qual um valor null foi fornecido, foi excluído; o valor de max_conns foi atualizado.

API#

Diretivas#

api#

api_config_files#

Métricas#

Exemplo de configuração#

Argumentos da query string#

Status do servidor#

/status/angie#

/status/angie/license (PRO)#

Conexões#

/status/connections#

Zonas de memória compartilhada com alocação slab#

/status/slabs/<zone>#

Consultas DNS ao resolver#

/status/resolvers/<zone>#

Servidor HTTP e localização#

/status/http/server_zones/<zone>#

/status/http/location_zones/<zone>#

/status/http/metric_zones/<zone>#

Servidor stream#

/status/stream/server_zones/<zone>#

/status/stream/metric_zones/<zone>#

Caches HTTP#

/status/http/caches/<cache>#

Clientes ACME#

/status/http/acme_clients/<client>#

limit_conn#

/status/http/limit_conns/<zone>, /status/stream/limit_conns/<zone>#

limit_req#

/status/http/limit_reqs/<zone>#

HTTP upstream#

/status/http/upstreams/<upstream>#

health/probes (PRO)#

queue (PRO)#

Upstream de stream#

/status/stream/upstreams/<upstream>#

Certificados#

/certificates/#

API de Configuração Dinâmica (PRO)#

Subseções de /config#

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

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

Métodos HTTP#

GET#

PUT#

DELETE#

PATCH#

`/status/angie`#

`/status/angie/license` (PRO)#

`/status/connections`#

`/status/slabs/<zone>`#

`/status/resolvers/<zone>`#

`/status/http/server_zones/<zone>`#

`/status/http/location_zones/<zone>`#

`/status/http/metric_zones/<zone>`#

`/status/stream/server_zones/<zone>`#

`/status/stream/metric_zones/<zone>`#

`/status/http/caches/<cache>`#

`/status/http/acme_clients/<client>`#

`/status/http/limit_conns/<zone>`, `/status/stream/limit_conns/<zone>`#

`/status/http/limit_reqs/<zone>`#

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

`health/probes` (PRO)#

`queue` (PRO)#

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

`/certificates/`#

Subseções de `/config`#

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

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