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.

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

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.10.2",
    "address":"192.168.16.5",
    "generation":1,
    "load_time":"2025-08-21T12:58:39.789Z",
    "config_files": {
        "/etc/angie/angie.conf": "...",
        "/etc/angie/mime.types": "..."
    }
}

Por 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 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.10.2",
        "address":"192.168.16.5",
        "generation":1,
        "load_time":"2025-08-21T12:58:39.789Z"
    },

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

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

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

                "512": {
                    "used":1,
                    "free":7,
                    "reqs":1,
                    "fails":0
                }
            }
        },

        "limit_conn_zone": {
            "pages": {
                "used":2,
                "free":2542
            },

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

                "128": {
                    "used":1,
                    "free":31,
                    "reqs":1,
                    "fails":0
                }
            }
        },

        "limit_req_zone": {
            "pages": {
                "used":2,
                "free":2542
            },

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

                "128": {
                    "used":2,
                    "free":30,
                    "reqs":3,
                    "fails":0
                }
            }
        }
    },

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

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

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

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

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

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

                "data": {
                    "received":538200,
                    "sent":177606236
                }
            }
        },
        "caches": {
            "cache_zone": {
                "size":0,
                "cold":false,
                "hit": {
                    "responses":0,
                    "bytes":0
                },

                "stale": {
                    "responses":0,
                    "bytes":0
                },

                "updating": {
                    "responses":0,
                    "bytes":0
                },

                "revalidated": {
                    "responses":0,
                    "bytes":0
                },

                "miss": {
                    "responses":0,
                    "bytes":0,
                    "responses_written":0,
                    "bytes_written":0
                },

                "expired": {
                    "responses":0,
                    "bytes":0,
                    "responses_written":0,
                    "bytes_written":0
                },

                "bypass": {
                    "responses":0,
                    "bytes":0,
                    "responses_written":0,
                    "bytes_written":0
                }
            }
        },

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

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

        "upstreams": {
            "upstream": {
                "peers": {
                    "192.168.16.4:80": {
                        "server":"backend.example.com",
                        "service":"_example._tcp",
                        "backup":false,
                        "weight":5,
                        "state":"up",
                        "selected": {
                            "current":2,
                            "total":232
                        },

                        "max_conns":5,
                        "responses": {
                            "200":222,
                            "302":12
                        },

                        "data": {
                            "sent":543866,
                            "received":27349934
                        },

                        "health": {
                            "fails":0,
                            "unavailable":0,
                            "downtime":0
                        },

                        "sid":"<server_id>"
                    }
                },

                "keepalive":2
            }
        }
    },

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

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

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/server_zones
$ curl https://www.example.com/status/http/server_zones/<http_server_zone>
$ curl https://www.example.com/status/http/server_zones/<http_server_zone>/ssl

Nota

Por 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 à string de consulta:

$ curl https://www.example.com/status/angie/load_time

  "2024-04-01T00:59:59+01:00"

$ curl https://www.example.com/status/angie/load_time?date=epoch

  1711929599

Status do servidor#

/status/angie#

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

version

String; versão do servidor web Angie em execução

build

String; nome específico da build quando 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.

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, como limit_conn, limit_req, e cache HTTP:

limit_conn_zone $binary_remote_addr zone=limit_conn_zone:10m;
limit_req_zone $binary_remote_addr zone=limit_req_zone:10m rate=1r/s;
proxy_cache cache_zone;
proxy_cache_valid 200 10m;

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 (Erro de Formato)

server_failure

Number; o número de respostas com código 2 (Falha do Servidor)

not_found

Number; o número de respostas com código 3 (Erro de Nome)

unimplemented

Number; o número de respostas com código 4 (Não Implementado)

refused

Number; o número de respostas com código 5 (Recusado)

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

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

Objeto; estatísticas SSL. Presente se server definir listen ssl;

handshaked

Número; o número total de handshakes SSL bem-sucedidos

reuses

Número; o número total de reutilizações de sessão durante o handshake SSL

timedout

Número; o número total de handshakes SSL que expiraram

failed

Número; o número total de handshakes SSL que falharam

requests

Objeto; estatísticas de requisições

total

