The ngx_http_api_module module (1.13.3) provides REST API for accessing various status information, configuring upstream server groups on-the-fly, and managing key-value pairs without the need of reconfiguring nginx.
The module supersedes the ngx_http_status_module and ngx_http_upstream_conf_module modules.
When using the PATCH or POST methods, make sure that the payload does not exceed the buffer size for reading the client request body, otherwise, the 413 (Request Entity Too Large) error may be returned.
This module is available as part of our commercial subscription.
http {
upstream backend {
zone http_backend 64k;
server backend1.example.com weight=5;
server backend2.example.com;
}
proxy_cache_path /data/nginx/cache_backend keys_zone=cache_backend:10m;
server {
server_name backend.example.com;
location / {
proxy_pass http://backend;
proxy_cache cache_backend;
health_check;
}
status_zone server_backend;
}
keyval_zone zone=one:32k state=one.keyval;
keyval $arg_text $text zone=one;
server {
listen 127.0.0.1;
location /api {
api write=on;
allow 127.0.0.1;
deny all;
}
}
}
stream {
upstream backend {
zone stream_backend 64k;
server backend1.example.com:12345 weight=5;
server backend2.example.com:12345;
}
server {
listen 127.0.0.1:12345;
proxy_pass backend;
status_zone server_backend;
health_check;
}
}
All API requests include a supported API version in the URI. Examples of API requests with this configuration:
http://127.0.0.1/api/6/ http://127.0.0.1/api/6/nginx http://127.0.0.1/api/6/connections http://127.0.0.1/api/6/http/requests http://127.0.0.1/api/6/http/server_zones/server_backend http://127.0.0.1/api/6/http/caches/cache_backend http://127.0.0.1/api/6/http/upstreams/backend http://127.0.0.1/api/6/http/upstreams/backend/servers/ http://127.0.0.1/api/6/http/upstreams/backend/servers/1 http://127.0.0.1/api/6/http/keyvals/one?key=arg1 http://127.0.0.1/api/6/stream/ http://127.0.0.1/api/6/stream/server_zones/server_backend http://127.0.0.1/api/6/stream/upstreams/ http://127.0.0.1/api/6/stream/upstreams/backend http://127.0.0.1/api/6/stream/upstreams/backend/servers/1
| Syntax: | api
[write=on|off]; |
|---|---|
| Default: | — |
| Context: | location |
Turns on the REST API interface in the surrounding location. Access to this location should be limited.
The write parameter determines whether the API is read-only or read-write. By default, the API is read-only.
All API requests should contain a supported API version in the URI. If the request URI equals the location prefix, the list of supported API versions is returned. The current API version is “6”.
The optional “fields” argument in the request line specifies which fields of the requested objects will be output:
http://127.0.0.1/api/6/nginx?fields=version,build
| Syntax: | status_zone zone; |
|---|---|
| Default: | — |
| Context: | server, location, if in location |
This directive appeared in version 1.13.12.
Enables collection of virtual http or stream server status information in the specified zone. Several servers may share the same zone.
Starting from 1.17.0, status information can be collected per location. The special value off disables statistics collection in nested location blocks. Note that the statistics is collected in the context of a location where processing ends. It may be different from the original location, if an internal redirect happens during request processing.
expire” parameter of a key-value pair can be set or changed since version 5. path and method fields of nginx error object were removed in version 4. These fields continue to exist in earlier api versions, but show an empty value. / Supported methods:
GET - Return list of root endpoints Returns a list of root endpoints.
Possible responses:
UnknownVersion), returns Error
/nginx Supported methods:
GET - Return status of nginx running instance Returns nginx version, build name, address, number of configuration reloads, IDs of master and worker processes.
Request parameters:
fields (string, optional)Possible responses:
/processes Supported methods:
GET - Return nginx processes status Returns the number of abnormally terminated and respawned child processes.
Possible responses:
DELETE - Reset nginx processes statistics Resets counters of abnormally terminated and respawned child processes.
Possible responses:
/connections Supported methods:
GET - Return client connections statistics Returns statistics of client connections.
Request parameters:
fields (string, optional)Possible responses:
UnknownVersion), returns Error
DELETE - Reset client connections statistics Resets statistics of accepted and dropped client connections.
Possible responses:
/slabs/ Supported methods:
GET - Return status of all slabs Returns status of slabs for each shared memory zone with slab allocator.
Request parameters:
fields (string, optional)fields” value is empty, then only zone names will be output.Possible responses:
UnknownVersion), returns Error
/slabs/{slabZoneName} slabZoneName (string, required)Supported methods:
GET - Return status of a slab Returns status of slabs for a particular shared memory zone with slab allocator.
Request parameters:
fields (string, optional)Possible responses:
SlabNotFound), unknown version (UnknownVersion), returns Error
DELETE - Reset slab statistics Resets the “reqs” and “fails” metrics for each memory slot.
Possible responses:
/http/ Supported methods:
GET - Return list of HTTP-related endpoints Returns a list of first level HTTP endpoints.
Possible responses:
UnknownVersion), returns Error
/http/requests Supported methods:
GET - Return HTTP requests statistics Returns status of client HTTP requests.
Request parameters:
fields (string, optional)Possible responses:
UnknownVersion), returns Error
DELETE - Reset HTTP requests statistics Resets the number of total client HTTP requests.
Possible responses:
/http/server_zones/ Supported methods:
GET - Return status of all HTTP server zones Returns status information for each HTTP server zone.
Request parameters:
fields (string, optional)fields” value is empty, then only server zone names will be output.Possible responses:
UnknownVersion), returns Error
/http/server_zones/{httpServerZoneName} httpServerZoneName (string, required)Supported methods:
GET - Return status of an HTTP server zone Returns status of a particular HTTP server zone.
Request parameters:
fields (string, optional)Possible responses:
ServerZoneNotFound), unknown version (UnknownVersion), returns Error
DELETE - Reset statistics for an HTTP server zone Resets statistics of accepted and discarded requests, responses, received and sent bytes in a particular HTTP server zone.
Possible responses:
/http/location_zones/ Supported methods:
GET - Return status of all HTTP location zones Returns status information for each HTTP location zone.
Request parameters:
fields (string, optional)fields” value is empty, then only zone names will be output.Possible responses:
UnknownVersion), returns Error
/http/location_zones/{httpLocationZoneName} httpLocationZoneName (string, required)Supported methods:
GET - Return status of an HTTP location zone Returns status of a particular HTTP location zone.
Request parameters:
fields (string, optional)Possible responses:
LocationZoneNotFound), unknown version (UnknownVersion), returns Error
DELETE - Reset statistics for a location zone. Resets statistics of accepted and discarded requests, responses, received and sent bytes in a particular location zone.
Possible responses:
/http/caches/ Supported methods:
GET - Return status of all caches Returns status of each cache configured by proxy_cache_path and other “*_cache_path” directives.
Request parameters:
fields (string, optional)fields” value is empty, then only names of cache zones will be output.Possible responses:
UnknownVersion), returns Error
/http/caches/{httpCacheZoneName} httpCacheZoneName (string, required)Supported methods:
GET - Return status of a cache Returns status of a particular cache.
Request parameters:
fields (string, optional)Possible responses:
CacheNotFound), unknown version (UnknownVersion), returns Error
DELETE - Reset cache statistics Resets statistics of cache hits/misses in a particular cache zone.
Possible responses:
/http/limit_conns/ Supported methods:
GET - Return status of all HTTP limit_conn zones Returns status information for each HTTP limit_conn zone.
Request parameters:
fields (string, optional)fields” value is empty, then only zone names will be output.Possible responses:
UnknownVersion), returns Error
/http/limit_conns/{httpLimitConnZoneName} httpLimitConnZoneName (string, required)Supported methods:
GET - Return status of an HTTP limit_conn zone Returns status of a particular HTTP limit_conn zone.
Request parameters:
fields (string, optional)Possible responses:
LimitConnNotFound), unknown version (UnknownVersion), returns Error
DELETE - Reset statistics for an HTTP limit_conn zone Resets the connection limiting statistics.
Possible responses:
/http/limit_reqs/ Supported methods:
GET - Return status of all HTTP limit_req zones Returns status information for each HTTP limit_req zone.
Request parameters:
fields (string, optional)fields” value is empty, then only zone names will be output.Possible responses:
UnknownVersion), returns Error
/http/limit_reqs/{httpLimitReqZoneName} httpLimitReqZoneName (string, required)Supported methods:
GET - Return status of an HTTP limit_req zone Returns status of a particular HTTP limit_req zone.
Request parameters:
fields (string, optional)Possible responses:
LimitReqNotFound), unknown version (UnknownVersion), returns Error
DELETE - Reset statistics for an HTTP limit_req zone Resets the requests limiting statistics.
Possible responses:
/http/upstreams/ Supported methods:
GET - Return status of all HTTP upstream server groups Returns status of each HTTP upstream server group and its servers.
Request parameters:
fields (string, optional)fields” value is empty, only names of upstreams will be output.Possible responses:
UnknownVersion), returns Error
/http/upstreams/{httpUpstreamName}/ httpUpstreamName (string, required)Supported methods:
GET - Return status of an HTTP upstream server group Returns status of a particular HTTP upstream server group and its servers.
Request parameters:
fields (string, optional)Possible responses:
UpstreamStatic), returns Error
UnknownVersion), upstream not found (UpstreamNotFound), returns Error
DELETE - Reset statistics of an HTTP upstream server group Resets the statistics for each upstream server in an upstream server group and queue statistics.
Possible responses:
/http/upstreams/{httpUpstreamName}/servers/ httpUpstreamName (string, required)Supported methods:
GET - Return configuration of all servers in an HTTP upstream server group Returns configuration of each server in a particular HTTP upstream server group.
Possible responses:
UpstreamStatic), returns Error
UnknownVersion), upstream not found (UpstreamNotFound), returns Error
POST - Add a server to an HTTP upstream server group Adds a new server to an HTTP upstream server group. Server parameters are specified in the JSON format.
Request parameters:
postHttpUpstreamServer (HTTP Upstream Server, required)ID”, “backup”, and “service” parameters cannot be changed.Possible responses:
UpstreamStatic), invalid “parameter” value (UpstreamConfFormatError), missing “server” argument (UpstreamConfFormatError), unknown parameter “name” (UpstreamConfFormatError), nested object or list (UpstreamConfFormatError), “error” while parsing (UpstreamBadAddress), service upstream “host” may not have port (UpstreamBadAddress), service upstream “host” requires domain name (UpstreamBadAddress), invalid “weight” (UpstreamBadWeight), invalid “max_conns” (UpstreamBadMaxConns), invalid “max_fails” (UpstreamBadMaxFails), invalid “fail_timeout” (UpstreamBadFailTimeout), invalid “slow_start” (UpstreamBadSlowStart), reading request body failed BodyReadError), route is too long (UpstreamBadRoute), “service” is empty (UpstreamBadService), no resolver defined to resolve (UpstreamConfNoResolver), upstream “name” has no backup (UpstreamNoBackup), upstream “name” memory exhausted (UpstreamOutOfMemory), returns Error
UnknownVersion), upstream not found (UpstreamNotFound), returns Error
MethodDisabled), returns Error
EntryExists), returns Error
JsonError), returns Error
/http/upstreams/{httpUpstreamName}/servers/{httpUpstreamServerId} httpUpstreamName (string, required)httpUpstreamServerId (string, required)Supported methods:
GET - Return configuration of a server in an HTTP upstream server group Returns configuration of a particular server in the HTTP upstream server group.
Possible responses:
UpstreamStatic), invalid server ID (UpstreamBadServerId), returns Error
id” does not exist (UpstreamServerNotFound), unknown version (UnknownVersion), upstream not found (UpstreamNotFound), returns Error
PATCH - Modify a server in an HTTP upstream server group Modifies settings of a particular server in an HTTP upstream server group. Server parameters are specified in the JSON format.
Request parameters:
patchHttpUpstreamServer (HTTP Upstream Server, required)ID”, “backup”, and “service” parameters cannot be changed.Possible responses:
UpstreamStatic), invalid “parameter” value (UpstreamConfFormatError), unknown parameter “name” (UpstreamConfFormatError), nested object or list (UpstreamConfFormatError), “error” while parsing (UpstreamBadAddress), invalid “server” argument (UpstreamBadAddress), invalid server ID (UpstreamBadServerId), invalid “weight” (UpstreamBadWeight), invalid “max_conns” (UpstreamBadMaxConns), invalid “max_fails” (UpstreamBadMaxFails), invalid “fail_timeout” (UpstreamBadFailTimeout), invalid “slow_start” (UpstreamBadSlowStart), reading request body failed BodyReadError), route is too long (UpstreamBadRoute), “service” is empty (UpstreamBadService), server “ID” address is immutable (UpstreamServerImmutable), server “ID” weight is immutable (UpstreamServerWeightImmutable), upstream “name” memory exhausted (UpstreamOutOfMemory), returns Error
id” does not exist (UpstreamServerNotFound), unknown version (UnknownVersion), upstream not found (UpstreamNotFound), returns Error
MethodDisabled), returns Error
JsonError), returns Error
DELETE - Remove a server from an HTTP upstream server group Removes a server from an HTTP upstream server group.
Possible responses:
UpstreamStatic), invalid server ID (UpstreamBadServerId), server “id” not removable (UpstreamServerImmutable), returns Error
id” does not exist (UpstreamServerNotFound), unknown version (UnknownVersion), upstream not found (UpstreamNotFound), returns Error
MethodDisabled), returns Error
/http/keyvals/ Supported methods:
GET - Return key-value pairs from all HTTP keyval zones Returns key-value pairs for each HTTP keyval shared memory zone.
Request parameters:
fields (string, optional)fields” value is empty, then only HTTP keyval zone names will be output.Possible responses:
UnknownVersion), returns Error
/http/keyvals/{httpKeyvalZoneName} httpKeyvalZoneName (string, required)Supported methods:
GET - Return key-value pairs from an HTTP keyval zone Returns key-value pairs stored in a particular HTTP keyval shared memory zone.
Request parameters:
key (string, optional)Possible responses:
KeyvalNotFound), keyval key not found (KeyvalKeyNotFound), unknown version (UnknownVersion), returns Error
POST - Add a key-value pair to the HTTP keyval zone Adds a new key-value pair to the HTTP keyval shared memory zone. Several key-value pairs can be entered if the HTTP keyval shared memory zone is empty.
Request parameters:
Key-value (HTTP Keyval Shared Memory Zone, required)expire parameter which overrides the timeout parameter of the keyval_zone directive.Possible responses:
KeyvalFormatError), invalid key format (KeyvalFormatError), key required (KeyvalFormatError), keyval timeout is not enabled (KeyvalFormatError), only one key can be added (KeyvalFormatError), reading request body failed BodyReadError), returns Error
KeyvalNotFound), unknown version (UnknownVersion), returns Error
MethodDisabled), returns Error
EntryExists), key already exists (KeyvalKeyExists), returns Error
JsonError), returns Error
PATCH - Modify a key-value or delete a key Changes the value of the selected key in the key-value pair, deletes a key by setting the key value to null, changes expiration time of a key-value pair. If synchronization of keyval zones in a cluster is enabled, deletes a key only on a target cluster node. Expiration time in milliseconds can be specified for a key-value pair with the expire parameter which overrides the timeout parameter of the keyval_zone directive.
Request parameters:
httpKeyvalZoneKeyValue (HTTP Keyval Shared Memory Zone, required)Possible responses:
KeyvalFormatError), key required (KeyvalFormatError), keyval timeout is not enabled (KeyvalFormatError), only one key can be updated (KeyvalFormatError), reading request body failed BodyReadError), returns Error
KeyvalNotFound), keyval key not found (KeyvalKeyNotFound), unknown version (UnknownVersion), returns Error
MethodDisabled), returns Error
JsonError), returns Error
DELETE - Empty the HTTP keyval zone Deletes all key-value pairs from the HTTP keyval shared memory zone. If synchronization of keyval zones in a cluster is enabled, empties the keyval zone only on a target cluster node.
Possible responses:
/stream/ Supported methods:
GET - Return list of stream-related endpoints Returns a list of first level stream endpoints.
Possible responses:
UnknownVersion), returns Error
/stream/server_zones/ Supported methods:
GET - Return status of all stream server zones Returns status information for each stream server zone.
Request parameters:
fields (string, optional)fields” value is empty, then only server zone names will be output.Possible responses:
UnknownVersion), returns Error
/stream/server_zones/{streamServerZoneName} streamServerZoneName (string, required)Supported methods:
GET - Return status of a stream server zone Returns status of a particular stream server zone.
Request parameters:
fields (string, optional)Possible responses:
ServerZoneNotFound), unknown version (UnknownVersion), returns Error
DELETE - Reset statistics for a stream server zone Resets statistics of accepted and discarded connections, sessions, received and sent bytes in a particular stream server zone.
Possible responses:
/stream/limit_conns/ Supported methods:
GET - Return status of all stream limit_conn zones Returns status information for each stream limit_conn zone.
Request parameters:
fields (string, optional)fields” value is empty, then only zone names will be output.Possible responses:
UnknownVersion), returns Error
/stream/limit_conns/{streamLimitConnZoneName} streamLimitConnZoneName (string, required)Supported methods:
GET - Return status of an stream limit_conn zone Returns status of a particular stream limit_conn zone.
Request parameters:
fields (string, optional)Possible responses:
LimitConnNotFound), unknown version (UnknownVersion), returns Error
DELETE - Reset statistics for a stream limit_conn zone Resets the connection limiting statistics.
Possible responses:
/stream/upstreams/ Supported methods:
GET - Return status of all stream upstream server groups Returns status of each stream upstream server group and its servers.
Request parameters:
fields (string, optional)fields” value is empty, only names of upstreams will be output.Possible responses:
UnknownVersion), returns Error
/stream/upstreams/{streamUpstreamName}/ streamUpstreamName (string, required)Supported methods:
GET - Return status of a stream upstream server group Returns status of a particular stream upstream server group and its servers.
Request parameters:
fields (string, optional)Possible responses:
UpstreamStatic), returns Error
UnknownVersion), upstream not found (UpstreamNotFound), returns Error
DELETE - Reset statistics of a stream upstream server group Resets the statistics for each upstream server in an upstream server group.
Possible responses:
/stream/upstreams/{streamUpstreamName}/servers/ streamUpstreamName (string, required)Supported methods:
GET - Return configuration of all servers in a stream upstream server group Returns configuration of each server in a particular stream upstream server group.
Possible responses:
UpstreamStatic), returns Error
UnknownVersion), upstream not found (UpstreamNotFound), returns Error
POST - Add a server to a stream upstream server group Adds a new server to a stream upstream server group. Server parameters are specified in the JSON format.
Request parameters:
postStreamUpstreamServer (Stream Upstream Server, required)ID”, “backup”, and “service” parameters cannot be changed.Possible responses:
UpstreamStatic), invalid “parameter” value (UpstreamConfFormatError), missing “server” argument (UpstreamConfFormatError), unknown parameter “name” (UpstreamConfFormatError), nested object or list (UpstreamConfFormatError), “error” while parsing (UpstreamBadAddress), no port in server “host” (UpstreamBadAddress), service upstream “host” may not have port (UpstreamBadAddress), service upstream “host” requires domain name (UpstreamBadAddress), invalid “weight” (UpstreamBadWeight), invalid “max_conns” (UpstreamBadMaxConns), invalid “max_fails” (UpstreamBadMaxFails), invalid “fail_timeout” (UpstreamBadFailTimeout), invalid “slow_start” (UpstreamBadSlowStart), “service” is empty (UpstreamBadService), no resolver defined to resolve (UpstreamConfNoResolver), upstream “name” has no backup (UpstreamNoBackup), upstream “name” memory exhausted (UpstreamOutOfMemory), reading request body failed BodyReadError), returns Error
UnknownVersion), upstream not found (UpstreamNotFound), returns Error
MethodDisabled), returns Error
EntryExists), returns Error
JsonError), returns Error
/stream/upstreams/{streamUpstreamName}/servers/{streamUpstreamServerId} streamUpstreamName (string, required)streamUpstreamServerId (string, required)Supported methods:
GET - Return configuration of a server in a stream upstream server group Returns configuration of a particular server in the stream upstream server group.
Possible responses:
UpstreamStatic), invalid server ID (UpstreamBadServerId), returns Error
UnknownVersion), upstream not found (UpstreamNotFound), server with ID “id” does not exist (UpstreamServerNotFound), returns Error
PATCH - Modify a server in a stream upstream server group Modifies settings of a particular server in a stream upstream server group. Server parameters are specified in the JSON format.
Request parameters:
patchStreamUpstreamServer (Stream Upstream Server, required)ID”, “backup”, and “service” parameters cannot be changed.Possible responses:
UpstreamStatic), invalid “parameter” value (UpstreamConfFormatError), unknown parameter “name” (UpstreamConfFormatError), nested object or list (UpstreamConfFormatError), “error” while parsing (UpstreamBadAddress), invalid “server” argument (UpstreamBadAddress), no port in server “host” (UpstreamBadAddress), invalid server ID (UpstreamBadServerId), invalid “weight” (UpstreamBadWeight), invalid “max_conns” (UpstreamBadMaxConns), invalid “max_fails” (UpstreamBadMaxFails), invalid “fail_timeout” (UpstreamBadFailTimeout), invalid “slow_start” (UpstreamBadSlowStart), reading request body failed BodyReadError), “service” is empty (UpstreamBadService), server “ID” address is immutable (UpstreamServerImmutable), server “ID” weight is immutable (UpstreamServerWeightImmutable), upstream “name” memory exhausted (UpstreamOutOfMemory), returns Error
id” does not exist (UpstreamServerNotFound), unknown version (UnknownVersion), upstream not found (UpstreamNotFound), returns Error
MethodDisabled), returns Error
JsonError), returns Error
DELETE - Remove a server from a stream upstream server group Removes a server from a stream server group.
Possible responses:
UpstreamStatic), invalid server ID (UpstreamBadServerId), server “id” not removable (UpstreamServerImmutable), returns Error
id” does not exist (UpstreamServerNotFound), unknown version (UnknownVersion), upstream not found (UpstreamNotFound), returns Error
MethodDisabled), returns Error
/stream/keyvals/ Supported methods:
GET - Return key-value pairs from all stream keyval zones Returns key-value pairs for each stream keyval shared memory zone.
Request parameters:
fields (string, optional)fields” value is empty, then only stream keyval zone names will be output.Possible responses:
UnknownVersion), returns Error
/stream/keyvals/{streamKeyvalZoneName} streamKeyvalZoneName (string, required)Supported methods:
GET - Return key-value pairs from a stream keyval zone Returns key-value pairs stored in a particular stream keyval shared memory zone.
Request parameters:
key (string, optional)Possible responses:
KeyvalNotFound), keyval key not found (KeyvalKeyNotFound), unknown version (UnknownVersion), returns Error
POST - Add a key-value pair to the stream keyval zone Adds a new key-value pair to the stream keyval shared memory zone. Several key-value pairs can be entered if the stream keyval shared memory zone is empty.
Request parameters:
Key-value (Stream Keyval Shared Memory Zone, required)expire parameter which overrides the timeout parameter of the keyval_zone directive.Possible responses:
KeyvalFormatError), invalid key format (KeyvalFormatError), key required (KeyvalFormatError), keyval timeout is not enabled (KeyvalFormatError), only one key can be added (KeyvalFormatError), reading request body failed BodyReadError), returns Error
KeyvalNotFound), unknown version (UnknownVersion), returns Error
MethodDisabled), returns Error
EntryExists), key already exists (KeyvalKeyExists), returns Error
JsonError), returns Error
PATCH - Modify a key-value or delete a key Changes the value of the selected key in the key-value pair, deletes a key by setting the key value to null, changes expiration time of a key-value pair. If synchronization of keyval zones in a cluster is enabled, deletes a key only on a target cluster node. Expiration time is specified in milliseconds with the expire parameter which overrides the timeout parameter of the keyval_zone directive.
Request parameters:
streamKeyvalZoneKeyValue (Stream Keyval Shared Memory Zone, required)Possible responses:
KeyvalFormatError), key required (KeyvalFormatError), keyval timeout is not enabled (KeyvalFormatError), only one key can be updated (KeyvalFormatError), reading request body failed BodyReadError), returns Error
KeyvalNotFound), keyval key not found (KeyvalKeyNotFound), unknown version (UnknownVersion), returns Error
MethodDisabled), returns Error
JsonError), returns Error
DELETE - Empty the stream keyval zone Deletes all key-value pairs from the stream keyval shared memory zone. If synchronization of keyval zones in a cluster is enabled, empties the keyval zone only on a target cluster node.
Possible responses:
/stream/zone_sync/ Supported methods:
GET - Return sync status of a node Returns synchronization status of a cluster node.
Possible responses:
UnknownVersion), returns Error
/resolvers/ Supported methods:
GET - Return status for all resolver zones Returns status information for each resolver zone.
Request parameters:
fields (string, optional)Possible responses:
UnknownVersion), returns Error
/resolvers/{resolverZoneName} resolverZoneName (string, required)Supported methods:
GET - Return statistics of a resolver zone Returns statistics stored in a particular resolver zone.
Request parameters:
fields (string, optional)Possible responses:
ResolverZoneNotFound), unknown version (UnknownVersion), returns Error
DELETE - Reset statistics for a resolver zone. Resets statistics in a particular resolver zone.
Possible responses:
/ssl Supported methods:
GET - Return SSL statistics Returns SSL statistics.
Request parameters:
fields (string, optional)Possible responses:
DELETE - Reset SSL statistics Resets counters of SSL handshakes and session reuses.
Possible responses:
nginx:
General information about nginx:version (string) build (string) address (string) generation (integer) load_timestamp (string) timestamp (string) pid (integer) ppid (integer) Example:
{
"nginx" : {
"version" : "1.17.3",
"build" : "nginx-plus-r19",
"address" : "206.251.255.64",
"generation" : 6,
"load_timestamp" : "2019-10-01T11:15:44.467Z",
"timestamp" : "2019-10-01T09:26:07.305Z",
"pid" : 32212,
"ppid" : 32210
}
} Processes:
respawned (integer) Example:
{
"respawned" : 0
} Connections:
The number of accepted, dropped, active, and idle connections.accepted (integer) dropped (integer) active (integer) idle (integer) Example:
{
"accepted" : 4968119,
"dropped" : 0,
"active" : 5,
"idle" : 117
} SSL:
handshakes (integer) handshakes_failed (integer) session_reuses (integer) Example:
{
"handshakes" : 79572,
"handshakes_failed" : 21025,
"session_reuses" : 15762
} Shared memory zone with slab allocator:
pages
used (integer) free (integer) slots
Status data for memory slots (8, 16, 32, 64, 128, etc.)
A collection of "Memory Slot" objects
Example:
{
"pages" : {
"used" : 1143,
"free" : 2928
},
"slots" : {
"8" : {
"used" : 0,
"free" : 0,
"reqs" : 0,
"fails" : 0
},
"16" : {
"used" : 0,
"free" : 0,
"reqs" : 0,
"fails" : 0
},
"32" : {
"used" : 0,
"free" : 0,
"reqs" : 0,
"fails" : 0
},
"64" : {
"used" : 1,
"free" : 63,
"reqs" : 1,
"fails" : 0
},
"128" : {
"used" : 0,
"free" : 0,
"reqs" : 0,
"fails" : 0
},
"256" : {
"used" : 18078,
"free" : 178,
"reqs" : 1635736,
"fails" : 0
}
}
} Memory Slot:
used (integer) free (integer) reqs (integer) fails (integer) HTTP Requests:
total (integer) current (integer) Example:
{
"total" : 10624511,
"current" : 4
} HTTP Server Zone:
processing (integer) requests (integer) responses
1xx”, “2xx”, “3xx”, “4xx”, and “5xx”.1xx (integer) 1xx” status codes. 2xx (integer) 2xx” status codes. 3xx (integer) 3xx” status codes. 4xx (integer) 4xx” status codes. 5xx (integer) 5xx” status codes. total (integer) discarded (integer) received (integer) sent (integer) Example:
{
"processing" : 1,
"requests" : 706690,
"responses" : {
"1xx" : 0,
"2xx" : 699482,
"3xx" : 4522,
"4xx" : 907,
"5xx" : 266,
"total" : 705177
},
"discarded" : 1513,
"received" : 172711587,
"sent" : 19415530115
} HTTP Location Zone:
requests (integer) responses
1xx”, “2xx”, “3xx”, “4xx”, and “5xx”.1xx (integer) 1xx” status codes. 2xx (integer) 2xx” status codes. 3xx (integer) 3xx” status codes. 4xx (integer) 4xx” status codes. 5xx (integer) 5xx” status codes. total (integer) discarded (integer) received (integer) sent (integer) Example:
{
"requests" : 706690,
"responses" : {
"1xx" : 0,
"2xx" : 699482,
"3xx" : 4522,
"4xx" : 907,
"5xx" : 266,
"total" : 705177
},
"discarded" : 1513,
"received" : 172711587,
"sent" : 19415530115
} HTTP Cache:
size (integer) max_size (integer) cold (boolean) hit
responses (integer) bytes (integer) stale
responses (integer) *_cache_use_stale” directives). bytes (integer) updating
responses (integer) *_cache_use_stale” directives). bytes (integer) revalidated
responses (integer) *_cache_revalidate” directives. bytes (integer) miss
responses (integer) bytes (integer) responses_written (integer) bytes_written (integer) expired
responses (integer) bytes (integer) responses_written (integer) bytes_written (integer) bypass
responses (integer) *_cache_bypass” directives. bytes (integer) responses_written (integer) bytes_written (integer) Example:
{
"size" : 530915328,
"max_size" : 536870912,
"cold" : false,
"hit" : {
"responses" : 254032,
"bytes" : 6685627875
},
"stale" : {
"responses" : 0,
"bytes" : 0
},
"updating" : {
"responses" : 0,
"bytes" : 0
},
"revalidated" : {
"responses" : 0,
"bytes" : 0
},
"miss" : {
"responses" : 1619201,
"bytes" : 53841943822
},
"expired" : {
"responses" : 45859,
"bytes" : 1656847080,
"responses_written" : 44992,
"bytes_written" : 1641825173
},
"bypass" : {
"responses" : 200187,
"bytes" : 5510647548,
"responses_written" : 200173,
"bytes_written" : 44992
}
} HTTP Connections Limiting:
passed (integer) rejected (integer) rejected_dry_run (integer) Example:
{
"passed" : 15,
"rejected" : 0,
"rejected_dry_run" : 2
} HTTP Requests Rate Limiting:
passed (integer) delayed (integer) rejected (integer) delayed_dry_run (integer) rejected_dry_run (integer) Example:
{
"passed" : 15,
"delayed" : 4,
"rejected" : 0,
"delayed_dry_run" : 1,
"rejected_dry_run" : 2
} HTTP Upstream:
peers
id (integer) server (string) service (string) name (string) backup (boolean) weight (integer) state (string) up”, “draining”, “down”, “unavail”, “checking”, and “unhealthy”. active (integer) max_conns (integer) requests (integer) responses
1xx (integer) 1xx” status codes. 2xx (integer) 2xx” status codes. 3xx (integer) 3xx” status codes. 4xx (integer) 4xx” status codes. 5xx (integer) 5xx” status codes. total (integer) sent (integer) received (integer) fails (integer) unavail (integer) unavail”) due to the number of unsuccessful attempts reaching the max_fails threshold. health_checks
checks (integer) fails (integer) unhealthy (integer) unhealthy”). last_passed (boolean) downtime (integer) unavail”, “checking”, and “unhealthy” states. downstart (string) unavail”, “checking”, or “unhealthy”, in the ISO 8601 format with millisecond resolution. selected (string) header_time (integer) response_time (integer) keepalive (integer) zombies (integer) zone (string) queue
size (integer) max_size (integer) overflows (integer) Example:
{
"upstream_backend" : {
"peers" : [
{
"id" : 0,
"server" : "10.0.0.1:8088",
"name" : "10.0.0.1:8088",
"backup" : false,
"weight" : 5,
"state" : "up",
"active" : 0,
"max_conns" : 20,
"requests" : 667231,
"header_time" : 20,
"response_time" : 36,
"responses" : {
"1xx" : 0,
"2xx" : 666310,
"3xx" : 0,
"4xx" : 915,
"5xx" : 6,
"total" : 667231
},
"sent" : 251946292,
"received" : 19222475454,
"fails" : 0,
"unavail" : 0,
"health_checks" : {
"checks" : 26214,
"fails" : 0,
"unhealthy" : 0,
"last_passed" : true
},
"downtime" : 0,
"downstart" : "2019-10-01T11:09:21.602Z",
"selected" : "2019-10-01T15:01:25.000Z"
},
{
"id" : 1,
"server" : "10.0.0.1:8089",
"name" : "10.0.0.1:8089",
"backup" : true,
"weight" : 1,
"state" : "unhealthy",
"active" : 0,
"max_conns" : 20,
"requests" : 0,
"responses" : {
"1xx" : 0,
"2xx" : 0,
"3xx" : 0,
"4xx" : 0,
"5xx" : 0,
"total" : 0
},
"sent" : 0,
"received" : 0,
"fails" : 0,
"unavail" : 0,
"health_checks" : {
"checks" : 26284,
"fails" : 26284,
"unhealthy" : 1,
"last_passed" : false
},
"downtime" : 262925617,
"downstart" : "2019-10-01T11:09:21.602Z",
"selected" : "2019-10-01T15:01:25.000Z"
}
],
"keepalive" : 0,
"zombies" : 0,
"zone" : "upstream_backend"
}
} HTTP Upstream Server:
Dynamically configurable parameters of an HTTP upstream server:id (integer) server (string) http” block. See also the resolve parameter of the HTTP upstream server. service (string) weight (integer) max_conns (integer) max_fails (integer) fail_timeout (string) slow_start (string) route (string) backup (boolean) true, adds a backup server. This parameter cannot be changed. down (boolean) drain (boolean) parent (string) host (string) Example:
{
"id" : 1,
"server" : "10.0.0.1:8089",
"weight" : 4,
"max_conns" : 0,
"max_fails" : 0,
"fail_timeout" : "10s",
"slow_start" : "10s",
"route" : "",
"backup" : true,
"down" : true
} HTTP Keyval Shared Memory Zone:
Contents of an HTTP keyval shared memory zone when using the GET method.Example:
{
"key1" : "value1",
"key2" : "value2",
"key3" : "value3"
} HTTP Keyval Shared Memory Zone:
Contents of an HTTP keyval shared memory zone when using the POST or PATCH methods.Example:
{
"key1" : "value1",
"key2" : "value2",
"key3" : {
"value" : "value3",
"expire" : 30000
}
} Stream Server Zone:
processing (integer) connections (integer) sessions
2xx”, “4xx”, or “5xx”.2xx (integer) 2xx”. 4xx (integer) 4xx”. 5xx (integer) 5xx”. total (integer) discarded (integer) received (integer) sent (integer) Example:
{
"dns" : {
"processing" : 1,
"connections" : 155569,
"sessions" : {
"2xx" : 155564,
"4xx" : 0,
"5xx" : 0,
"total" : 155569
},
"discarded" : 0,
"received" : 4200363,
"sent" : 20489184
}
} Stream Connections Limiting:
passed (integer) rejected (integer) rejected_dry_run (integer) Example:
{
"passed" : 15,
"rejected" : 0,
"rejected_dry_run" : 2
} Stream Upstream:
peers
id (integer) server (string) service (string) name (string) backup (boolean) weight (integer) state (string) up”, “down”, “unavail”, “checking”, or “unhealthy”. active (integer) max_conns (integer) connections (integer) connect_time (integer) first_byte_time (integer) response_time (integer) sent (integer) received (integer) fails (integer) unavail (integer) unavail”) due to the number of unsuccessful attempts reaching the max_fails threshold. health_checks
checks (integer) fails (integer) unhealthy (integer) unhealthy”). last_passed (boolean) downtime (integer) unavail”, “checking”, and “unhealthy” states. downstart (string) unavail”, “checking”, or “unhealthy”, in the ISO 8601 format with millisecond resolution. selected (string) zombies (integer) zone (string) Example:
{
"dns" : {
"peers" : [
{
"id" : 0,
"server" : "10.0.0.1:12347",
"name" : "10.0.0.1:12347",
"backup" : false,
"weight" : 5,
"state" : "up",
"active" : 0,
"max_conns" : 50,
"connections" : 667231,
"sent" : 251946292,
"received" : 19222475454,
"fails" : 0,
"unavail" : 0,
"health_checks" : {
"checks" : 26214,
"fails" : 0,
"unhealthy" : 0,
"last_passed" : true
},
"downtime" : 0,
"downstart" : "2019-10-01T11:09:21.602Z",
"selected" : "2019-10-01T15:01:25.000Z"
},
{
"id" : 1,
"server" : "10.0.0.1:12348",
"name" : "10.0.0.1:12348",
"backup" : true,
"weight" : 1,
"state" : "unhealthy",
"active" : 0,
"max_conns" : 50,
"connections" : 0,
"sent" : 0,
"received" : 0,
"fails" : 0,
"unavail" : 0,
"health_checks" : {
"checks" : 26284,
"fails" : 26284,
"unhealthy" : 1,
"last_passed" : false
},
"downtime" : 262925617,
"downstart" : "2019-10-01T11:09:21.602Z",
"selected" : "2019-10-01T15:01:25.000Z"
}
],
"zombies" : 0,
"zone" : "dns"
}
} Stream Upstream Server:
Dynamically configurable parameters of a stream upstream server:id (integer) server (string) stream” block. See also the resolve parameter of the stream upstream server. service (string) weight (integer) max_conns (integer) max_fails (integer) fail_timeout (string) slow_start (string) backup (boolean) true, adds a backup server. This parameter cannot be changed. down (boolean) parent (string) host (string) Example:
{
"id" : 0,
"server" : "10.0.0.1:12348",
"weight" : 1,
"max_conns" : 0,
"max_fails" : 1,
"fail_timeout" : "10s",
"slow_start" : 0,
"backup" : false,
"down" : false
} Stream Keyval Shared Memory Zone:
Contents of a stream keyval shared memory zone when using the GET method.Example:
{
"key1" : "value1",
"key2" : "value2",
"key3" : "value3"
} Stream Keyval Shared Memory Zone:
Contents of a stream keyval shared memory zone when using the POST or PATCH methods.Example:
{
"key1" : "value1",
"key2" : "value2",
"key3" : {
"value" : "value3",
"expire" : 30000
}
} Stream Zone Sync Node:
zones
Synchronization information per each shared memory zone.
A collection of "Sync Zone" objects
status
bytes_in (integer) msgs_in (integer) msgs_out (integer) bytes_out (integer) nodes_online (integer) Example:
{
"zones" : {
"zone1" : {
"records_pending" : 2061,
"records_total" : 260575
},
"zone2" : {
"records_pending" : 0,
"records_total" : 14749
}
},
"status" : {
"bytes_in" : 1364923761,
"msgs_in" : 337236,
"msgs_out" : 346717,
"bytes_out" : 1402765472,
"nodes_online" : 15
}
} Sync Zone:
Synchronization status of a shared memory zone.records_pending (integer) records_total (integer) Resolver Zone:
Statistics of DNS requests and responses per particular resolver zone.requests
name (integer) srv (integer) addr (integer) responses
noerror (integer) formerr (integer) Format error) responses. servfail (integer) Server failure) responses. nxdomain (integer) Host not found) responses. notimp (integer) Unimplemented) responses. refused (integer) Operation refused) responses. timedout (integer) unknown (integer) Example:
{
"resolver_zone1" : {
"requests" : {
"name" : 25460,
"srv" : 130,
"addr" : 2580
},
"responses" : {
"noerror" : 26499,
"formerr" : 0,
"servfail" : 3,
"nxdomain" : 0,
"notimp" : 0,
"refused" : 0,
"timedout" : 243,
"unknown" : 478
}
}
} Error:
nginx error object.error
status (integer) text (string) code (string) request_id (string) href (string)
© 2002-2020 Igor Sysoev
© 2011-2020 Nginx, Inc.
Licensed under the BSD License.
https://nginx.org/en/docs/http/ngx_http_api_module.html