Merge pull request #1014 from skivis/geventhttpclientmergeconflicts

FastHttpLocust

docs/increase-performance.rst

@@ -0,0 +1,62 @@
+.. _increase-performance:
+
+==============================================================
+Increase Locust's performance with a faster HTTP client
+==============================================================
+
+Locust's default HTTP client uses `python-requests <http://www.python-requests.org/>`_. 
+The reason for this is that requests is a very well-maintained python package, that 
+provides a really nice API, that many python developers are familiar with. Therefore, 
+in many cases, we recommend that you use the default :py:class:`HttpLocust <locust.core.HttpLocust>` 
+which uses requests. However, if you're planning to run really large scale tests, 
+Locust comes with an alternative HTTP client, 
+:py:class:`FastHttpLocust <locust.contrib.fasthttp.FastHttpLocust>` which 
+uses `geventhttpclient <https://github.com/gwik/geventhttpclient/>`_ instead of requests.
+This client is significantly faster, and we've seen 5x-6x performance increases for making 
+HTTP-requests. This does not necessarily mean that the number of users one can simulate 
+per CPU core will automatically increase 5x-6x, since it also depends on what else 
+the load testing script does. However, if your locust scripts are spending most of their 
+CPU time in making HTTP-requests, you are likely to see signifant performance gains.
+
+
+How to use FastHttpLocust
+===========================
+
+First, you need to install the geventhttplocust python package::
+
+    pip install geventhttpclient
+
+Then you just subclass FastHttpLocust instead of HttpLocust::
+
+    from locust import TaskSet, task
+    from locust.contrib.fasthttp import FastHttpLocust
+    
+    class MyTaskSet(TaskSet):
+        @task
+        def index(self):
+            response = self.client.get("/")
+    
+    class MyLocust(FastHttpLocust):
+        task_set = MyTaskSet
+        min_wait = 1000
+        max_wait = 60000
+
+
+.. note::
+
+    FastHttpLocust uses a whole other HTTP client implementation, with a different API, compared to 
+    the default HttpLocust that uses python-requests. Therefore FastHttpLocust might not work as a d
+    rop-in replacement for HttpLocust, depending on how the HttpClient is used.
+
+
+API
+===
+
+FastHttpSession class
+=====================
+
+.. autoclass:: locust.contrib.fasthttp.FastHttpSession
+    :members: __init__, request, get, post, delete, put, head, options, patch
+
+.. autoclass:: locust.contrib.fasthttp.FastResponse
+    :members: content, text, headers

docs/index.rst

@@ -31,6 +31,7 @@ Locust Documentation
 
     running-locust-distributed
     running-locust-without-web-ui
+    increase-performance
 
 .. toctree ::
     :maxdepth: 4

docs/running-locust-distributed.rst

@@ -91,3 +91,10 @@ Running Locust distributed without the web UI
 =============================================
 
 See :ref:`running-locust-distributed-without-web-ui`
+
+
+Increase Locust's performance
+=============================
+
+If your planning to run large-scale load tests you might be interested to use the alternative 
+HTTP client that's shipped with Locust. You can read more about it here: :ref:`increase-performance`

docs/writing-a-locustfile.rst

@@ -73,7 +73,7 @@ classes. Say for example, web users are three times more likely than mobile user
 The *host* attribute
 --------------------
 
-The host attribute is a URL prefix (i.e. "https://google.com") to the host that is to be loaded. 
+The host attribute is a URL prefix (i.e. "https://google.com") to the host that is to be loaded.
 Usually, this is specified on the command line, using the :code:`--host` option, when locust is started. 
 If one declares a host attribute in the locust class, it will be used in the case when no :code:`--host` 
 is specified on the command line.
@@ -322,7 +322,7 @@ Since many setup and cleanup operations are dependent on each other, here is the
 In general, the setup and teardown methods should be complementary.
 
 
-Making HTTP requests 
+Making HTTP requests
 =====================
 
 So far, we've only covered the task scheduling part of a Locust user. In order to actually load test 
@@ -405,6 +405,8 @@ Response object. The request will be reported as a failure in Locust's statistic
 Response's *content* attribute will be set to None, and its *status_code* will be 0.
 
 
+.. _catch-response:
+
 Manually controlling if a request should be considered successful or a failure
 ------------------------------------------------------------------------------