Número; o número total de requisições de clientes

processing

Número; o número de requisições de clientes sendo processadas atualmente

discarded

Número; o número total de requisições de clientes concluídas sem enviar uma resposta

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 de clientes

sent

Número; o número total de bytes enviados para clientes

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

Objeto; estatísticas de requisições

total

Número; o número total de requisições de clientes

discarded

Número; o número total de requisições de clientes concluídas sem enviar uma resposta

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 de clientes

sent

Número; o número total de bytes enviados para clientes

Exemplo:

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

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

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

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

Objeto; estatísticas SSL. Presente se server definir listen ssl;

handshaked

Número; o número total de handshakes SSL bem-sucedidos

reuses

Número; o número total de reutilizações de sessão durante o handshake SSL

timedout

Número; o número total de handshakes SSL que expiraram

failed

Número; o número total de handshakes SSL que falharam

connections

Objeto; estatísticas de conexões

total

Número; o número total de conexões de clientes

processing

Número; o número de conexões de clientes sendo processadas atualmente

discarded

Número; o número total de conexões de clientes concluídas sem criar uma sessão

passed

Número; o número total de conexões de clientes redirecionadas para outra porta de escuta com diretivas pass

sessions

Objeto; estatísticas de sessões

success

Número; o número de sessões concluídas com código 200, que significa conclusão bem-sucedida

invalid

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

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

Número; o número de sessões concluídas com código 500, erro interno do servidor

bad_gateway

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

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

Objeto; estatísticas de dados

received

Número; o número total de bytes recebidos de clientes

sent

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

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 expiradas 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 expiradas 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 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 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 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

Adicionado na versão 1.2.0: PRO

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

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#

Adicionado na versão 1.1.0.

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

/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

slow_start
(PRO 1.4.0+)

Número; o valor slow_start especificado para o servidor, expresso em segundos.

Ao definir o valor através da subseção respectiva da API de configuração dinâmica, você pode especificar um número de segundos ou um valor de tempo com precisão de milissegundos.

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;

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

  • draining: similar a down, mas requisições de sessões previamente vinculadas (via sticky) ainda 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

header_time
(PRO 1.3.0+)

Número; tempo médio (em milissegundos) para receber os cabeçalhos de resposta do servidor; veja response_time_factor (PRO)

response_time
(PRO 1.3.0+)

Número; tempo médio (em milissegundos) para receber a resposta completa do servidor; veja response_time_factor (PRO)

sid

String; id configurado do servidor no grupo upstream

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

Alterado na versão 1.2.0: 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 o 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": "2025-08-21T09: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)#

Alterado na versão 1.4.0: 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

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

/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

slow_start
(PRO 1.4.0+)

Número; o valor slow_start especificado para o servidor, expresso em segundos.

Ao definir o valor através da subseção respectiva da API de configuração dinâmica, você pode especificar um número ou um valor de tempo com precisão de milissegundos.

backup

Booleano; true para servidor de backup

weight

Número; o peso do 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

  • down: desabilitado manualmente, nenhuma requisição é enviada

  • 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

  • draining: similar a down, mas requisições de sessões previamente vinculadas (via sticky) ainda são enviadas

  • unhealthy: não operacional, apenas requisições de sonda são enviadas

selected

Objeto; as métricas de seleção do peer

current

Número; conexões atuais para o peer

total

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; métricas 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; métricas de saúde do peer

fails

Número; total de tentativas falhadas para alcançar o peer

unavailable

Número; vezes que o peer ficou unavailable devido a atingir o max_fails

downtime

Número; tempo total (em milissegundos) que o peer esteve unavailable para seleção

downstart

String ou número; momento em que o peer ficou unavailable pela última vez, formatado como uma data

connect_time
(PRO 1.4.0+)

Número; tempo médio (em milissegundos) necessário para estabelecer uma conexão com o peer; veja a diretiva response_time_factor (PRO).

first_byte_time
(PRO 1.4.0+)

Número; tempo médio (em milissegundos) para receber o primeiro byte da resposta do peer; veja a diretiva response_time_factor (PRO).

last_byte_time
(PRO 1.4.0+)

