mirror of https://github.com/locustio/locust.git
Docs: Import wiki to docs (#2734)
* Straight pandoc migration, no edits * Minimum edits for the docs to build - added imports to TOC - deleted Home.rst - removed spurious html formatting `li`, `h4` etc - fixed H1s Still to do - rename files - actually look at content :-p * Blog post links live in ther forum now * Move imported files to lowercase, update wiki links to docs links * Move troubleshooting into installation * Break out increasing request rate * Remove duped content * Remove duped content * Codespell fixes * Misc review feedback and fixes * Just nuke it * Fix line breaks * This aint the wiki youre looking for
This commit is contained in:
Sam
GitHub
parent
4cf3f0aa49
commit
8f04a6bcd1
|
|
@ -191,9 +191,6 @@ With the following file structure:
|
|||
The Web UI will display:
|
||||
|
||||
.. image:: images/userclass_picker_example.png
|
||||
:width: 200
|
||||
|
||||
|
|
||||
|
||||
The class picker additionally allows for disabling individual User tasks, changing the weight or fixed count, and configuring the host.
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,68 @@
|
|||
.. _extensions:
|
||||
|
||||
======================
|
||||
Third party extensions
|
||||
======================
|
||||
|
||||
Support for load testing other protocols, reporting etc
|
||||
-------------------------------------------------------
|
||||
|
||||
- `locust-plugins <https://github.com/SvenskaSpel/locust-plugins/>`__
|
||||
|
||||
- request logging & graphing
|
||||
- new protocols like websockets, selenium/webdriver, http users that
|
||||
load html page resources
|
||||
- readers (ways to get test data into your tests)
|
||||
- wait time (custom wait time functions)
|
||||
- debug (support for running a single user in the debugger)
|
||||
- checks (adds command line parameters to set locust exit code based
|
||||
on requests/s, error percentage and average response times)
|
||||
|
||||
Automate distributed runs over SSH
|
||||
----------------------------------
|
||||
|
||||
- `locust-swarm <https://github.com/SvenskaSpel/locust-swarm/>`__
|
||||
|
||||
Automatically translate a browser recording (HAR-file) to a locustfile
|
||||
----------------------------------------------------------------------
|
||||
|
||||
- `har2locust <https://github.com/SvenskaSpel/har2locust>`__
|
||||
|
||||
Workers written in other languages than Python
|
||||
----------------------------------------------
|
||||
|
||||
A Locust master and a Locust worker communicate by exchanging
|
||||
`msgpack <http://msgpack.org/>`__ messages, which is supported by many
|
||||
languages. So, you can write your User tasks in any languages you like.
|
||||
For convenience, some libraries do the job as a worker runner. They run
|
||||
your User tasks, and report to master regularly.
|
||||
|
||||
- `Boomer <https://github.com/myzhan/boomer/>`__ - Go
|
||||
- `Locust4j <https://github.com/myzhan/locust4j>`__ - Java
|
||||
|
||||
Configuration Management
|
||||
------------------------
|
||||
|
||||
- `ansible-role-locust <https://github.com/tinx/ansible-role-locust>`__
|
||||
- an Ansible role to install, configure and control Locust as a
|
||||
systemd service, or to build Locust docker images using
|
||||
ansible-container. Also manages locustfiles and accompanying test
|
||||
data.
|
||||
- `locust_slave <https://github.com/tinx/locust_slave>`__ - an Ansible
|
||||
role to manage Locust slave instances.
|
||||
|
||||
.. _helm:
|
||||
|
||||
Helm
|
||||
----
|
||||
|
||||
DeliveryHero maintains an extensive list of helm charts, including `one
|
||||
for
|
||||
locust <https://github.com/deliveryhero/helm-charts/tree/master/stable/locust>`__.
|
||||
|
||||
Kubernetes Operator
|
||||
-------------------
|
||||
|
||||
AbdelrhmanHamouda has written a `Kubernetes
|
||||
Operator <https://github.com/AbdelrhmanHamouda/locust-k8s-operator>`__
|
||||
for Locust
|
||||
|
|
@ -0,0 +1,107 @@
|
|||
.. _faq:
|
||||
|
||||
===
|
||||
FAQ
|
||||
===
|
||||
|
||||
How do I…
|
||||
|
||||
..
|
||||
|
||||
Note: Hatch rate/ramp up does not change peak load, it only changes
|
||||
how fast you get there (people keep asking about this for some
|
||||
reason).
|
||||
|
||||
Resolve errors that occur during load (error 5xx, Connection aborted, Connection reset by peer, etc)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Check your server logs. If it works at low load then it is almost
|
||||
certainly not a Locust issue, but an issue with the system you are
|
||||
testing.
|
||||
|
||||
Clear cookies, to make the next task iteration seem like a new user to my system under test
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Call ``self.client.cookies.clear()`` at the end of your task.
|
||||
|
||||
Control headers or other things about my HTTP requests
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Locust’s client in ``HttpUser`` inherits from
|
||||
`requests <https://requests.readthedocs.io/en/master/>`__ and the
|
||||
vast majority of parameters and methods for requests should just work
|
||||
with Locust. Check out the docs and Stack Overflow answers for
|
||||
requests first and then ask on Stack Overflow for additional Locust
|
||||
specific help if necessary.
|
||||
|
||||
Create a Locust file based on a recorded browser session
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Try using `Transformer <https://transformer.readthedocs.io/>`__
|
||||
|
||||
How to run a Docker container of Locust in Windows Subsystem for Linux (Windows 10 users)?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
If you use WSL on a Windows computer, then you need one extra step
|
||||
than the `“docker run …”
|
||||
command <https://docs.locust.io/en/stable/running-locust-docker.html>`__:
|
||||
copy your locusttest1.py to a folder in a Windows path on your WSL
|
||||
and mount that folder instead of your normal WSL folder:
|
||||
|
||||
::
|
||||
|
||||
$ mkdir /c/Users/[YOUR_Windows_USER]/Documents/Locust/
|
||||
$ cp ~/path/to/locusttest1.py /c/Users/[YOUR_Windows_USER]/Documents/Locust/
|
||||
$ docker run -p 8089:8089 -v /c/Users/[YOUR_Windows_USER]/Documents/Locust/:/mnt/locust locustio/locust:1.3.1 -f /mnt/locust/locusttest1.py
|
||||
|
||||
How to run locust on custom endpoint
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Prefix the the endpoint to all ``@app.route`` definitions in
|
||||
``locust/web.py`` file & also change as follows (where ``/locust`` is
|
||||
new endpoint)
|
||||
|
||||
``app = Flask(__name__, static_url_path='/locust')``
|
||||
|
||||
Change the entries of static content location in file
|
||||
``locust/templates/index.html``.
|
||||
|
||||
Eg:
|
||||
``<link rel="shortcut icon" href="{{ url_for('static', filename='img/favicon.ico') }}" type="image/x-icon"/>``
|
||||
|
||||
Locust web UI doesn’t show my tasks running, says 0 RPS
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Locust only knows what you’re doing when you tell it. There are `Event
|
||||
Hooks <https://docs.locust.io/en/stable/api.html#events>`__ that you use
|
||||
to tell Locust what’s going on in your code. If you use Locust’s
|
||||
``HttpUser`` and then use ``self.client`` to make http calls, the proper
|
||||
events are normally fired for you automatically, making less work for
|
||||
you unless you want to override the default events.
|
||||
|
||||
If you use the plain ``User`` or use ``HttpUser`` and you’re not using
|
||||
``self.client`` to make http calls, Locust will not fire events for you.
|
||||
You will have to fire events yourself. See `the Locust
|
||||
docs <https://docs.locust.io/en/stable/testing-other-systems.html>`__
|
||||
for examples.
|
||||
|
||||
HTML Report is filled up with failed requests for long running tests
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
https://github.com/locustio/locust/issues/2328
|
||||
|
||||
Other questions and issues
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
`Check the list of issues (a lot of questions/misunderstandings are
|
||||
filed as
|
||||
issues) <https://github.com/locustio/locust/issues?q=is%3Aissue%20>`__
|
||||
|
||||
Add things that you ran into and solved here! Anyone with a GitHub
|
||||
account can contribute!
|
||||
|
||||
If you have questions about Locust that are not answered here, please
|
||||
check
|
||||
`StackOverflow <https://stackoverflow.com/questions/tagged/locust>`__,
|
||||
or post your question there. This wiki is not for asking questions but
|
||||
for answering them :)
|
||||
|
|
@ -2,13 +2,11 @@
|
|||
Further reading / knowledgebase
|
||||
===============================
|
||||
|
||||
The `Locust wiki <https://github.com/locustio/locust/wiki/>`_ serves as a community maintained knowledgebase for Locust, augmenting the official documentation.
|
||||
- :ref:`extensions`.
|
||||
|
||||
- `Extensions <https://github.com/locustio/locust/wiki/Extensions>`_ Third party extensions and tools
|
||||
- An unmaintained list of Locust `articles, blog posts, reviews, and walkthroughs <https://github.com/orgs/locustio/discussions/2752>`_.
|
||||
|
||||
- `Articles <https://github.com/locustio/locust/wiki/Articles>`_ Blog posts with reviews & walkthroughs of how to run Locust in various use cases
|
||||
|
||||
- `Frequently Asked Questions <https://github.com/locustio/locust/wiki/FAQ>`_ Common questions about Locust answered here
|
||||
- :ref:`Common questions and answers about Locust <faq>`.
|
||||
|
||||
You'll also find a lot of answers on `stackoverflow <https://stackoverflow.com/questions/tagged/locust?sort=MostVotes>`_, for example:
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,28 @@
|
|||
.. _increaserr:
|
||||
|
||||
===========================
|
||||
Increasing the request rate
|
||||
===========================
|
||||
|
||||
Increase the number of requests per second using a combination of the following steps:
|
||||
|
||||
#. Increase the number of users. To fully utilize your target system you may need a lot of simultaneous users, especially if each request takes a long time to complete.
|
||||
|
||||
#. If response times are unexpectedly high and/or increasing as the number of users go up, then you have probably saturated the system you are testing and need to dig into why. This is not really a Locust problem, but here are some things you may want to check:
|
||||
|
||||
- resource utilization (e.g. CPU, memory & network. Check these metrics on the locust side as well)
|
||||
- configuration (e.g. max threads for your web server)
|
||||
- back end response times (e.g. DB)
|
||||
- client side DNS performance/flood protection (Locust will normally make at least one DNS Request per User)
|
||||
|
||||
#. If Locust prints a warning about high CPU usage (``WARNING/root: CPU usage above 90%! ...``) try the following:
|
||||
|
||||
- Run Locust `distributed <https://docs.locust.io/en/stable/running-locust-distributed.html>`__ to utilize multiple cores & multiple machines
|
||||
- Try switching to `FastHttpUser <https://docs.locust.io/en/stable/increase-performance.html#increase-performance>`__ to reduce CPU usage
|
||||
- Check to see that there are no strange/infinite loops in your code
|
||||
|
||||
#. If you are using a custom client (not HttpUser or FastHttpUser), make sure any client library you are using is gevent-friendly otherwise it will block the entire Python process (essentially limiting you to one user per worker)
|
||||
|
||||
.. note::
|
||||
|
||||
Hatch rate/ramp up does not change peak load, it only changes how fast you get there.
|
||||
|
|
@ -30,6 +30,7 @@ Running your Locust tests
|
|||
:maxdepth: 1
|
||||
|
||||
configuration
|
||||
increasing-request-rate
|
||||
running-distributed
|
||||
running-in-debugger
|
||||
running-in-docker
|
||||
|
|
@ -49,6 +50,7 @@ Other functionalities
|
|||
extending-locust
|
||||
logging
|
||||
use-as-lib
|
||||
extensions
|
||||
|
||||
|
||||
Further reading / knowledgebase
|
||||
|
|
@ -59,6 +61,7 @@ Further reading / knowledgebase
|
|||
|
||||
developing-locust
|
||||
further-reading
|
||||
faq
|
||||
|
||||
|
||||
API
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ Installation
|
|||
|
||||
0. `Install Python <https://docs.python-guide.org/starting/installation/>`_ (3.9 or later)
|
||||
|
||||
1. Install the package (check `the wiki <https://github.com/locustio/locust/wiki/Installation>`_ if the installation fails)
|
||||
1. Install the package (check `Troubleshooting Installation`_ if the installation fails)
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
|
|
@ -37,3 +37,67 @@ Install for development
|
|||
-----------------------
|
||||
|
||||
If you want to modify Locust, or contribute to the project, see :ref:`developing-locust`.
|
||||
|
||||
Troubleshooting installation
|
||||
----------------------------
|
||||
|
||||
|
||||
.. contents:: Some solutions for common installation issues
|
||||
:depth: 1
|
||||
:local:
|
||||
:backlinks: none
|
||||
|
||||
|
||||
psutil/\_psutil_common.c:9:10: fatal error: Python.h: No such file or directory
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
`Answered in Stackoverflow thread 63440765 <https://stackoverflow.com/questions/63440765/locust-installation-error-using-pip3-error-command-errored-out-with-exit-statu>`_
|
||||
|
||||
ERROR: Failed building wheel for xxx
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
While Locust itself is a pure Python package, it has some dependencies
|
||||
(e.g. gevent and geventhttpclient) that are compiled from C code. Pretty
|
||||
much all common platforms have binary packages on PyPi, but sometimes
|
||||
there is a new release that doesn't, or you are running on some exotic
|
||||
platform. You have two options:
|
||||
|
||||
- (on macos) Install xcode: ``xcode-select --install``
|
||||
- Use ``pip install --prefer-binary locust`` to select a pre-compiled
|
||||
version of packages even if there is a more recent version available
|
||||
as source.
|
||||
- Try googling the error message for the specific package that failed
|
||||
(not Locust), ensure you have the appropriate build tools installed
|
||||
etc.
|
||||
|
||||
Windows
|
||||
~~~~~~~
|
||||
|
||||
`Answered in Stackoverflow thread 61592069 <https://stackoverflow.com/questions/61592069/locust-is-not-installing-on-my-windows-10-for-load-testing>`_
|
||||
|
||||
Installation works, but the ``locust`` command is not found
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
When running pip, did you get a warning saying ``The script locust is installed in '...' which is not on PATH``?
|
||||
|
||||
Add that directory to your PATH environment variable.
|
||||
|
||||
Increasing Maximum Number of Open Files Limit
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Every User/HTTP connection from Locust opens a new file (technically
|
||||
a file descriptor). Many operating systems by default set a low limit
|
||||
for the maximum number of files that can be open at the same time.
|
||||
Locust will try to adjust this automatically for you, but in a lot of
|
||||
cases your operating system will not allow it (in which case you will
|
||||
get a warning in the log). Instead you will have to do it manually.
|
||||
|
||||
How to do this depends on your operating system, but you might find
|
||||
some useful information here:
|
||||
https://www.tecmint.com/increase-set-open-file-limits-in-linux/ and
|
||||
practical examples
|
||||
https://www.ibm.com/support/knowledgecenter/SS8NLW_11.0.2/com.ibm.discovery.es.in.doc/iiysiulimits.html
|
||||
|
||||
For systemd-based systems (e.g. Debian/Ubuntu) different limits are
|
||||
used for graphical login sessions. See
|
||||
https://unix.stackexchange.com/a/443467 for additional settings.
|
||||
|
|
|
|||
|
|
@ -56,7 +56,7 @@ The following screenshots show what it might look like when running this test us
|
|||
|
||||
If your response times are *not* increasing then add even more users until you find the service's breaking point, or celebrate that your service is already performant enough for your expected load.
|
||||
|
||||
If you need some help digging into server side problems, or you're having trouble generating enough load to saturate your system, take a look at the `Locust FAQ <https://github.com/locustio/locust/wiki/FAQ#increase-my-request-raterps>`_.
|
||||
If you're having trouble generating enough load to saturate your system, take a look at :ref:`increaserr`.
|
||||
|
||||
Direct command line usage / headless
|
||||
====================================
|
||||
|
|
@ -89,7 +89,7 @@ To run Locust distributed across multiple Python processes or machines, you star
|
|||
with the ``--master`` command line parameter, and then any number of Locust worker processes using the ``--worker``
|
||||
command line parameter. See :ref:`running-distributed` for more info.
|
||||
|
||||
To see all available options type: ```locust --help`` or check :ref:`configuration`.
|
||||
To see all available options type: ``locust --help`` or check :ref:`configuration`.
|
||||
|
||||
Next steps
|
||||
==========
|
||||
|
|
|
|||
|
|
@ -18,7 +18,7 @@ To simplify startup, you can use the ``--processes`` flag. It will launch a mast
|
|||
.. note::
|
||||
There is almost no limit to how many Users you can run per worker. Locust/gevent can run thousands or even tens of thousands of Users per process just fine, as long as their total request rate (RPS) is not too high.
|
||||
|
||||
If Locust *is* getting close to running out of CPU resources, it will log a warning. If there is no warning but you are still unable to generate the expected load, then the problem must be `something else <https://github.com/locustio/locust/wiki/FAQ#increase-my-request-raterps>`_.
|
||||
If Locust *is* getting close to running out of CPU resources, it will log a warning. If there is no warning but you are still unable to generate the expected load, then the problem must be :ref:`increaserr`.
|
||||
|
||||
Single machine
|
||||
==============
|
||||
|
|
|
|||
|
|
@ -38,4 +38,4 @@ official Locust docker image as a base image::
|
|||
Running Locust using Kubernetes
|
||||
===============================
|
||||
|
||||
See [Extensions](https://github.com/locustio/locust/wiki/Extensions#helm) in the wiki.
|
||||
See :ref:`Helm charts for Locust <helm>`
|
||||
Loading…
Reference in New Issue