API module

New in version 1.0.0.

Module provides HTTP RESTful interface for accessing in JSON format basic information about a web server instance, as well as metrics of client connections, shared memory zones, DNS queries, HTTP requests, HTTP responses cache, TCP/UDP sessions of stream_core module, and zones of http limit_conn, stream limit_conn, limit_req and http upstream modules.

API accepts GET и HEAD HTTP-requests, another request method leads to error:

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

Angie, configured as follows, with location /status/, resolver, http upstream, http server, location, cache, limit_conn in http и limit_req zones for example:

http {

        ...

        resolver 8.8.8.8 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 64k;
                server backend.example.com service=_http._tcp resolve max_conns=5;
           keepalive 4;
        }

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

                status_zone http_server_zone;
                proxy_cache cache_zone;

                access_log /var/log/access.log main;

                location / {
                        root /usr/share/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;
                }

        }
}

to the request curl https://www.example.com/status/ returns JSON tree

 {
   "status": {
     "angie": {
       "version": "1.0.0",
       "address": "192.168.1.1",
       "generation": 1,
       "load_time": "2022-10-19T12: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": 6,
             "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.24.1:80": {
               "server": "backend.example.com",
               "service": "_http._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
               }
             }
           },
           "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
         }
       }
     }
   }
 }

Each JSON branch can be requested separately with the request constructed accordingly, e.g.:

$ 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

Directives

api

Syntax:

api path;

Default:

—

Context:

location

Enables HTTP RESTful interface in location.

path parameter is mandatory and works similar to the alias directive, but operates over API tree, rather than filesystem hierarchy.

When specified in a prefix location:

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

the part of request URI matching particular prefix location /stats/ will be replaced by the path /status/http/server_zones/ in the directive parameter. For example, on a request of /stats/foo/ the /status/http/server_zones/foo/ API element will be accessed.

Also it’s possible to use variables: api /status/$module/server_zones/$name/ and the directive can also be specified inside a regexp location:

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

here, similar to alias, parameter defines the whole path to the API element. E.g., from /api/location/bar/data/ the following positional variables will be populated:

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

which results after interpolation in /status/http/location_zones/bar/data API request.

Overall, it serves for precise configuration of API access rights, e.g.:

location /status/ {
        api /status/;

        allow 127.0.0.1;
        deny  all;
}

or

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

        auth_basic           "blog";
        auth_basic_user_file conf/htpasswd;
}

Metrics

Server status

/status/angie

{
  "version": "1.1.0",
  "address": "192.168.0.1",
  "generation": 1,
  "load_time": "2022-10-24T16:15:43.805Z"
}

version	String; version of the running Angie web server
build	String; particular build name when it specified during compilation
address	String; the address of the server that accepted API request
generation	Number; the total number of configuration reloads
load_time	String; time of the last reload of configuration, in the ISO 8601 format with millisecond resolution

Connections global metrics

/status/connections

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

accepted	Number; the total number of accepted client connections
dropped	Number; the total number of dropped client connections
active	Number: the current number of active client connections
idle	Number; the current number of idle client connections

Slab allocator metrics of shared memory zones

Usage statistics of configured shared memory zones, such as: limit_conn, limit_req, HTTP cache

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;

/status/slabs/<zone>

where <zone> is the name of any configured status_zone shared memory zone that uses slab allocator

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

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

pages	Object; memory pages statistics
used	Number; the number of currently used memory pages
free	Number; the number of currently free memory pages
slots	Object; memory slots statistics for each slot size. The slots object contains fields for requested memory slot sizes (e.g. 8, 16, 32, etc., up to half of the page size)
used	Number; the number of currently used memory slots of specified size
free	Number; the number of currently free memory slots of specified size
reqs	Number; the total number of attempts to allocate memory slot of specified size
fails	Number; the number of unsuccessful attempts to allocate memory slot of specified size

Resolver

The statistics collection is enabled by specifying the zone name in the status_zone=<name> (status_zone) parameter of the resolver directive.

resolver 8.8.8.8 status_zone=resolver_zone;

/status/resolvers/<zone>

where <zone> is the name of any shared memory zone that collects resolver statistics

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