Número; tempo médio (em milissegundos) para receber a resposta completa do peer; veja a diretiva response_time_factor (PRO).

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 requisições. 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)

Alterado na versão 1.4.0: PRO

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 peer, enquanto o state do peer também pode ser checking e unhealthy, além dos valores listados na tabela acima:

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

O valor checking de state significa que o peer, que tem uma sonda configurada como essential, ainda não foi verificado; o valor unhealthy significa que o peer está com mau funcionamento. Ambos os estados também implicam que o peer 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 peer

fails

Número; total de sondas falhadas

last

String ou número; momento da última sonda, formatado como uma data

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

Adicionado na versão 1.2.0: PRO

A API inclui uma seção /config que permite atualizações dinâmicas na configuração do Angie em 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, backup, down e sid, conforme descrito em server.

Nota

Não há um parâmetro drain (PRO) 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,
    "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."
}

Nota

Mesmo com um método de balanceamento de carga compatível, o parâmetro backup só pode ser definido ao adicionar um novo peer.

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

Permite configurar servidores individuais dentro de um upstream, incluindo adicionar novos e excluir os configurados.

Parâmetros no caminho URI:

<upstream>

Nome do bloco upstream; para configurá-lo via /config, deve conter a diretiva zone que define uma zona de memória compartilhada.

<name>

Nome de um servidor específico dentro do <upstream> especificado; especificado no formato <service>@<host>, onde:

  • <service>@ — parte opcional que especifica o nome do serviço para resolver registros SRV.

  • <host> — nome de domínio do serviço (quando resolve está presente) ou endereço IP; a porta também pode ser especificada.

Por exemplo, para a seguinte configuração:

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

Estes nomes de servidor são válidos:

$ curl http://127.0.0.1/config/stream/upstreams/backend/servers/_example._tcp@backend.example.com:8080/
$ curl http://127.0.0.1/config/stream/upstreams/backend/servers/127.0.0.1:12345/

Esta subseção da API permite definir os parâmetros weight, max_conns, max_fails, fail_timeout, backup e down descritos na seção server.

Nota

Não há um parâmetro drain separado (PRO); para habilitar o modo drain, defina o parâmetro 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,
    "backup": true,
    "down": false,
}

Apenas os parâmetros que são suportados pelo método de balanceamento de carga atual do upstream estarão realmente disponíveis. Por exemplo, se o upstream estiver configurado com o método de balanceamento random:

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

Então é impossível adicionar um novo servidor com o parâmetro backup:

$ curl -X PUT -d '{ "backup": true }' \
    http://127.0.0.1/config/stream/upstreams/backend/servers/backend1.example.com

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

Nota

Mesmo com um método de balanceamento compatível, o parâmetro backup só pode ser definido ao adicionar um novo servidor.

Ao excluir servidores, 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 todos os métodos HTTP aplicáveis a esta seção, dada esta configuração upstream:

http {
    # ...

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

    server {
        # ...

        location /config/ {
            api /config/;

            allow 127.0.0.1;
            deny all;
        }
    }
}

GET#

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 defaults=on:

$ curl http://127.0.0.1/config/http/upstreams/backend/servers?defaults=on

{
    "backend.example.com": {
        "weight": 1,
        "max_conns": 5,
        "max_fails": 1,
        "fail_timeout": 10,
        "backup": false,
        "down": false,
        "sid": ""
    }
}

PUT#

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

Por exemplo, para definir o parâmetro max_fails, não especificado anteriormente, do 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, retorna aos valores padrão se houver algum.

Por exemplo, para excluir o parâmetro max_fails definido anteriormente 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 defaults=on:

$ curl http://127.0.0.1/config/http/upstreams/backend/servers/backend.example.com?defaults=on

{
    "weight": 1,
    "max_conns": 5,
    "max_fails": 1,
    "fail_timeout": 10,
    "backup": false,
    "down": false,
    "sid": ""
}

A configuração max_fails voltou 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 a configuração 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
}

O objeto JSON fornecido com a requisição PATCH foi mesclado com o existente em vez de sobrescrevê-lo, 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 a configuração down adicionada 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 null foi fornecido, foi excluído; max_conns foi atualizado.