Nginx – Meaning of Defining Burst with Nodelay Option

nginxrate-limiting

In the Nginx configuration, when you want to limit the request processing rate by using the limit_req_zone / limit_req instructions, I don't really understand the use of the nodelay option.
In my understanding, it terminates the requests above the defined rate without delaying them. So it seems equivalent to burst=0.
That is why I don't understand the following example :

limit_req zone=one burst=5 nodelay;

burst defines the number of requests which could be delayed, so what is the meaning to define burst if there is the nodelay option?

Best Answer

I find limit_req documentation clear enough.

burst is documented that way:

Excessive requests are delayed until their number exceeds the maximum burst size [...]

nodelay is documented that way:

If delaying of excessive requests while requests are being limited is not desired, the parameter nodelay should be used

Requests are limited to fit the defined rate. If requests are incoming at a higher rate, no more than the defined number of requests per time unit will be served. You then need to decide on what to do with those other requests.

By default (no burst, no nodelay), requests are denied with an HTTP 503 error.
With burst, you stack the defined number of requests in a waiting queue, but you do not process them quicker than the defined requests per time unit rate.
With burst and nodelay, the queue won't be waiting and request bursts will get processed immediately.

Related Solutions

Nginx – Understanding the nodelay Option for Limiting Requests

The documentation here has an explanation that sounds like what you want to know:

The directive specifies the zone (zone) and the maximum possible bursts of requests (burst). If the rate exceeds the demands outlined in the zone, the request is delayed, so that queries are processed at a given speed

From what I understand, requests over the burst will be delayed (take more time and wait until they can be served), with the nodelay options the delay is not used and excess requests are denied with a 503 error.

This blog post (archive.org) gives good explanation how the rate limiting works on nginx:

If you’re like me, you’re probably wondering what the heck burst really means. Here is the trick: replace the word ‘burst’ with ‘bucket’, and assume that every user is given a bucket with 5 tokens. Every time that they exceed the rate of 1 request per second, they have to pay a token. Once they’ve spent all of their tokens, they are given an HTTP 503 error message, which has essentially become the standard for ‘back off, man!’.

Nginx 301’ing limit_req rate limited requests instead of error page

By default, nginx will return a 503 service temporarily unavailable error code.

The limit_req_status directive exists to change the error code in case they hit the limit_req :

location = /search/bulk {
          limit_req zone=one burst=2;
          limit_req_status 404;
}

The problem is that this directive only allows a range from 400 to 599, so you cannot specify a 301 :

[emerg] 3130#0: value must be between 400 and 599 in /etc/nginx/nginx.conf:72

So, if your main issue is to display a custom error message instead of the default 503 one, you could proceed like this :

http {
    limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s;
    server {
       location = /search/bulk {
                limit_req zone=one burst=2;
                error_page  503  /503.html;
       }
       location  /503.html {
            internal;
       }
    }
}

Then your custom 503.html file :

<html><body>Would you like to use our API ?</body></html>

The rate argument is mandatory. You have to specify a rate for limit_req_zone

Best Answer

Related Solutions

Nginx – Understanding the nodelay Option for Limiting Requests

Nginx 301’ing limit_req rate limited requests instead of error page

Related Topic