Document "maxsize" (or equivalent) more prominently

[amontalenti]

I just had a scenario where I had to use Elasticsearch from a Tornado web service via its ThreadPoolExecutor integration. I was noticing terrible tail latencies on queries. After some digging, I discovered this was because of the maxsize parameter on the default connection class, documented here. The issue was that though my thread pool supported up to 500 threads, it was limited by the 10 concurrent connections that the driver had set on the underlying pool.

Thankfully, I could fix this by passing "maxsize" to the Elasticsearch object, since this then passes through to the connection object. But given how big an impact this parameter has on performance in multi-threaded scenarios, I think the documentation should call it out much more prominently. People are probably running very slow code in production without realizing it, even if they have big ES clusters, as a result of leaving this default.

[honzakral]

Thanks for raising this issue. I have made some changes to the docs, please let me know if you think that's enough or we need to do more. I also added a note on recommended usage (create one global client object and keep reusing).

[amontalenti]

This looks good. Thank you @honzakral!