Merge pull request #1355 from locustio/env-vars-config

Environment variable configuration changes

.gitignore

@@ -4,6 +4,7 @@ locust.egg-info/**
 locustio.egg-info/**
 docs/_build/**
 docs/cli-help-output.txt
+docs/env-options.rst
 mock.*.egg
 dist/**
 .idea/**

docs/changelog.rst

@@ -45,6 +45,20 @@ attribute instead:
         tasks = [MyTaskSet]
 
 
+Environment variables changed
+-----------------------------
+
+The following changes has been made to the configuration environment variables
+
+* ``LOCUST_MASTER`` has been renamed to ``LOCUST_MODE_MASTER`` (in order to make it less likely to get variable name collisions 
+  when running Locust in Kubernetes/K8s which automatically adds environment variables depending on service/pod names).
+* ``LOCUST_SLAVE`` has been renamed to ``LOCUST_MODE_WORKER``.
+* ``LOCUST_MASTER_PORT`` has been renamed to ``LOCUST_MASTER_NODE_PORT``.
+* ``LOCUST_MASTER_HOST`` has been renamed to ``LOCUST_MASTER_NODE_HOST``.
+* ``CSVFILEBASE`` has been renamed to ``LOCUST_CSV``.
+
+See the :ref:`configuration` documentation for a full list of available :ref:`environment variables <environment-variables>`.
+
 
 Other breaking changes
 ----------------------
@@ -70,6 +84,7 @@ Other breaking changes
 * The official docker image no longer uses a shell script with a bunch of special environment variables to configure how 
   how locust is started. Instead, the ``locust`` command is now set as ``ENTRYPOINT`` of the docker image. See
   :ref:`running-locust-docker` for more info.
+* Command line option ``--csv-base-name`` has been removed, since it was just an alias for ``--csv``.
 
 
 Other fixes and improvements

docs/conf.py

@@ -11,14 +11,50 @@
 import os
 import subprocess
 
+from locust.argument_parser import get_empty_argument_parser, setup_parser_arguments
 
 
 # Run command `locust --help` and store output in cli-help-output.txt which is included in the docs
-cli_help_output_file = os.path.join(os.path.abspath(os.path.dirname(__file__)), "cli-help-output.txt")
-print("Running `locust --help` command and storing output in %s" % cli_help_output_file)
-help_output = subprocess.check_output(["locust", "--help"]).decode("utf-8")
-with open(cli_help_output_file, "w") as f:
-    f.write(help_output)
+def save_locust_help_output():
+    cli_help_output_file = os.path.join(os.path.abspath(os.path.dirname(__file__)), "cli-help-output.txt")
+    print("Running `locust --help` command and storing output in %s" % cli_help_output_file)
+    help_output = subprocess.check_output(["locust", "--help"]).decode("utf-8")
+    with open(cli_help_output_file, "w") as f:
+        f.write(help_output)
+
+save_locust_help_output()
+
+# Generate RST table with help/descriptions for all available environment variables
+def save_locust_env_variables():
+    env_options_output_file = os.path.join(os.path.abspath(os.path.dirname(__file__)), "env-options.rst")
+    print("Generating RST table for Locust environment variables and storing in %s" % env_options_output_file)
+    parser = get_empty_argument_parser()
+    setup_parser_arguments(parser)
+    table_data = []
+    for action in parser._actions:
+        if action.env_var:
+            table_data.append((
+                action.env_var, 
+                ", ".join(["``%s``" % c for c in action.option_strings]), 
+                action.help,
+            ))
+    colsizes = [max(len(r[i]) for r in table_data) for i in range(len(table_data[0]))]
+    formatter = ' '.join('{:<%d}' % c for c in colsizes)
+    rows = [formatter.format(*row) for row in table_data]
+    edge = formatter.format(*['=' * c for c in colsizes])
+    divider = formatter.format(*['-' * c for c in colsizes])
+    headline = formatter.format(*["Name", "Command line option", "Description"])
+    output = "\n".join([
+        edge,
+        headline,
+        divider,
+        "\n".join(rows),
+        edge,
+    ])
+    with open(env_options_output_file, "w") as f:
+        f.write(output)
+
+save_locust_env_variables()
 
 
 # The default replacements for |version| and |release|, also used in various

docs/configuration.rst

@@ -0,0 +1,29 @@
+.. _configuration:
+
+Configuration
+=============
+
+
+Command Line Options
+-----------------------------
+
+The most straight forward way to Configure how Locust is run is through command line options. 
+
+.. code-block:: console
+
+    $ locust --help
+
+.. literalinclude:: cli-help-output.txt
+    :language: console
+
+
+
+.. _environment-variables:
+
+Environment variables
+---------------------
+
+Most of the configuration that can be set through command line arguments can also be set through 
+environment variables. Here's a table of all the available environment variables:
+
+.. include:: env-options.rst

docs/index.rst

@@ -39,6 +39,7 @@ Running your Locust tests
 .. toctree ::
     :maxdepth: 1
 
+    configuration
     running-locust-distributed
     running-locust-docker
     running-locust-without-web-ui

docs/quickstart.rst

@@ -144,22 +144,21 @@ host defaults to 127.0.0.1):
     $ locust -f locust_files/my_locust_file.py --worker --master-host=192.168.0.100
 
 
-Parameters can also be set in a `config file <https://github.com/bw2/ConfigArgParse#config-file-syntax>`_ (locust.conf or ~/.locust.conf) or in env vars, prefixed by LOCUST\_
+Parameters can also be set as :ref:`environment variables <environment-variables>`, or in a 
+`config file <https://github.com/bw2/ConfigArgParse#config-file-syntax>`_ (``locust.conf`` or ``~/.locust.conf``).
 
 For example: (this will do the same thing as the previous command)
 
+.. code-block:: console
+
+    $ LOCUST_MASTER_NODE_HOST=192.168.0.100 locust
+
 .. code-block::
 
     # locust.conf in current directory
     locustfile locust_files/my_locust_file.py
     worker
 
-
-.. code-block:: console
-
-    $ LOCUST_MASTER_HOST=192.168.0.100 locust
-
-
 .. note::
 
     To see all available options type: ``locust --help``
@@ -175,12 +174,7 @@ greeted with something like this:
 .. image:: images/webui-splash-screenshot.png
 
 
-Locust Command Line Interface
-=============================
-
-.. code-block:: console
-
-    $ locust --help
+Locust Command Line Interface & Configuration
+=============================================
 
-.. literalinclude:: cli-help-output.txt
-    :language: console
+For a full list of available command line options see :ref:`configuration`.