locust 2.24.2.dev19__tar.gz → 2.25.0__tar.gz

{locust-2.24.2.dev19 → locust-2.25.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: locust
-Version: 2.24.2.dev19
+Version: 2.25.0
 Summary: Developer friendly load testing framework
 License: MIT
 Project-URL: Homepage, https://github.com/locustio/locust

{locust-2.24.2.dev19 → locust-2.25.0}/docs/changelog.rst

@@ -4,6 +4,13 @@ Changelog Highlights
 
 For full details of the Locust changelog, please see https://github.com/locustio/locust/blob/master/CHANGELOG.md
 
+2.25.0
+======
+* Add functionality to run listener functions for `custom_messages` concurrently (https://github.com/locustio/locust/pull/2650)
+* Update User Classes in Distributed Mode (https://github.com/locustio/locust/pull/2666)
+* Log deprecation warning for --legacy-ui (https://github.com/locustio/locust/pull/2670)
+* Fix UserClasses weight distribution with gcd (https://github.com/locustio/locust/pull/2663)
+
 2.24.1
 ======
 * Some documentation updates & minor fixes to UI

{locust-2.24.2.dev19 → locust-2.25.0}/docs/extending-locust.rst

@@ -53,6 +53,7 @@ To see a full list of available events see :ref:`events`.
 
 .. _request_context:
 
+
 Request context
 ===============
 
@@ -110,6 +111,10 @@ to the Flask app instance and use that to set up a new route::
 
 You should now be able to start locust and browse to http://127.0.0.1:8089/added_page
 
+.. note::
+
+    Please note that at the moment Locust does not show the extended Web UI under the default root path `"/"`. 
+    To view your extensions, navigate to the newly added web route. In this example, `"/added_page"`.
 
 
 Extending Web UI
@@ -123,9 +128,14 @@ as it involves also writing and including HTML and Javascript files to be served
 greatly enhance the utility and customizability of the web UI.
 
 A working example of extending the web UI, complete with HTML and Javascript example files, can be found
-in the `examples directory <https://github.com/locustio/locust/tree/master/examples>`_ of the Locust
+in the `examples directory <https://github.com/locustio/locust/tree/master/examples/>`_ of the Locust
 source code.
 
+*  ``extend_modern_web_ui.py``: Display a table with content-length for each call.
+
+* ``web_ui_cache_stats.py``: Display Varnish Hit/ Miss stats for each call. Could be easly extended to other CDN or cache proxies and gather other cache statistics such as cache age, control, ...
+
+ .. image:: images/extend_modern_web_ui_cache_stats.png
 
 
 Adding Authentication to the Web UI
@@ -149,8 +159,6 @@ authentication to the app should be granted.
 A full example can be seen `in the auth example <https://github.com/locustio/locust/tree/master/examples/web_ui_auth.py>`_.
 
 
-
-
 Run a background greenlet
 =========================
 
@@ -182,6 +190,7 @@ For example, you can monitor the fail ratio of your test and stop the run if it
 
 .. _parametrizing-locustfiles:
 
+
 Parametrizing locustfiles
 =========================
 
@@ -224,11 +233,13 @@ You can add your own command line arguments to Locust, using the :py:attr:`init_
 
 When running Locust :ref:`distributed <running-distributed>`, custom arguments are automatically forwarded to workers when the run is started (but not before then, so you cannot rely on forwarded arguments *before* the test has actually started).
 
+
 Test data management
 ====================
 
 There are a number of ways to get test data into your tests (after all, your test is just a Python program and it can do whatever Python can). Locust's events give you fine-grained control over *when* to fetch/release test data. You can find a `detailed example here <https://github.com/locustio/locust/tree/master/examples/test_data_management.py>`_.
 
+
 More examples
 =============
 

{locust-2.24.2.dev19 → locust-2.25.0}/docs/quickstart.rst

@@ -16,7 +16,7 @@ A Locust test is essentially just a Python program making requests to the system
             self.client.get("/hello")
             self.client.get("/world")
 
-This user will make HTTP requests to ``/hello``, and then ``/world``, again and again. For a full explanation and a more realistic example see :ref:`writing-a-locustfile`.
+This user will make an HTTP request to ``/hello``, and after that to ``/world``, and then repeat. For a full explanation and a more realistic example see :ref:`writing-a-locustfile`.
 
 Change ``/hello`` and ``/world`` to some actual paths on the web site/service you want to test, put the code in a file named ``locustfile.py`` in your current directory and then run ``locust``:
 
@@ -24,7 +24,7 @@ Change ``/hello`` and ``/world`` to some actual paths on the web site/service yo
     :substitutions:
 
     $ locust
-    [2021-07-24 09:58:46,215] .../INFO/locust.main: Starting web interface at http://*:8089
+    [2021-07-24 09:58:46,215] .../INFO/locust.main: Starting web interface at http://0.0.0.0:8089
     [2021-07-24 09:58:46,285] .../INFO/locust.main: Starting Locust |version|
 
 Locust's web interface

{locust-2.24.2.dev19 → locust-2.25.0}/docs/writing-a-locustfile.rst

@@ -62,28 +62,30 @@ is executed. For more info see :ref:`wait-time`.
 
     @task
     def hello_world(self):
-        ...
+        self.client.get("/hello")
+        self.client.get("/world")
 
-Methods decorated with ``@task`` are the core of your locust file. For every running user,
-Locust creates a greenlet (micro-thread), that will call those methods.
+Methods decorated with ``@task`` are the core of your locust file. For every running User,
+Locust creates a `greenlet <https://greenlet.readthedocs.io/en/stable/greenlet.html>`_ (a coroutine or "micro-thread"), that will call those methods. 
+Code within a task is executed sequentially (it is just regular Python code),
+so ``/world`` wont be called until the response from ``/hello`` has been received.
 
 .. code-block:: python
 
     @task
     def hello_world(self):
-        self.client.get("/hello")
-        self.client.get("/world")
-
+        ...
+    
     @task(3)
     def view_items(self):
-    ...
+        ...
 
 We've declared two tasks by decorating two methods with ``@task``, one of which has been given a higher weight (3).
 When our ``QuickstartUser`` runs it'll pick one of the declared tasks - in this case either ``hello_world`` or
 ``view_items`` - and execute it. Tasks are picked at random, but you can give them different weighting. The above
 configuration will make Locust three times more likely to pick ``view_items`` than ``hello_world``. When a task has
-finished executing, the User will then sleep during its wait time (in this case between 1 and 5 seconds).
-After its wait time it'll pick a new task and keep repeating that.
+finished executing, the User will then sleep for its specified wait time (in this case between 1 and 5 seconds).
+Then it will pick a new task.
 
 Note that only methods decorated with ``@task`` will be picked, so you can define your own internal helper methods any way you like.
 

{locust-2.24.2.dev19 → locust-2.25.0}/examples/extend_web_ui/extend.py

@@ -9,9 +9,16 @@ from locust import HttpUser, TaskSet, between, events, task, web
 import os
 from html import escape
 from time import time
+from warnings import warn
 
 from flask import Blueprint, jsonify, make_response, render_template
 
+warn(
+    "This UI example is deprecated, please downgrade to Locust 2.21.0 or use --legacy-ui flag ; version=2.22.0",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
 
 class MyTaskSet(TaskSet):
     @task(2)

locust-2.25.0/examples/web_ui_cache_stats.py

@@ -0,0 +1,210 @@
+"""
+This is an example of a locustfile that uses Locust's built in event and web
+UI extension hooks to track the sum of Varnish cache hit/miss headers
+and display them in the web UI.
+"""
+
+from locust import HttpUser, TaskSet, between, events, task, web
+
+import json
+import os
+from html import escape
+from time import time
+
+from flask import Blueprint, jsonify, make_response, render_template, request
+
+
+class MyTaskSet(TaskSet):
+    @task(1)
+    def miss(l):
+        """MISS X-Cache header"""
+        l.client.get("/response-headers?X-Cache=MISS")
+
+    @task(2)
+    def hit(l):
+        """HIT X-Cache header"""
+        l.client.get("/response-headers?X-Cache=HIT")
+
+    @task(1)
+    def noinfo(l):
+        """No X-Cache header (noinfo counter)"""
+        l.client.get("/")
+
+
+class WebsiteUser(HttpUser):
+    host = "http://httpbin.org"
+    wait_time = between(2, 5)
+    tasks = [MyTaskSet]
+
+
+# This example is based on the Varnish hit/miss headers (https://docs.varnish-software.com/tutorials/hit-miss-logging/).
+# It could easly be customised for matching other caching sytems, CDN or custom headers.
+CACHE_HEADER = "X-Cache"
+
+cache_stats = {}
+
+page_stats = {"hit": 0, "miss": 0, "noinfo": 0}
+
+path = os.path.dirname(os.path.abspath(__file__))
+extend = Blueprint(
+    "extend",
+    "extend_web_ui",
+    static_folder=f"{path}/static/",
+    static_url_path="/extend/static/",
+    template_folder=f"{path}/templates/",
+)
+
+
+@events.init.add_listener
+def locust_init(environment, **kwargs):
+    """
+    Load data on locust init.
+    :param environment:
+    :param kwargs:
+    :return:
+    """
+
+    if environment.web_ui:
+        # this code is only run on the master node (the web_ui instance doesn't exist on workers)
+
+        def get_cache_stats():
+            """
+            This is used by the Cache tab in the
+            extended web UI to show the stats.
+            """
+            if cache_stats:
+                stats_tmp = []
+
+                for name, inner_stats in cache_stats.items():
+                    stats_tmp.append(
+                        {
+                            "name": name,
+                            "safe_name": escape(name, quote=False),
+                            "hit": inner_stats["hit"],
+                            "miss": inner_stats["miss"],
+                            "noinfo": inner_stats["noinfo"],
+                        }
+                    )
+
+                # Truncate the total number of stats and errors displayed since a large number
+                # of rows will cause the app to render extremely slowly.
+                return stats_tmp[:500]
+            return cache_stats
+
+        @environment.web_ui.app.after_request
+        def extend_stats_response(response):
+            if request.path != "/stats/requests":
+                return response
+
+            # extended_stats contains the data where extended_tables looks for its data: "cache-statistics"
+            response.set_data(
+                json.dumps(
+                    {**response.json, "extended_stats": [{"key": "cache-statistics", "data": get_cache_stats()}]}
+                )
+            )
+
+            return response
+
+        @extend.route("/extend")
+        def extend_web_ui():
+            """
+            Add route to access the extended web UI with our new tab.
+            """
+            # ensure the template_args are up to date before using them
+            environment.web_ui.update_template_args()
+            # set the static paths to use the modern ui
+            environment.web_ui.set_static_modern_ui()
+
+            return render_template(
+                "index.html",
+                template_args={
+                    **environment.web_ui.template_args,
+                    # extended_tabs and extended_tables keys must match.
+                    "extended_tabs": [{"title": "Cache statistics", "key": "cache-statistics"}],
+                    "extended_tables": [
+                        {
+                            "key": "cache-statistics",
+                            "structure": [
+                                {"key": "name", "title": "Name"},
+                                {"key": "hit", "title": "Hit"},
+                                {"key": "miss", "title": "Miss"},
+                                {"key": "noinfo", "title": "No Info"},
+                            ],
+                        }
+                    ],
+                    "extended_csv_files": [{"href": "/cache/csv", "title": "Download Cache statistics CSV"}],
+                },
+            )
+
+        @extend.route("/cache/csv")
+        def request_cache_csv():
+            """
+            Add route to enable downloading of cache stats as CSV
+            """
+            response = make_response(cache_csv())
+            file_name = f"cache-{time()}.csv"
+            disposition = f"attachment;filename={file_name}"
+            response.headers["Content-type"] = "text/csv"
+            response.headers["Content-disposition"] = disposition
+            return response
+
+        def cache_csv():
+            """Returns the cache stats as CSV."""
+            rows = [",".join(['"Name"', '"hit"', '"miss"', '"noinfo"'])]
+
+            if cache_stats:
+                for name, stats in cache_stats.items():
+                    rows.append(f'"{name}",' + ",".join(str(v) for v in stats.values()))
+            return "\n".join(rows)
+
+        # register our new routes and extended UI with the Locust web UI
+        environment.web_ui.app.register_blueprint(extend)
+
+
+@events.request.add_listener
+def on_request(name, response, exception, **kwargs):
+    """
+    Event handler that get triggered on every request
+    """
+
+    cache_stats.setdefault(name, page_stats.copy())
+
+    if CACHE_HEADER not in response.headers:
+        cache_stats[name]["noinfo"] += 1
+    elif response.headers[CACHE_HEADER] == "HIT":
+        cache_stats[name]["hit"] += 1
+    elif response.headers[CACHE_HEADER] == "MISS":
+        cache_stats[name]["miss"] += 1
+
+
+@events.report_to_master.add_listener
+def on_report_to_master(client_id, data):
+    """
+    This event is triggered on the worker instances every time a stats report is
+    to be sent to the locust master. It will allow us to add our extra cache
+    data to the dict that is being sent, and then we clear the local stats in the worker.
+    """
+    global cache_stats
+    data["cache_stats"] = cache_stats
+    cache_stats = {}
+
+
+@events.worker_report.add_listener
+def on_worker_report(client_id, data):
+    """
+    This event is triggered on the master instance when a new stats report arrives
+    from a worker. Here we just add the cache to the master's aggregated stats dict.
+    """
+    for name in data["cache_stats"]:
+        cache_stats.setdefault(name, page_stats.copy())
+        for stat_name, value in data["cache_stats"][name].items():
+            cache_stats[name][stat_name] += value
+
+
+@events.reset_stats.add_listener
+def on_reset_stats():
+    """
+    Event handler that get triggered on click of web UI Reset Stats button
+    """
+    global cache_stats
+    cache_stats = {}

{locust-2.24.2.dev19 → locust-2.25.0}/locust/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '2.24.2.dev19'
-__version_tuple__ = version_tuple = (2, 24, 2, 'dev19')
+__version__ = version = '2.25.0'
+__version_tuple__ = version_tuple = (2, 25, 0)

{locust-2.24.2.dev19 → locust-2.25.0}/locust/dispatch.py

@@ -1,8 +1,10 @@
 from __future__ import annotations
 
 import contextlib
+import functools
 import itertools
 import math
+import sys
 import time
 from collections import defaultdict
 from operator import attrgetter
@@ -16,6 +18,20 @@ if TYPE_CHECKING:
     from locust.runners import WorkerNode
 
 
+def compatible_math_gcd(*args: int) -> int:
+    """
+    This function is a workaround for the fact that `math.gcd` in:
+        - 3.5 <= Python < 3.9   doesn't accept more than two arguments.
+        - 3.9 <= Python         can accept more than two arguments.
+    See more at https://docs.python.org/3.9/library/math.html#math.gcd
+    """
+    if (3, 5) <= sys.version_info < (3, 9):
+        return functools.reduce(math.gcd, args)
+    elif sys.version_info >= (3, 9):
+        return math.gcd(*args)
+    raise NotImplementedError("This function is only implemented for Python from 3.5")
+
+
 # To profile line-by-line, uncomment the code below (i.e. `import line_profiler ...`) and
 # place `@profile` on the functions/methods you wish to profile. Then, in the unit test you are
 # running, use `from locust.dispatch import profile; profile.print_stats()` at the end of the unit test.
@@ -366,18 +382,37 @@ class UsersDispatcher(Iterator):
             if not users:
                 return itertools.cycle([None])
 
-            # Normalize the weights so that the smallest weight will be equal to "target_min_weight".
-            # The value "2" was experimentally determined because it gave a better distribution especially
-            # when dealing with weights which are close to each others, e.g. 1.5, 2, 2.4, etc.
-            target_min_weight = 2
-
-            # 'Value' here means weight or fixed count
+            def _get_order_of_magnitude(n: float) -> int:
+                """Get how many times we need to multiply `n` to get an integer-like number.
+                For example:
+                    0.1 would return 10,
+                    0.04 would return 100,
+                    0.0007 would return 10000.
+                """
+                if n <= 0:
+                    raise ValueError("To get the order of magnitude, the number must be greater than 0.")
+
+                counter = 0
+                while n < 1:
+                    n *= 10
+                    counter += 1
+                return 10**counter
+
+            # Get maximum order of magnitude to "normalize the weights".
+            # "Normalizing the weights" is to multiply all weights by the same number so that
+            # they become integers. Then we can find the largest common divisor of all the
+            # weights, divide them by it and get the smallest possible numbers with the same
+            # ratio as the numbers originally had.
+            max_order_of_magnitude = _get_order_of_magnitude(min(abs(u[1]) for u in users))
+            weights = tuple(int(u[1] * max_order_of_magnitude) for u in users)
+
+            greatest_common_divisor = compatible_math_gcd(*weights)
             normalized_values = [
                 (
-                    user.__name__,
-                    round(target_min_weight * value / min(u[1] for u in users)),
+                    user[0].__name__,
+                    normalized_weight // greatest_common_divisor,
                 )
-                for user, value in users
+                for user, normalized_weight in zip(users, weights)
             ]
             generation_length_to_get_proper_distribution = sum(
                 normalized_val[1] for normalized_val in normalized_values

{locust-2.24.2.dev19 → locust-2.25.0}/locust/test/test_dispatch.py

@@ -847,6 +847,75 @@ class TestRampUpUsersFromZero(unittest.TestCase):
         delta = time.perf_counter() - ts
         self.assertTrue(0 <= delta <= _TOLERANCE, delta)
 
+    def test_implementation_of_dispatch_distribution_with_gcd(self):
+        class User1(User):
+            weight = 4
+
+        class User2(User):
+            weight = 5
+
+        user_classes = [User1, User2]
+        worker_node1 = WorkerNode("1")
+
+        sleep_time = 0.2  # Speed-up test
+
+        users_dispatcher = UsersDispatcher(worker_nodes=[worker_node1], user_classes=user_classes)
+        users_dispatcher.new_dispatch(target_user_count=9, spawn_rate=9)
+
+        users_dispatcher._wait_between_dispatch = sleep_time
+
+        ts = time.perf_counter()
+        self.assertDictEqual(
+            next(users_dispatcher),
+            {
+                "1": {"User1": 4, "User2": 5},
+            },
+        )
+        delta = time.perf_counter() - ts
+        self.assertTrue(0 <= delta <= _TOLERANCE, delta)
+
+        ts = time.perf_counter()
+        self.assertRaises(StopIteration, lambda: next(users_dispatcher))
+        delta = time.perf_counter() - ts
+        self.assertTrue(0 <= delta <= _TOLERANCE, delta)
+
+    def test_implementation_of_dispatch_distribution_with_gcd_float_weight(self):
+        class User1(User):
+            weight = 0.8
+
+        class User2(User):
+            weight = 1
+
+        normalized_weights_to_min_int = 5  # User1: 0.8 * 5 = 4; User2: 1 * 5 = 5
+
+        user_classes = [User1, User2]
+        worker_node1 = WorkerNode("1")
+
+        sleep_time = 0.2  # Speed-up test
+
+        users_dispatcher = UsersDispatcher(worker_nodes=[worker_node1], user_classes=user_classes)
+        users_dispatcher.new_dispatch(target_user_count=18, spawn_rate=18)
+
+        users_dispatcher._wait_between_dispatch = sleep_time
+
+        ts = time.perf_counter()
+        self.assertDictEqual(
+            next(users_dispatcher),
+            {
+                "1": {
+                    "User1": int(normalized_weights_to_min_int * User1.weight * 2),
+                    "User2": int(normalized_weights_to_min_int * User2.weight * 2),
+                },
+            },
+        )
+        delta = time.perf_counter() - ts
+        self.assertTrue(0 <= delta <= _TOLERANCE, delta)
+
+        ts = time.perf_counter()
+        self.assertRaises(StopIteration, lambda: next(users_dispatcher))
+        delta = time.perf_counter() - ts
+        self.assertTrue(0 <= delta <= _TOLERANCE, delta)
+
 
 class TestWaitBetweenDispatch(unittest.TestCase):
     def test_wait_between_dispatch(self):

{locust-2.24.2.dev19 → locust-2.25.0}/locust.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: locust
-Version: 2.24.2.dev19
+Version: 2.25.0
 Summary: Developer friendly load testing framework
 License: MIT
 Project-URL: Homepage, https://github.com/locustio/locust

{locust-2.24.2.dev19 → locust-2.25.0}/locust.egg-info/SOURCES.txt

@@ -55,6 +55,7 @@ docs/use-as-lib.rst
 docs/what-is-locust.rst
 docs/writing-a-locustfile.rst
 docs/_static/theme-overrides.css
+docs/images/extend_modern_web_ui_cache_stats.png
 docs/images/locust_workers.png
 docs/images/number_of_users.png
 docs/images/response_times.png
@@ -84,6 +85,7 @@ examples/stop_on_threshold.py
 examples/test_data_management.py
 examples/use_as_lib.py
 examples/web_ui_auth.py
+examples/web_ui_cache_stats.py
 examples/worker_index.py
 examples/custom_shape/double_wave.py
 examples/custom_shape/stages.py