queries	Object; queries statistics
name	Number; the number of queries to resolve names to addresses (A and AAAA types queries)
srv	Number; the number of queries to resolve services to addresses (SRV type queries)
addr	Number; the number of queries to resolve addresses to names (PTR type queries)
responses	Object; responses statistics
success	Number; the number of successful responses
timedout	Number; the number of timed out queries
format_error	Number; the number responses with code 1 (Format error)
server_failure	Number; the number responses with code 2 (Server failure)
not_found	Number; the number responses with code 3 (Name Error)
unimplemented	Number; the number responses with code 4 (Not Implemented)
refused	Number; the number responses with code 5 (Refused)
other	Number; the number of queries completed with other non-zero code

The response codes are described in RFC 1035, section 4.1.1.

HTTP server and location

The status_zone <zone> (status_zone) directive specified in the server context enables the collection of statistics in the specified server zone. Object ssl is filled up with data when server is configured with listen ssl;

server {
        ...
        status_zone http_server_zone;

/status/http/server_zones/<zone>

where <zone> is the name of any shared memory zone that collects server statistics

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

ssl	Object; SSL statistics
handshaked	Number; the total number of successful SSL handshakes
reuses	Number; the total number of session reuses during SSL handshake
timedout	Number; the total number of timed out SSL handshakes
failed	Number; the total number of failed SSL handshakes
requests	Object; requests statistics
total	Number; the total number of client requests
processing	Number; the number of currently being processed client requests
discarded	Number; the total number of client requests completed without sending a response
responses	Object; responses statistics
<code>	Number; a non-zero number of responses with status <code> (100-599)
xxx	Number; a non-zero number of responses with other status codes
data	Object; data statistics
received	Number; the total number of bytes received from clients
sent	Number; the total number of bytes sent to clients

The status_zone <zone> (status_zone) directive, specified in location and if in location contexts enables the collection of statistics in the specified location zone. The special value off disables statistics collection in nested location blocks. location branch never includes ssl object and requests/processing metric

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

/status/http/location_zones/<zone>

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

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

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

Stream server

The status_zone <zone> (status_zone) directive specified in the server context enables the collection of statistics in the specified server zone. Object ssl is filled up with data when server is configured with listen ssl;

server {
        ...
        status_zone stream_server_zone;

/status/stream/server_zones/<zone>

where <zone> is the name of any shared memory zone that collects server statistics

{
  "ssl": {
    "handshaked": 24,
    "reuses": 0,
    "timedout": 0,
    "failed": 0
  },

  "connections": {
    "total": 24,
    "processing": 1,
    "discarded": 0
  },

  "sessions": {
    "success": 24,
    "invalid": 0,
    "forbidden": 0,
    "internal_error": 0,
    "bad_gateway": 0,
    "service_unavailable": 0
  },

  "data": {
    "received": 2762947,
    "sent": 53495723
  }
}

ssl	Object; SSL statistics
handshaked	Number; the total number of successful SSL handshakes
reuses	Number; the total number of session reuses during SSL handshake
timedout	Number; the total number of timed out SSL handshakes
failed	Number; the total number of failed SSL handshakes
connections	Object; connections statistics
total	Number; the total number of client connections
processing	Number; the number of currently being processed client connections
discarded	Number: the total number of client connections completed without creating a session
sessions	Object; sessions statistics
success	Number; the number of sessions completed with code 200, which means successful completion
invalid	Number; the number of sessions completed with code 400, which happens when client data could not be parsed, e.g. the PROXY protocol header
forbidden	Number; the number of sessions completed with code 403, when access was forbidden, for example, when access is limited for certain client addresses
internal_error	Number; the number of sessions completed with code 500, the internal server error
bad_gateway	Number; the number of sessions completed with code 502, bad gateway, for example, if an upstream server could not be selected or reached
service_unavailable	Number; the number of sessions completed with code 503, service unavailable, for example, when access is limited by the number of connections
data	Object; data statistics
received	Number; the total number of bytes received from clients
sent	Number; the total number of bytes sent to clients

HTTP caches

proxy_cache cache_zone;

/status/http/caches/<cache>

For each cache configured with proxy_cache

{
  "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	Number; the current size of the cache
max_size	Number; configured limit on the maximum size of the cache
cold	Boolean; true while cache loader loads data from disk
hit	Object; statistics of valid cached responses (proxy_cache_valid)
responses	Number; the total number of responses read from the cache
bytes	Number; the total number of bytes read from the cache
stale	Object; statistics of expired responses taken from the cache (proxy_cache_use_stale)
responses	Number; the total number of responses read from the cache
bytes	Number; the total number of bytes read from the cache
updating	Object; statistics of expired responses taken from the cache while responses were being updated (proxy_cache_use_stale updating)
responses	Number; the total number of responses read from the cache
bytes	Number; the total number of bytes read from the cache
revalidated	Object; statistics of expired and revalidated responses taken from the cache (proxy_cache_revalidate)
responses	Number; the total number of responses read from the cache
bytes	Number; the total number of bytes read from the cache
miss	Object; statistics of responses not found in the cache
responses	Number; the total number of corresponding responses
bytes	Number; the total number of bytes read from the proxied server
responses_written	Number; the total number of responses written to the cache
bytes_written	Number; the total number of bytes written to the cache
expired	Object; statistics of expired responses not taken from the cache
responses	Number; the total number of corresponding responses
bytes	Number; the total number of bytes read from the proxied server
responses_written	Number; the total number of responses written to the cache
bytes_written	Number; the total number of bytes written to the cache
bypass	Object; statistics of responses not looked up in the cache (proxy_cache_bypass)
responses	Number; the total number of corresponding responses
bytes	Number; the total number of bytes read from the proxied server
responses_written	Number; the total number of responses written to the cache
bytes_written	Number; the total number of bytes written to the cache

limit_conn

limit_conn_zone $binary_remote_addr zone=limit_conn_zone:10m;

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

Objects for each configured limit_conn in http or limit_conn in stream contexts with the following fields

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

passed	Number; the total number of passed connections
skipped	Number; the total number of connections passed with zero-length key, or key exceeding 255 bytes
rejected	Number; the total number of connections exceeding the configured limit
exhausted	Number; the total number of connections rejected due to exhaustion of zone storage

limit_req

limit_req_zone $binary_remote_addr zone=limit_req_zone:10m rate=1r/s;

/status/http/limit_reqs/<zone>

Objects for each configured limit_req with the following fields

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

passed	Number; the total number of passed connections
skipped	Number; the total number of requests passed with zero-length key, or key exceeding 65535 bytes
delayed	Number; the total number of delayed requests
rejected	Number; the total number of rejected requests
exhausted	Number; the total number of requests rejected due to exhaustion of zone storage

HTTP upstream

New in version 1.1.0.

The zone <zone> (zone) directive specified in the upstream context enables the collection of statistics in the specified upstream zone.

upstream backend {
        zone http_backend 64k;

        server backend1.example.com weight=5;
        server backend2.example.com;
}

/status/http/upstreams/<upstream>

where <upstream> is the name of any upstream specified with the zone directive

{
  "peers": {
    "192.168.24.1:80": {
      "server": "backend.example.com",
      "service": "_http._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
      }
    }
  },
  "keepalive": 2
}

peers	Object; upstream peers statistics
address	Object; peer’s statistics
server	String; the parameter of the server directive
service	String; name of service as it’s specified in server directie, if configured
backup	Boolean; true for backup servers
weight	Number; configured weight
state	String; the current state of the server, can either be up, down, or unavailable (when max_fails limit is reached)
selected	Object; peer selection statistics
current	Number; the current number of connections to peer
total	Number; total number of requests forwarded to peer
last	String; time in ISO 8601 format when peer was last selected
max_conns	Number; the configured maximum number of simultaneous connections, if specified
responses	Object; responses statistics
<code>	Number; a non-zero number of responses with status <code> (100-599)
xxx	Number; a non-zero number of responses with other status codes
data	Object; data statistics
received	Number; the total number of bytes received from peer
sent	Number; the total number of bytes sent to peer
health	Object; health statistics
fails	Number; the total number of unsuccessful attempts to communicate with the peer
unavailable	Number; how many times peer became unavailable due to reaching the max_fails limit
downtime	Number; the total time (in milliseconds) when peer was unavailable for selection due to being unavailable
downstart	String; time in ISO 8601 format when peer became unavailable
keepalive	Number; the number of currently cached connections